Skip to main content
This page explains how to accept card payments using the Paybyrd API.

​
Overview

Paybyrd handles the complexity of card payment processing, including 3D Secure authentication. By default, the API triggers the 3D Secure V2 flow for all card transactions, with a native fallback to V1 if the card is not enrolled for V2. No additional development is required on your side to support both versions. A single request is enough to enable SCA (Strong Customer Authentication) and process payments 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, typically by entering a password or a code sent to their phone. Paybyrd triggers 3D Secure for all transactions by default. To create a transaction without 3D Secure, set the parameter VerificationMethod=None. Note that the card issuer will likely decline such transactions.

​
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. In the first flow, Paybyrd handles the 3D Secure authentication result and calls the payment completion automatically. To use this flow, provide the RedirectUrl parameter. Paybyrd redirects the customer to this URL after the full process completes. You can use that page to query the transaction status and direct the shopper accordingly. 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}' \
 --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"
 }
}'

​
Soft descriptor

You can customize the text shown on the cardholder’s bank statement for each transaction by passing a softDescriptor value in the payment request. This is useful for providing a clearer transaction reference to your customers. The field accepts a string of up to 22 characters. Requests exceeding this limit return 400 Bad Request. 
{
  "type": "Card",
  "softDescriptor": "Paybyrd Store Purchase",
  ...
}

​
Using callbacks in the 3DSecure flow

To handle the 3D Secure result yourself, provide the CallbackUrl inside the ThreeDSecure node instead of the RedirectUrl parameter. Paybyrd sends the authentication result to that URL as a base64-encoded query parameter. You can decode it, review the result, and decide whether to call the payment completion. This is useful if you need to run anti-fraud checks before completing the transaction. 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}' \
 --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"
 }
}'
See the full API reference for more details. Check the code field to know whether the transaction was accepted. A successful scenario returns the code BYRD207 and Pending redirect in the description field. You can find the list of all status codes in the Respone code reference. The action field contains the next step. If you use your own 3D Secure provider and perform cardholder authentication before calling the Paybyrd API, provide the authentication data in your request. 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 triggers the 3D Secure authentication flow. A challenge may be presented, in which case the bank screen will wait for the shopper to authenticate. 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"
}
FieldDescription
TransactionIdTransaction id generated by Paybyrd
StatusAuthorized — Authentication succeeded. Unauthorized — Authentication was declined. NotEnrolled — Card is not enrolled for 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, call the Payment API to finalize the payment. Provide the card data and the 3D Secure information received during the previous step: 
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}' \
--data '{
    "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"
    }
}'

​
3DS exemptions

If 3DS validation fails and you still want to proceed with the payment, provide the threeDSecureExemption field, which accepts the values 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}' \
--data '{
    "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 use an external 3DS server to authenticate the cardholder, pass the authentication data to the API when creating the 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}' \
  --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"
  }
}'
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 this case, set the verificationMethod field to ThreeDSecureAttempt.