SDK setup

Requirements

API Key: Obtain your API key from the Developer Section in our dashboard.
SDK: Add the Paybyrd SDK to your site.

Step-by-step Guide

1. Initiate the flow

Create 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}' \
 --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}'
  }
});
console.log(response.data);

using var client = new HttpClient();

client.DefaultRequestHeaders.Add("x-api-key", "{your_api_key}");

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}";
$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}"
}

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())

Example response

{
 "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"
 }
}

Execute this request from your backend. Sending card data from a client exposes credentials to end users.

For full details on payment creation, see the API reference.

2. Handle the Payment Response

Code BYRD207 means 3DS authentication is required before the payment can complete. The response includes these 3DS fields:

Property	Description
code	`BYRD207` means 3DS authentication is required before the payment can complete.
action	Contains action data for the request.
threeDSecure	Contains 3DS authentication data.
threeDSecure.id	Identifier used to initiate the 3DS flow in 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 `Created`.
requestId	Request identifier in the Paybyrd service.

Using the SDK with threeDSecure.id

Use the threeDSecure.id and requestId values from the payment response to initiate 3DS authentication in the Paybyrd SDK.
Once the 3DS process is complete, retrieve the authentication result and proceed based on the returned status.

The SDK handles 3DS authentication inside your application without redirecting the customer. You control the UI and payment flow.

3. Install and use the Paybyrd ThreeDSecure SDK

Install the SDK:

npm i @paybyrd/threedsecure-service-js

yarn add @paybyrd/threedsecure-service-js

The SDK is compatible with TypeScript.

Configure the SDK

Parameter	Required	Description	Default
container	Yes	HTML element for displaying challenge screens	—
challengeWindowSize	No	Size of the challenge window	100%
threeDSecureUrl	No	URL of the 3DS service	https://threedsecure.paybyrd.com
culture	No	Culture passed to the authenticator and API	en-US
timeoutInSeconds	No	Maximum wait time per request	30

Create a service instance:

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

Execute

Pass threeDSecure.id and requestId from the payment response:

The requestId is optional but links the 3DS result to the original payment request.

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

The SDK handles the entire 3DS flow and submits the payment once authentication completes.

Verify the payment result

After the 3DS flow completes, check the payment result. Use paymentStatus to determine the final transaction outcome.

{
    "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 created in the gateway
status	3DS authentication result. Use `paymentStatus` for the final payment outcome, not this field.	Authorized, Unauthorized, Expired, NotEnrolled
paymentStatus	Payment outcome. Use this field to determine the final transaction result.	Success, Denied, Error
gatewayResponse	Contains additional payment details.
gatewayResponse.status	Final payment status	Success, Denied, Error
gatewayResponse.code	Response code
gatewayResponse.message	Error message
gatewayResponse.errorDetails	Additional context when the payment failed
gatewayResponse.errorDetails.acquirerResponseCode	Response code returned by the acquirer
gatewayResponse.errorDetails.acquirerResponseMessage	Response message returned by the acquirer
authenticationData	Contains 3DS authentication data.
authenticationData.threeDsVersion	3DS version used	V2
authenticationData.aav	Authorization code
authenticationData.dsTransactionId	ID of the transaction in the Directory Server
authenticationData.verificationMethod	Verification method used	None, ThreeDSecure
authenticationData.protocolVersion	Protocol version used	2.2.0
code	Error code
message	Error message
details	Error details
authorizationTransStatus	Authorization status per ACS (Access Control Server)	A, R, U, C, N
authorizationTransStatusReason	Additional information about `authorizationTransStatus`
transStatus	Final status per ACS	Y, N
transStatusReason	Additional information about `transStatus`

Get Started

Advanced

Requirements

Step-by-step Guide

1. Initiate the flow

2. Handle the Payment Response

Using the SDK with threeDSecure.id

3. Install and use the Paybyrd ThreeDSecure SDK

Configure the SDK

Execute

Verify the payment result

​Requirements

​Step-by-step Guide

​1. Initiate the flow

​2. Handle the Payment Response

​Using the SDK with threeDSecure.id

​3. Install and use the Paybyrd ThreeDSecure SDK

​Configure the SDK

​Execute

​Verify the payment result

Requirements

Step-by-step Guide

1. Initiate the flow

2. Handle the Payment Response

Using the SDK with threeDSecure.id

3. Install and use the Paybyrd ThreeDSecure SDK

Configure the SDK

Execute

Verify the payment result