Documentación

3DS implementation

3DS Integration

To perform the 3DS integration with the Direct Payment approach, that is, without being redirected to the OrkestaPay checkout, it is necessary to follow these steps:

  1. Direct Payment Integration
  2. 3DS flow integration
  3. Complete payment for 3DS

Preconditions

  • Have an orchestration route with a configured 3DS provider.
  • Have the OrkestaPay CDN previously initialized in the frontend.

Direct Payment Integration

Follow the guide for Payment Integration, however in step number 4 where the payment is registered, you must send the redirection_url object with the redirect URLs for the successful or canceled 3DS authentication scenarios.

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}}"
}
'
📘

Documentation

Visit our API documentation: https://docs-en.orkestapay.com/reference/create-payment


3D Secure

There are 2 modalities for addressing 3D Secure:

  • Modal: The 3DS challenge will be displayed in a modal window, which will allow the user to complete their purchase process within the merchant's page checkout.
  • Redirection: The challenge will be displayed on an external page (from Orkestapay) to which the user must be redirected to complete the payment.

If the response status has the value PAYMENT_ACTION_REQUIRED, then the 3D Secure challenge must be executed.

Below is an example of the response indicating that the payment requires 3D Secure validation:

{
  "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",
      "authentication_redirect_url": "https://checkout.dev.orkestapay.com/3ds/global?merchant_id=mch_9608f49086bf44ea8a02f0c3f5d35383&public_key=pk_test_bjc14uzla1m941dgy74psmeaujayc6rx&merchant_provider_id=mpv_100f2f97b2da4ee6bc8828504571a76c&payment_id=pay_7d0114f013924c0c8d23180922ad7a5f&order_id=ord_edfa827d57794f4487a97d99b9089b17&is_sandbox=false"
    }
  },
  "transactions": [
    {
      "type": "REGISTER",
      "transaction_id": "tds_1dcb08fcacbb4a888461539ecc49ec63",
      "status": "SUCCESS",
      "amount": 16100,
      "code": "APPROVED",
      "message": "Approved or completed successfully",
      "description": "ord_edfa827d57794f4487a97d99b9089b17",
      "provider": {
        "merchant_provider_id": "mpv_100f2f97b2da4ee6bc8828504571a76c",
        "name": "cyber_source",
        "code": "",
        "message": ""
      },
      "created_at": "1731010722448"
    }
  ],
  "device_session_id": "7e4e4bdd-6eaa-4470-979c-1fe8fe02b0d2",
  "created_at": "1731010721909",
  "updated_at": "1731010721909"
}
📘

Documentation

Visit our API documentation: https://docs-en.orkestapay.com/reference/create-payment


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


3D Secure with modal

In the user_action_required object of the aforementioned response, there will be a three_d_secure_authentication object containing an ID in the merchant_provider_id property. This ID, together with the order_id and payment_id, will be used to launch the modal that displays the 3D Secure challenge.

To open the modal window, a method from the OrkestaPay CDN must be executed that returns a promise. This promise will be resolved once the 3D Secure provider has evaluated the transaction.

Below is a very basic example of the implementation from the application's frontend.

// Initialize 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,
});
📘

CDN OrkestaPay

For more information about the OrkestaPay CDN, you can review our documentation on Initialization.


NOTE: The challenge of the 3DS implementation, will take place in a pop-up window (modal window). Once the 3D Secure verification has been resolved, it is necessary to complete the payment (addressed later in the article).


Complete payment for 3DS with modal

Once the 3DS modal challenge has been successfully completed, a service must be called to complete the payment.


Request to the service

The "complete payment" service must be called, and as part of the request the Idempotency-Key and Authorization headers must be sent**,** both headers are mentioned in the Payment Integration guide.

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 '
{}
'
📘

Documentation

Visit our API documentation: https://docs-en.orkestapay.com/reference/complete-payment


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"
}
📘

Documentation

Visit our API documentation: https://docs-en.orkestapay.com/reference/complete-payment


3D Secure with redirection

In the user_action_required object returned in the /payments service response, there will be a three_d_secure_authentication object containing the URL to which the user must be redirected authentication_redirect_url.

Once the 3DS challenge is completed or canceled, the user will be redirected to the URLs you indicated during the call to the /payments service.

IMPORTANT

In the redirection modality, it is not necessary to call the completion service.


Specific 3D Secure

To validate that the type of 3D Secure is specific, it is verified that the user_action_required object has a type property with the value THREE_D_SECURE_AUTHENTICATION. Additionally, within the same user_action_required object there will be another object three_d_secure_specific containing a URL in the three_ds_redirect_url property. In this case, the user must be redirected to that URL to perform the specific 3D Secure challenge. Once the challenge is passed/failed, the user will be redirected to the corresponding URL defined when registering the payment.

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

{
  "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.0,
      "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"
}
📘

Documentation

Visit our API documentation: https://docs-en.orkestapay.com/reference/create-payment


NOTE: The challenge of the specific 3DS implementation will take place on a URL belonging to 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 query the payment made via its payment_id to confirm its status.