3D Secure authentication

Learn about 3D Secure authentication to reduce fraud and meet regulatory requirements.

3D Secure (3DS) is a security layer that provides fraud prevention for card payments. The system requires customers to complete an additional verification step with the card issuer when paying. It involves a pop-up window or inline frame appearing during the online transaction process, requiring the cardholder to authenticate the card, tipically entering a password or code sent to his phone.

Paybyrd API and 3D Secure server-side

Paybyrd abstracts all the complexity that is in the card payment processing, including the 3D Secure. Our API will always trigger the 3D Secure V2 flow for all card transactions if no authentication data is provided.

Payment API

The card payment creation is divided mainly in three steps:

  1. Creation of the card payment
  2. 3D Secure authentication
  3. Payment completion

Creation of the card payment

On the first step you need to create the payment and provide all the necessary info for the next steps. You can see below the simplest example of how to create a card payment and the generated response:

curl --request POST \
  --url https://gateway.paybyrd.com/api/v2/payment \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
  --data '
{
  "type": "Card",
  "amount": "8.15",
  "currency": "EUR",
  "orderRef": "ABC12345",
  "redirectUrl": "https://your-shop-url?orderRef=ABC12345",
  "card": {
    "number": "4200000000000000",
    "expiration": "02/25",
    "cvv": "123",
    "holder": "Peter Parker"
  }
}'
{
    "transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
    "type": "Card",
    "currency": "EUR",
    "orderRef": "ABC12345", 
    "brand": "VISA",
    "fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
    "amount": "8.15",
    "isPreAuth": false,
    "redirectUrl": "https://your-shop-url?orderRef=ABC12345",
    "action": {
        "type": "redirect",
        "url": "https://gateway.paybyrd.com/v1/ThreeDSecure/InitiatePayment?transactionId=0e443bff-9052-4eec-a5f1-9db474f2077a"
    },
    "card": {
        "number": "420000******0000",
        "expiration": "12/25",
        "cvv": "***",
        "holder": "Peter Parker"
    },
    "code": "BYRD207",
    "description": "Pending redirect",
}

See the full API reference here.

In order to know whether the transaction was accepted or not, you must check the code field. For successful scenarios the expected code is BYRD207 and the description is Pending redirect (You can find here the list of all possible codes). That means an extra step has to be taken in order to complete de payment. The action node contains what the next step is. For 3D Secure payments, a redirect must be performed.

3D Secure authentication

Once the shopper is redirected, Paybyrd will trigger the 3D Secure authentication flow. A challenge may be required. If so the bank screen will prompt waiting for the shopper's authentication. The payment will be processed automatically right after the authentication.

Payment completion

At this point Paybyrd will conclude the payment and the shopper will be redirected to the Url defined in the redirectUrl field. Paybyrd will concat the transactionId as a query string. This allows you to query the transaction status in the end of the process.

Using an external 3D Secure provider

If you choose to verify the card holder with an external 3DS server, you should pass the authentication data to our API when authorizing a transaction.

You can find below an example of how to provide the 3DS v2 authentication when creating a new card payment:

curl --request POST \
  --url https://gateway.paybyrd.com/api/v2/payment \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
  --data '
{
  "type": "Card",
  "amount": "8.15",
  "currency": "EUR",
  "orderRef": "ABC12345",  
  "card": {
    "number": "4200000000000000",
    "expiration": "02/25",
    "cvv": "123",
    "holder": "Peter Parker",
    "eci": "05",
    "aav": "avv123456abcd",   
    "dsTransactionId": "33cdebf1-ff0c-4e33-a4b1-47e4c141fe58",
    "threeDSVersion": "V2",
    "verificationMethod": "ThreeDSecure"
  }
}'
{
    "type": "Card",
    "currency": "EUR",
    "orderRef": "ABC12345", 
    "brand": "MASTER",
    "fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
    "code": "BYRD200",
    "description": "Operation successfully completed",
    "transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
    "amount": "8.15",
    "isPreAuth": false,
    "card": {
        "number": "4200000000000000",
        "expiration": "02/25",
        "cvv": "123",
        "holder": "Peter Parker",
        "eci": "05",
        "aav": "avv123456abcd",       
        "dsTransactionId": "33cdebf1-ff0c-4e33-a4b1-47e4c141fe58",
        "threeDSVersion": "V2",
        "verificationMethod": "ThreeDSecure"
    }
}

If you attempt authentication but the issuer doesn't support 3DS or its access control server doesn't respond, the liability shifts to the issuer, as long as the attempt includes a cryptogram (CAVV/AVV) from the card scheme's directory server. In these situations you should set the verificationMethod field to ThreeDSecureAttempt.

Card tokenization API

The card tokenization service works very similar to the payment flow described above. When no authentication data is provided, the 3D Secure authentication flow will be triggered and Paybyrd will respond with the actionUrl. By invoking it, the 3D Secure authentication process occurs and the card is verified (zero dolar auth). In the of the process the customer is redirected to the url provided in the redirectUrl field.

See below an example of how to make a simple create token request to our API:

curl --request POST \
--url https://gateway.paybyrd.com/api/v2/tokens \
--header 'X-Api-Key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "card",
    "currency": "EUR",
    "card": {
        "number": "5277801257221511",
        "expiration": "06/26",
        "cvv": "123",
        "holder": "Peter Parker"
    },
    "customReference": "PeterP",
    "alias": "PeterCard",
    "redirectUrl": "https://www.paybyrd.com"
}'
{
    "card": {
        "number": "527780******1511",
        "expiration": "06/26",
        "cvv": "**********************************",
        "holder": "Peter Parker"
    },
    "action": {
        "type": "redirect",
        "url": "https://gatewaysandbox.paybyrd.com/v1/ThreeDSecure/InitiatePayment?transactionId=cb503fa2-fb6e-45ba-a97f-0283cce5cc30"
    },
    "transactionId": "cb503fa2-fb6e-45ba-a97f-0283cce5cc30",
    "tokenId": "2349c7fd-3f1b-4188-b98e-3dcead913ef6",
    "customReference": "PeterP",
    "alias": "PeterCard",
    "code": "BYRD207",
      "description": "Pending redirect"
}

Using an external 3D Secure provider

If you choose to verify the card holder with an external 3DS server, you should pass the authentication data to our API when authorizing a transaction.

You can find below an example of how to provide the 3DS v2 authentication when creating a new card payment:

curl --request POST \
--url https://gateway.paybyrd.com/api/v2/tokens \
--header 'X-Api-Key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "card",
    "currency": "EUR",
    "card": {
        "number": "5277801257221511",
        "expiration": "06/26",
        "cvv": "123",
        "holder": "Peter Parker",
        "eci": "05",
        "aav": "avv123456abcd",   
        "dsTransactionId": "33cdebf1-ff0c-4e33-a4b1-47e4c141fe58",
        "threeDSVersion": "V2",
        "verificationMethod": "ThreeDSecure"
    },
    "customReference": "PeterP",
    "alias": "PeterCard"    
}'
{
    "type": "card",
    "currency": "EUR",  
    "card": {
        "number": "5277801257221511",
        "expiration": "06/26",
        "cvv": "123",
        "holder": "Peter Parker",
        "eci": "05",
        "aav": "avv123456abcd",       
        "dsTransactionId": "33cdebf1-ff0c-4e33-a4b1-47e4c141fe58",
        "threeDSVersion": "V2",
        "verificationMethod": "ThreeDSecure"
    },  
    "customReference": "PeterP",
    "alias": "PeterCard",
    "code": "BYRD200",
    "description": "Operation successfully completed",    
    "tokenId": "2349c7fd-3f1b-4188-b98e-3dcead913ef6"
}

If you want to know more about card tokenization, please check Tokenization session.