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 use SCA (strong customer authentication) and guarantee that your payment is being processed in a secure environment.

πŸ“˜

Info

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

Create card payment

The card payment creation is divided mainly in three steps:

1st step: Creation of the card payment
2nd step: 3D Secure authentication
3rd step: 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.

πŸ“˜

Info

By default all authorizations are captured automatically, unless you specify the field isPreAuth=true .

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 shall pass the authentication result to our API when authorizing a transaction.

You can find below an example of how to provide the 3DS v1 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",
    "xid": "xid123456abcd",
    "aav": "avv123456abcd",  
    "threeDSVersion": "V1",
    "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",
        "xid": "xid123456abcd",
        "aav": "avv123456abcd",           
        "threeDSVersion": "V1",
        "verificationMethod": "ThreeDSecure"
    }
}

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",
    "xid": "xid123456abcd",
    "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",
        "xid": "xid123456abcd",
        "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 .