- 28 Aug 2024
- 5 Minutes to read
3DS Implementation
- Updated on 28 Aug 2024
- 5 Minutes to read
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).
CDN OrkestaPay
For more information about the OrkestaPay CDN, you can review our Initialization documentation.
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.