SDK setup

Integrate Paybyrd's 3D Secure (3DS) flow seamlessly into your platform by following this guide.

Requirements

API Key: Obtain your API key from the Developer Section in our dashboard.
And to simplify the integration, you will have to add our SDK to your site. We will show you how to do it.

Step-by-step Guide

1. Initiating the Flow

Begin by creating a payment request using your API key.:

curl --request POST \
  --url https://gatewaysandbox.paybyrd.com/api/v2/payment \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY_HERE' \
  --data '{
  "type": "card",
  "isoAmount": 100,
  "currency": "EUR",
  "orderRef": "YOUR_REF_CODE_HERE",
  "redirectUrl": "https://your-shop-url?orderRef=YOUR_REF_CODE_HERE",
  "card": {
    "number": "5555341244441115",
    "expiration": "12/30",
    "cvv": "893",
    "holder": "Paybyrd"
  }
}'

const axios = require('axios');

const response = await axios.post('https://gatewaysandbox.paybyrd.com/api/v2/payment', {
  type: 'card',
  isoAmount: 100,
  currency: 'EUR',
  orderRef: 'YOUR_REF_CODE_HERE',
  redirectUrl: 'https://your-shop-url?orderRef=YOUR_REF_CODE_HERE',
  card: {
    number: '5555341244441115',
    expiration: '12/30',
    cvv: '893',
    holder: 'Paybyrd'
  }
}, {
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY_HERE'
  }
});
console.log(response.data);

using var client = new HttpClient();

client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY_HERE");

var requestBody = new
{
  type = "card",
  isoAmount = 100,
  currency = "EUR",
  orderRef = "YOUR_REF_CODE_HERE",
  redirectUrl = "https://your-shop-url?orderRef=YOUR_REF_CODE_HERE",
  card = new
  {
    number = "5555341244441115",
    expiration = "12/30",
    cvv = "893",
    holder = "Paybyrd"
    }
};

var response = await client.PostAsync("https://gatewaysandbox.paybyrd.com/api/v2/payment",
                                      new StringContent(System.Text.Json.JsonSerializer.Serialize(requestBody), Encoding.UTF8, "application/json"));

string responseContent = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseContent);

$apiKey = "YOUR_API_KEY_HERE";
$url = "https://gatewaysandbox.paybyrd.com/api/v2/payment";

$data = [
    "type" => "card",
    "isoAmount" => 100,
    "currency" => "EUR",
    "orderRef" => "YOUR_REF_CODE_HERE",
    "redirectUrl" => "https://your-shop-url?orderRef=YOUR_REF_CODE_HERE",
    "card" => [
        "number" => "5555341244441115",
        "expiration" => "12/30",
        "cvv" => "893",
        "holder" => "Paybyrd"
    ]
];

$options = [
    "http" => [
        "header" => "Content-Type: application/json\r\n" .
                     "x-api-key: $apiKey\r\n",
        "method" => "POST",
        "content" => json_encode($data),
    ],
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);

if ($result === FALSE) {
    die('Error occurred');
}

echo $result;

import requests
import json

url = "https://gatewaysandbox.paybyrd.com/api/v2/payment"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY_HERE"
}

data = {
    "type": "card",
    "isoAmount": 100,
    "currency": "EUR",
    "orderRef": "YOUR_REF_CODE_HERE",
    "redirectUrl": "https://your-shop-url?orderRef=YOUR_REF_CODE_HERE",
    "card": {
        "number": "5555341244441115",
        "expiration": "12/30",
        "cvv": "893",
        "holder": "Paybyrd"
    }
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())

🚧
We strongly recommend executing this request from your backend for enhanced security and reliability

Minimal Request example

{
  "type": "card",
  "isoAmount": 100,
  "currency": "EUR",
  "orderRef": "YOUR_REF_CODE_HERE",
  "redirectUrl": "https://your-shop-url?orderRef=YOUR_REF_CODE_HERE",
  "card": {
    "number": "5555341244441115",
    "expiration": "12/30",
    "cvv": "893",
    "holder": "Paybyrd"
  }
}

Response example

