3DS Implementation

3DS Integration

To integrate 3DS with the Direct Payment approach (without being redirected to OrkestaPay’s checkout), follow these steps:

1. Direct Payment Integration

2. 3DS Flow Integration

3. Complete Payment for Global 3DS

Preconditions

• Have an orchestration route configured with a 3DS provider.

• Initialize OrkestaPay’s CDN on the frontend.

Direct Payment Integration

Follow the Payment Integration. In step 4, when registering the payment, send the redirection_url object with the URLs for successful or canceled 3DS authentication scenarios.

If the response status is PAYMENT_ACTION_REQUIRED, the 3D Secure challenge needs to be executed.

curl --request POST \
     --url https://api.sand.orkestapay.com/v1/payments \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Idempotency-Key: adffaf7a3141474555d988fbb5e43e85' \
     --header 'Authorization: Bearer REPLACE_WITH_YOUR_ACCESS_TOKEN' \
     --data '
{
  "payment_source": {
     "type" : "CARD",
     "payment_method_id": "{{REPLACE_WITH_CARD_TOKEN}}",
     "settings": {
       "card": {
         "capture":true
       },
       "redirection_url": {
         "completed_redirect_url": "https://tu.dominio.com/status?result=COMPLETED",
         "canceled_redirect_url": "https://tu.dominio.com/status?result=CANCELED"
       }
     }
   },
   "device_session_id": "{{REPLACE_WITH_DEVICE_SESSION_ID}}",
   "order_id": "{{REPLACE_WITH_ORDER_ID}}"
}
'

NOTE: The type of 3DS will depend on the payment processor(s) configuration you have enabled in your orchestration path.

Global 3D Secure

To validate that the 3D Secure type is global, check the user_action_required object for the property type with the value THREE_D_SECURE_AUTHENTICATION. If present, another object three_d_secure_authentication contains an ID in the merchant_provider_id property. Use this ID, along with the order_id and payment_id, to launch the modal displaying the global 3D Secure challenge.

Below is an example of the response that payment requires validating the 3D Secure global:

{
    "payment_id": "pay_f30a6fb904bc46d5978c716895651705",
    "order_id": "ord_a850ee7aba994b05b6eca01a57d62cbf",
    "status": "PAYMENT_ACTION_REQUIRED",
    "payment_source": {
        "type": "CARD",
        "settings": {
            "card": {
                "capture": true
            },
            "redirection_url": {
                "completed_redirect_url": "https://tu.dominio.com/status?result=COMPLETED",
                "canceled_redirect_url": "https://tu.dominio.com/status?result=CANCELED"
            }
        },
        "payment_method_id": "pym_20e99063448344bc9e84a9cd9cd1b5d4"
    },
    "amount": {
        "currency": "MXN"
    },
    "user_action_required": {
        "type": "THREE_D_SECURE_AUTHENTICATION",
        "three_d_secure_authentication": {
            "merchant_provider_id": "mpv_b7609d98330e4606931ba267424d0e91"
        }
    }
}

To lift the modal, a method is executed from the OrkestaPay CDN that returns a promise. This promise will be resolved once the transaction has been evaluated by the 3D Secure Global provider.

// Inicializar CDN
const merchant_id = '{YOUR_MERCHANT_ID}';
const public_key = '{YOUR_PUBLIC_KEY}';
const orkestapay = initOrkestaPay({ merchant_id, public_key });

// Modal 3DS
const results = await orkestaPay.startModal3DSecure({
  merchant_provider_id,
  payment_id,
  order_id,
});

NOTE: The challenge of deploying with 3DS global will be held in a pop-up window (modal window).

Once the global 3D Secure verification has been resolved, the payment needs to be completed (discussed later in the article).

Complete Payment for Global 3DS

Once the global 3DS challenge is successfully completed, call the service to complete the payment, sending the Idempotency-Key and Authorization headers.

Request to the service

curl --request POST \
     --url https://api.sand.orkestapay.com/v1/payments/{PAYMENT_ID}/complete \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'Idempotency-Key: adffaf7a3141474555d988fbb5e43e85' \
     --header 'Authorization: Bearer REPLACE_WITH_YOUR_ACCESS_TOKEN' \
     --data '
{}
'

Service response

When completing a payment, the following information will be returned.

{
    "type": "COMPLETE",
    "transaction_id": "ctx_68654481e4a04e30bee02bfecd4e8c72",
    "status": "COMPLETED",
    "amount": 1403.6,
    "code": "APPROVED",
    "message": "Transaction approved",
    "description": "mch_db68ab57e28a42b7bad618f1b364f958",
    "provider": {
        "name": "Stripe",
        "provider_transaction_id": "ctx_68654481e4a04e30bee02bfecd4e8c72",
        "code": "000",
        "message": "Transaction approved"
    },
    "authorization_code": "pi_3PDdFPGYqhDa3Ul63cpDZVZ2",
    "created_at": "1715046917129"
}

Specific 3D Secure

To validate that the 3D Secure type is specific, check the user_action_required object for the property type with the value THREE_D_SECURE_AUTHENTICATION. If present, another object three_d_secure_specific contains a URL in the three_ds_redirect_url property. Redirect to this URL for the specific 3D Secure challenge.

Below is an example of the response that payment requires validating the specific 3D Secure:

{
    "payment_id": "pay_7fee268029bd402cbcbd6215d48c2cdb",
    "order_id": "ord_80b6a1701f7c402fab89a466a852c952",
    "status": "PAYMENT_ACTION_REQUIRED",
    "payment_source": {
        "type": "CARD",
        "settings": {
            "card": {
                "capture": true
            },
            "redirection_url": {
                "completed_redirect_url": "https://sven.biz",
                "canceled_redirect_url": "http://stuart.org"
            }
        },
        "payment_method_id": "pym_d82f63059792493dac024464858c2fa4"
    },
    "amount": {
        "currency": "MXN"
    },
    "user_action_required": {
        "type": "THREE_D_SECURE_SPECIFIC",
        "three_d_secure_specific": {
            "three_ds_redirect_url": "https://api.dev.orkestapay.com/public/v1/redirect/tds_6661c1d7d61a41cd80fbc383e25e7c32"
        }
    },
    "transactions": [
        {
            "type": "REGISTER",
            "transaction_id": "ctx_815509c8bb2449eba9301593094cb1ad",
            "status": "SUCCESS",
            "amount": 995.00,
            "code": "APPROVED",
            "message": "Approved or completed successfully",
            "description": "ord_80b6a1701f7c402fab89a466a852c952",
            "provider": {
                "merchant_provider_id": "mpv_b6de55faf5734859a3ef7842fb99e5cf",
                "name": "openpay",
                "provider_transaction_id": "trnsmosizgcxpuex2ihv",
                "code": "000",
                "message": ""
            },
            "authorization_code": "trnsmosizgcxpuex2ihv",
            "created_at": "1715118387984"
        }
    ],
    "created_at": "1715118384684",
    "updated_at": "1715118384684"
}

NOTE: The challenge of the implementation with specific 3DS will be carried out in a URL of the payment processor, to which the user must be redirected.

Once the specific 3D Secure Provider's challenge has been completed/failed, it is recommended to check the payment made through your payment_id to confirm your status.