3DS authentication

3D Secure (3DS) is an authentication protocol for online card payments defined and managed by EMVCo. The name refers to the "three domains" which interact using the protocol: the merchant/acquirer domain, the issuer domain, and the interoperability domain. It reduces the risk of fraud by ensuring the card is used by its true holder through multi-factor authentication.

3D Secure authentication is optional. You must flag transactions (details below) in order to not attempt 3D secure on them (for example if you experience any challenges during the authentication process). However, even if a transaction is not flagged, the final decision is done by PSP, in case it doesn’t support or require 3D Secure for particular transaction based on the exemptions criteria.

3DS version is controlled by the gateway. Current version mandated by the schemes is 3DS 2.0 with a few exceptions.

When does it apply?

For the 3DS protocol to apply, the following conditions must be met:

  • Customer-initiated transaction (CIT) – This means that the user is online when the payment is made (as opposed to an MIT
  • Processed with cards from the major networks (CB, Visa, Mastercard, Maestro, AMEX, etc.)


Examples of transactions for which challenge doesn’t apply

  • Merchant-initiated transactions (e.g., subscriptions, installments)
  • Mail and telephone order (MOTO)

When is it triggered?

3DS challenge is triggered by default for all eligible transactions unless specified otherwise.

To force 3DS challenge the following parameter should be used: threeds.enabled: true

To skip 3DS challenge the following parameter should be used: threeds.enabled: false

How does it work?

In case all the conditions for 3DS authentication met and PSP requests for a challenge completion, you will receive the response with Operation status "PENDING_AUTHENTICATION" and authentication_embed_url to initiate the challenge:

  "status": {
    "code": 200,
    "message": "success",
    "errors": []
  "data": {
    "operation_data": {
      "authentication_embed_url": "https://stg-embed.moneyhash.io/embed/payment/ZDnDrbL",
      "intent": {
        "id": "ZDnDrbL",
        "created": "2023-08-09 07:04:10.672479+00:00",
        "custom_fields": null,
        "split_data": [],
        "custom_form_answers": null,
        "amount": {
          "value": 50,
          "currency": "USD"
      "account": {
        "id": "YVglAZx"
      "api_version": "1.1"
  "count": 1,
  "next": null,
  "previous": null

3DS Results

3DS details received from the provider are included into the "provider_transaction_fields" on request for particular provider. Please contact our customer support in case you need it to be enabled for specific provider.

Test Cards

STATUSCard NumberExpiry DateCVV
AUTHENTICATION REQUIRED0000222222222222any future expiry dateany valid CVV (three-digit number)