payabl. 3DSecure services

This guide will show you how to integrate 3D Secure 2 (3DS2) into your payment flows.

Step 1. Initiate transaction

When you send a transaction request, Authorization or Pre-Authorization, to the payment gateway, it requires additional parameters for 3DSecure, such as:

  • url_return: The URL where the customer will be redirected.
  • param_3d: This parameter indicates if there will be a 3DSecure procedure.

The parameter "param_3d "can have several values:

  • non3d: The transaction will be sent to the acquirer without executing the 3DSecure procedure.
  • try3d: This value is used by default, and the 3DS procedure is attempted. If the procedure fails due to a communication error or the cardholder is not enrolled, the transaction will attempt the non-3D procedure. If the cardholder is enrolled, they must authenticate the transaction by entering their 3DS credentials on their issuing bank 3DS form. Should the cardholder not be able to authenticate the card, the transaction will be declined.
  • always3d: The transaction will be declined for any type of failure during the 3DSecure procedure. There is an edge case where the 3DS procedure is "attempted" and due to enrolment issues either with the issuer or card, the gateway receives a "3DS attempted" status. The transaction will be accepted and sent to the acquirer for processing in this mode. "3DS attempted" status means the transaction was processed and classified as 3DS.
  • authenticated_only: Unless the cardholder enters their 3DS authentication successfully the transaction will be declined. The card must be enrolled, and the cardholder must enter their 3DS credentials successfully. Transactions qualifying as "3DS Attempted" will also be declined in this mode.

Step 2. The payment gateway check

When you send a transaction request, the payment gateway will validate the parameters and send a response to you with an additional parameter url_3ds. The transaction has a pending status at this point.
The parameter url_3ds is a URL to where you need to redirect the customer to pass 3DSecure.


After you receive url_3ds, you need to decode it and redirect the customers to it.

Response example


Step 3. Handle the redirect

After you received and decoded url_3ds, redirect the customer to the provided URL. The customer should provide a PIN or passphrase for her bank account to verify the transaction.


Soft decline

In some cases, the Issuer's bank can return a non3d transaction with Soft Decline code. In this case, you need to redirect your customer to the 3D Secure page.
Please follow this guide to implement the procedure for [Soft Declines] (

Step 4. Handle the notification

After the customer successfully entered the PIN/password for 3D Secure, the transaction is sent to payabl. An internal notification will be sent to your notification URL and the customer will be redirected to url_return.

The notification will include the following parameters:

  • transactionid:The field transactionid contains the transaction’s identification in the payment gateway. The transaction ID is generated within the payment gateway for a Preauthorize request or an Authorize request, and is send back to the merchant's system.
  • orderid: The field orderid is optional and exclusively for the merchants convenience.
  • type: When a transaction has successful 3D and order is successful, it will have type = capture. When a transaction has successful 3D and authorization is failed, type = order.
  • errorcode: 0 = no error, 2000 = pending, any other value is an error code
  • errormessage: error message or empty
  • security: Please refer to Signature Calculation.

Step 5. 3DSecure process is finalized.

Payabl will send you a response that contains the security parameter. You need to verify the authentication of the notification with this security parameter.
The value of the security parameter is calculated in the same way, the signature parameter is.
The callback will contain all fields for Capture response + 3dstatus.

Possible values: