Guides

Card

Suggest Edits

Here you will find out how to accept card payments on your platform.

Overview

Paybyrd abstracts all the complexity that is in the card payment processing, including the 3D Secure authentication. By default our API triggers the 3D Secure V2 flow for all card transactions. We also have implemented natively a fall back to the 3D Secure V1, in case the card is not enrolled for the V2. On your side, no extra development is needed to use both versions. With only one single request you will able to enable SCA (strong customer authentication) and guarantee that your payment is being processed in a secure environment.

🚧

PCI compliance

In case you are not PCI compliant and you want to build your own cards payment form, please check our hosted form and card collect solution.

3D Secure

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.

📘

Info

If you want to know more about the 3D Secure, please check here.

As mentioned before, Paybyrd triggers the 3D Secure for all transactions by default. If you want to change this behavior and create a transaction without going through this process, you must sent the parameter VerificationMethod=None, although we do not recommend to do this since the card issuer will likely decline the transaction.

Paybyrd API and 3D Secure server-side

The card payment creation is divided mainly in three steps:

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

Creation of the card payment

On the first step you will need to create the payment and provide all the necessary information for the next steps. Paybyrd has two different flows that can be triggered depending on the parameters you sent to us. The first flow consists in calling the payment completion automatically after the 3D Secure authentication is performed by the card holder. Basically Paybyrd will handle the 3D Secure authentication result for you and call the payment completion. For that, you must provide the parameter RedirectUrl. Paybyrd will use this URL to redirect the customer in the end of the whole process. You can also use this page to query the transaction status and take the shopper to the page you want.

You can see below an example of how to create a card payment that will trigger the 3D Secure flow which will be fully managed by Paybyrd:

curl --request POST \
  --url https://gateway.paybyrd.com/api/v2/payment \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {{YOUR_API_KEY_HERE}}' \
  --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://link-s.paybyrd.com/3ds_Q44clBT77"
    },
    "card": {
        "number": "420000******0000",
        "expiration": "12/25",
        "cvv": "***",
        "holder": "Peter Parker"
    },
    "code": "BYRD207",
    "description": "Pending redirect",
}

In case you want to have full control over the 3D Secure authentication result and decide what to do with the transaction, instead of providing the RedirectURL parameter, you must provide the CallbackUrl inside the ThreeDSecure node. Paybyrd will call the URL provided, by sending the result of the authentication as a query parameter encoded in base64. You can decode this data on your side, analyse the authentication result and decide if you want to call the payment completion or not. This can be useful if you want to perform any anti-fraud checks based on the response you get.

You can see below an example of how to create a card payment that will trigger the 3D Secure flow which will be managed by you:

curl --request POST \
  --url https://gateway.paybyrd.com/api/v2/payment \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {{YOUR_API_KEY_HERE}}' \
  --data '
{
  "type": "Card",
  "amount": "8.15",
  "currency": "EUR",
  "orderRef": "ABC12345",
  "card": {
    "number": "4200000000000000",
    "expiration": "02/25",
    "cvv": "123",
    "holder": "Peter Parker"
  },
  "threeDSecure": {
    "callbackUrl": "https://your-threedsresult-handle-url.com"
    }
}'

{
    "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,
    "action": {
        "type": "redirect",
        "url": "https://link-s.paybyrd.com/3ds_Q44clBT77"
    },
    "card": {
        "number": "420000******0000",
        "expiration": "12/25",
        "cvv": "***",
        "holder": "Peter Parker"
    },
    "threeDSecure": {
        "callbackUrl": "https://your-threedsresult-handle-url.com"
    },
    "code": "BYRD207",
    "description": "Pending redirect",
}

📘

Info

Please check the full API reference here.

In order to know whether the transaction was accepted or not for both scenarios, you must check the code field. For successful scenarios the expected code is BYRD207 and the description is Pending redirect (codes list). That means an extra step has to be taken in order to complete de payment. The action node contains what the next step is.

Some of our customers have their own 3D Secure provider and the card holder authentication is performed before calling Paybyrd's API. For that case you must provide the authentication data and Paybyrd will respond with code BYRD200 and no extra step is required. Please check the Using an external 3D Secure provider section.

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. In case you provided the RedirectUrl parameter during the first step, the payment will be processed automatically right after the 3D Secure authentication and the shopper will be redirected to the URL sent.

For the scenario where you sent the CallbackUrl instead, we will call the provided URL with the threeDSecureResult parameter encoded in base64 as you can see below:

http://your-threedsresult-handle-url.com/?threedSecureResult=eyJ0cmFuc2FjdGlvbklkIjoiMjgzMjlmNjEtNDE2NC00MGQwLWI5MzktZmUxMjk3ZTlmOTE2Iiwic3RhdHVzIjoiQXV0aG9yaXplZCIsImF1dGhlbnRpY2F0aW9uRGF0YSI6eyJ0aHJlZURzVmVyc2lvbiI6IlYyIiwiYWF2IjoiZjVkZjQwMDdjODQ3NDZhZTgwNjU1ODM2OTViOGJjYTUiLCJkc1RyYW5zYWN0aW9uSWQiOiI1ZTRiZjA3Zi03NDBjLTQ4YmMtYjI5Ni02YjA5NWEyOTQzZjkiLCJlY2kiOiIwNSIsInZlcmlmaWNhdGlvbk1ldGhvZCI6IlRocmVlRFNlY3VyZSJ9LCJ0cmFuc1N0YXR1cyI6IlkiLCJ0cmFuc1N0YXR1c1JlYXNvbiI6IjE3In0

The decoded response will look like the following json:

{
    "transactionId": "28329f61-4164-40d0-b939-fe1297e9f916",
    "status": "Authorized",
    "authenticationData": {
        "threeDsVersion": "V2",
        "aav": "f5df4007c84746ae8065583695b8bca5",
        "dsTransactionId": "5e4bf07f-740c-48bc-b296-6b095a2943f9",
        "eci": "05",
        "verificationMethod": "ThreeDSecure"
    },
    "transStatus": "Y",
    "transStatusReason": "17"
}

{
    "transactionId": "5051e95a-977e-4925-a9af-3f05ce39c890",
    "status": "Unauthorized",
    "authenticationData": {
        "threeDsVersion": "V2",
        "dsTransactionId": "2b771583-f9a4-4562-a71d-badab879d7d7",
        "eci": "07",
        "verificationMethod": "ThreeDSecure"
    },
    "message": "Authorization failed",
    "details": "Security failure",
    "transStatus": "N",
    "transStatusReason": "09"
}

{
    "transactionId": "0160b04d-61b4-47ce-bbf9-067bc939f0e5",
    "status": "NotEnrolled",
    "authenticationData": {
        "threeDsVersion": "V1",
        "eci": "06",
        "verificationMethod": "None"
    },
    "code": "999",
    "message": "Simulated not enrolled error",
    "details": "Simulated not enrolled error"
}
FieldDescription
TransactionIdTransaction id generated by Paybyrd
StatusAuthorized - Card authentication was successfully performed.

Unauthorized - Card authentication was declined.

NotEnrolled - Card is not enrolled for the 3D Secure
AuthenticationData.ThreeDsVersionV2
V1
AuthenticationData.AavAuthentication value received by the 3DS provider
AuthenticationData.DsTransactionIdTransaction id in the directory server
AuthenticationData.ECIResponse code returned by the schemes
AuthenticationData.VerificationMethodThreeDSecure - Card went through the 3D Secure process.

ThreeDSecureAttempt - Attempt (proof of authentication attempt, may continue to transaction but issuer might still reject).

None - No authentication was performed
CodeError code
MessageError message
DetailsError message details
TransStatusTransaction status returned by ACS
TransStatusReasonTransaction status reason returned by ACS

Payment completion (optional)

After obtaining the 3D Secure response, you may call the payment API in order to conclude the payment. It is necessary to send us the card data again and also the information retrieved in the previous step. Please see the request below:

curl --location --request POST 'https://gateway.paybyrd.com/api/v2/payment/0e443bff-9052-4eec-a5f1-9db474f2077a/pay' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{YOUR_API_KEY_HERE}}' \
--data-raw '{
    "card":{
        "number":"4200000000000000",
        "expiration":"12/25",
        "cvv":"123",
        "holder":"Jane Jones",
        "ThreeDsVersion": "V2",
        "Aav": "aaaaaaec781048dd9ad8fc96e0031111",
        "DsTransactionId": "11111111-1111-1111-1111-111111111111",
        "Eci": "01",
        "VerificationMethod": "ThreeDSecure"
    }
}

{
    "code": "BYRD200",
    "description": "Operation successfully completed",
    "status": "Success"
}

3D Secure Exemptions

If for some reason the 3DS validation fails and you still want to try to execute the payment, you can send us the field threeDSecureExemption, which accepts the value TRA and LowValue.

curl --location --request POST 'https://gateway.paybyrd.com/api/v2/payment/0e443bff-9052-4eec-a5f1-9db474f2077a/pay' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{YOUR_API_KEY_HERE}}' \
--data-raw '{
    "card":{
        "number":"4200000000000000",
        "expiration":"12/25",
        "cvv":"123",
        "holder":"Jane Jones",
        "threeDsVersion": "V2",
        "dsTransactionId": "11111111-1111-1111-1111-111111111111",
        "eci": "07",
        "verificationMethod": "ThreeDSecure",
        "threeDSecureExemption": "TRA"
    }
}

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: {{YOUR_API_KEY_HERE}}' \
  --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.

Updated 10 days ago

What’s Next