{
  "type": "Card",
  "currency": "EUR",
  "orderRef": "YOUR_REF_CODE_HERE",
  "acquirer": "SIMULATED",
  "brand": "MASTER",
  "paymentMethod": "card",
  "redirectUrl": "https://your-shop-url?orderRef=YOUR_REF_CODE_HERE",
  "fingerprint": "d2456a93-4092-45ed-8f65-1446a255a8ed",
  "action": {
    "type": "redirect",
    "url": "https://link.paybyrd.com/3ds_yvLu4cxe8"
  },
  "code": "BYRD207",
  "description": "Pending redirect",
  "status": "Created",
  "requestId": "f2d40ac5-59ed-4528-a4c1-01641fd64bf7",
  "expiresAt": "2025-01-13T20:33:03.4365231Z",
  "acceptTokenization": false,
  "transactionMode": "None",
  "transactionId": "77f01ebc-2241-4c5f-8bfd-9cab6c81d74a",
  "amount": "1.00",
  "isoAmount": 100,
  "isPreAuth": false,
  "card": {
    "number": "555534******1115",
    "expiration": "12/30",
    "cvv": "***",
    "holder": "Paybyrd",
    "installments": 1,
    "installmentAmount": 100,
    "isPayerTraveling": false,
    "scheme": "Master",
    "usage": "Credit",
    "countryCode": "QAT"
  },
  "threeDSecure": {
    "id": "9e8cf073-c854-4534-97ae-1cea65695efb",
    "verificationMethod": "ThreeDSecure",
    "channel": "Browser",
    "status": "Created"
  }
}

📘
For more information about payment creation, see the documentation

2. Handle the Payment Response

Upon initiating the payment, the response will indicate if 3D Secure (3DS) authentication is required to complete the transaction. This is indicated by the BYRD207 code, which signals that an additional step is necessary.

The response will include the following fields relevant to 3DS execution:

Property	Description
code	The code BYRD207 indicates that an additional step is required to complete the payment, specifically the execution of 3D Secure (3DS) authentication.
action	Root node for any action available based on the request.
threeDSecure	Root node with information about 3DS.
threeDSecure.id	A unique identifier for initiating the 3DS flow using the SDK.
threeDSecure.verificationMethod	Verification method used. Default is ThreeDSecure.
threeDSecure.channel	Authentication channel. Default is Browser.
threeDSecure.status	Status of the 3DS process. Initially, this should be Created.
requestId	The identification of the request in our service.

Using the SDK with threeDSecure.Id

1- Use the threeDSecure.Id and requestId value from the payment response to initiate the 3DS authentication within the Paybyrd SDK.

2- The SDK will handle the 3DS authentication process directly within your application.

3- Once the 3DS process is complete, retrieve the authentication result and execute the payment accordingly.

Key Advantages:

Provides a seamless, in-app experience for customers, avoiding redirection.
Offers more control over the user interface and payment flow, suitable for custom or embedded payment solutions.

3. Installing & Using Paybyrd ThreeDSecure SDK

You can install the SDK as follows:

npm i @paybyrd/threedsecure-service-js

yarn add @paybyrd/threedsecure-service-js

The SDK is compatible with TypeScript, allowing easy identification of required fields and configurations for the correct execution of 3DS on your website.

Configuring the SDK

Once installed, we need to configure the SDK. The following parameters are available:

Parameter	Required	Description	Default
container	Yes	The HTML element responsible for displaying all screens needed for the challenge	-
challengeWindowSize	No	The size of the window available for displaying the challenge	100%
threeDSecureUrl	No	URL of the 3DS service	https://threedsecure.paybyrd.com
culture	No	Culture provided in some calls to the authenticator and API	en-US
timeoutInSeconds	No	Maximum wait time for each request	30

To configure the service, execute the following script:

const threeDSService = new ThreeDSecureService({
    container,
});

Executing

To initiate the 3DS authentication, you will need the threeDSecure.id and requestId returned during payment creation.

📘
The requestId is not mandatory, but allows proper referencing of the entire payment flow.

const threeDSRequest = {
  id: createPaymentResponse.threeDSecure.id,
  correlationId: createPaymentResponse.requestId
};
try {
  const threeDSResponse = await threeDSecureService.execute(threeDSRequest);
} catch (error) {
  // unexpected error
}

This call allows the SDK to handle the entire 3DS authentication flow, and based on the authentication result, Paybyrd will automatically initiate the payment process, completing the transaction seamlessly.

Verify Payment Result

After executing the 3DS flow, it’s essential to verify the payment result to determine whether the transaction was successful. The response contains multiple fields that provide insight into the authentication status, payment outcome, and any potential errors. Below is an explanation of the key fields and their significance, along with examples to help interpret the responses.

Please make sure to look at all the examples of the response below:

{
    "callbackUrl": "https://tppropayment.suitairibe.com/paymentHub/tap/paybyrd/redirect?correlationId=c2065871-431e-4ae8-a476-fffbe2560293&transactionId=b216c11e-5235-4460-b0e2-106ca54c63a7",
    "transactionId": "b216c11e-5235-4460-b0e2-106ca54c63a7",
    "status": "Authorized",
    "paymentStatus": "Success",
    "gatewayResponse": {
        "status": "Success",
        "code": "BYRD200",
        "description": "Operation successfully completed",
        "errorDetails": null
    },
    "authenticationData": {
        "threeDsVersion": "V2",
        "aav": "kBMQDhqw04iJEl2wdcJi1Zhhs0s9",
        "dsTransactionId": "5ab3efd2-aadc-46b5-8b86-3194e1aece83",
        "eci": "02",
        "verificationMethod": "ThreeDSecure",
        "protocolVersion": "2.2.0"
    },
    "code": null,
    "message": null,
    "details": null,
    "executePayment": true,
    "authorizationTransStatus": "C",
    "authorizationTransStatusReason": null,
    "transStatus": "Y",
    "transStatusReason": null
}

{
  "callbackUrl": "https://paybyrd.com/?correlationId=eb0ea1fc-5d3b-4e59-af3f-0ea9d2959a12&transactionId=a773a590-b607-408f-bf41-7c8448f4ee44",
  "transactionId": "a773a590-b607-408f-bf41-7c8448f4ee44",
  "status": "NotEnrolled",
  "paymentStatus": "Success",
  "gatewayResponse": {
    "status": "Success",
    "code": "BYRD200",
    "description": "Operation successfully completed",
    "errorDetails": null
  },
  "authenticationData": {
    "threeDsVersion": "V2",
    "aav": null,
    "dsTransactionId": null,
    "eci": null,
    "verificationMethod": "ThreeDSecure",
    "protocolVersion": null
  },
  "code": "305",
  "message": "Not enrolled simulation",
  "details": "An error was simulated",
  "executePayment": true,
  "authorizationTransStatus": null,
  "authorizationTransStatusReason": null,
  "transStatus": "N",
  "transStatusReason": "01"
}

{
  "callbackUrl": "https://paybyrd.com/?correlationId=63aa9ef5-5f90-47e2-b751-c931e8933081&transactionId=bd421c15-5e8c-4210-85ee-d3bb534ca53c",
  "transactionId": "bd421c15-5e8c-4210-85ee-d3bb534ca53c",
  "status": "Unauthorized",
  "paymentStatus": "Denied",
  "gatewayResponse": {
    "status": "Denied",
    "code": "BYRD205",
    "description": "Operation rejected",
    "errorDetails": {
      "acquirerResponseCode": null,
      "acquirerResponseMessage": null,
      "canRetry": false,
      "isChallengeRequired": false,
      "attempt": 1,
      "maxAttempts": null
    }
  },
  "authenticationData": {
    "threeDsVersion": "V2",
    "aav": null,
    "dsTransactionId": "7fed7b1c-c8be-4ce6-ae43-c78bf6b70eba",
    "eci": "07",
    "verificationMethod": "ThreeDSecure",
    "protocolVersion": "2.2.0"
  },
  "code": "899",
  "message": "Authorization failed",
  "details": "Security failure",
  "executePayment": true,
  "authorizationTransStatus": "N",
  "authorizationTransStatusReason": "09",
  "transStatus": "N",
  "transStatusReason": "09"    
}

{
  "callbackUrl": "https://paybyrd.com/?correlationId=fccca3d7-6f0f-426e-90f8-d96ee3b8c6d3&transactionId=f0b4d3d8-e161-4638-b049-543f2380d824",
  "transactionId": "f0b4d3d8-e161-4638-b049-543f2380d824",
  "status": "Authorized",
  "paymentStatus": "Denied",
  "gatewayResponse": {
    "status": "Denied",
    "code": "BYRD205",
    "description": "Operation rejected",
    "errorDetails": {
      "acquirerResponseCode": "58",
      "acquirerResponseMessage": "Unauthorized. Contact issuer",
      "canRetry": true,
      "isChallengeRequired": false,
      "attempt": 1,
      "maxAttempts": null
    }
  },
  "authenticationData": {
    "threeDsVersion": "V2",
    "aav": "7a636b2c808a44b28b876bb315c73995",
    "dsTransactionId": "348569bc-e1dd-4832-9e36-cbb23cca5054",
    "eci": "02",
    "verificationMethod": "ThreeDSecure",
    "protocolVersion": "2.2.0"
  },
  "code": null,
  "message": null,
  "details": null,
  "executePayment": true,
  "authorizationTransStatus": "C",
  "authorizationTransStatusReason": null,
  "transStatus": "Y",
  "transStatusReason": "17"
}

{
  "callbackUrl": "https://paybyrd.com/?correlationId=4375de6e-2eb4-4263-bf1b-7e3abf3f0e02&transactionId=d3c27736-4d3d-4888-9bae-30976e15b76d",
  "transactionId": "d3c27736-4d3d-4888-9bae-30976e15b76d",
  "status": "Authorized",
  "paymentStatus": "Error",
  "gatewayResponse": {
    "status": "Error",
    "code": "BYRD999",
    "description": "Operation failed",
    "errorDetails": {
      "acquirerResponseCode": null,
      "acquirerResponseMessage": null,
      "canRetry": true,
      "isChallengeRequired": false,
      "attempt": 1,
      "maxAttempts": null
    }
  },
  "authenticationData": {
    "threeDsVersion": "V2",
    "aav": "f998578d2f8d4908805cdc236ed2cde7",
    "dsTransactionId": "4c492ffd-a546-423b-939a-6045cced326b",
    "eci": "05",
    "verificationMethod": "ThreeDSecure",
    "protocolVersion": "2.2.0"
  },
  "code": null,
  "message": null,
  "details": null,
  "executePayment": true,
  "authorizationTransStatus": "C",
  "authorizationTransStatusReason": null,
  "transStatus": "Y",
  "transStatusReason": "17"
}

Field	Description	Possible Values
callbackUrl	Callback URL configured during payment creation
transactionId	ID of the transaction initially created in the Gateway
status	Represents the status of the 3DS authentication (e.g., Authorized, Unauthorized). Important: This field indicates the result of the authentication, not the final payment status.	Authorized, Unauthorized, Expired, NotEnrolled
paymentStatus	Indicates whether the payment was successful or not. You should use this field to determinate the final status of the transaction.	Success, Denied, Error
gatewayResponse	Contains additional details about the payment.
gatewayResponse.status	Final payment status	Success, Denied, Error
gatewayResponse.code	Response code
gatewayResponse.message	Error message
gatewayResponse.errorDetails	Provides additional context if the payment failed
gatewayResponse.errorDetails.acquirerResponseCode	The response code returned by the acquirer.
gatewayResponse.errorDetails.acquirerResponseMessage	The response message returned by the acquirer.
authenticationData	Root node of authentication data obtained from 3DS
authenticationData.threeDsVersion	3DS version used	V2
authenticationData.aav	Authorization code
authenticationData.dsTransactionId	ID of the transaction performed in the DS (Directory Server)
authenticationData.verificationMethod	Verification method used in the process	None or ThreeDSecure
authenticationData.protocolVersion	Protocol version used	2.2.0
code	Error code
message	Error message
details	Error details
authorizationTransStatus	Authorization status as per ACS (Access Control Server)	A, R, U, C, or N
authorizationTransStatusReason	Additional information about the above status
transStatus	Final status as per ACS	Y or N
transStatusReason	Additional information about the above status

If you have any questions, please contact our support.

SDK setup

Requirements

Step-by-step Guide

1. Initiating the Flow

🚧
We strongly recommend executing this request from your backend for enhanced security and reliability

Minimal Request example

Response example

📘
For more information about payment creation, see the documentation

2. Handle the Payment Response

Using the SDK with threeDSecure.Id

3. Installing & Using Paybyrd ThreeDSecure SDK

Configuring the SDK

Executing

📘
The `requestId` is not mandatory, but allows proper referencing of the entire payment flow.

Verify Payment Result

Requirements

Step-by-step Guide

1. Initiating the Flow

🚧We strongly recommend executing this request from your backend for enhanced security and reliability

Minimal Request example

Response example

📘For more information about payment creation, see the documentation

2. Handle the Payment Response

Using the SDK with threeDSecure.Id

3. Installing & Using Paybyrd ThreeDSecure SDK

Configuring the SDK

Executing

📘The requestId is not mandatory, but allows proper referencing of the entire payment flow.

Verify Payment Result

🚧
We strongly recommend executing this request from your backend for enhanced security and reliability

📘
For more information about payment creation, see the documentation

📘
The `requestId` is not mandatory, but allows proper referencing of the entire payment flow.