Skip to main content
This guide explains how to integrate Paybyrd’s 3D Secure (3DS) flow into your platform.

​
Requirements

  • API Key: Obtain your API key from the Developer Section in our dashboard.
  • SDK: Add the Paybyrd SDK to your site. The steps below show you how.

​
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}' \
 --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"
 }
}'
Execute this request from your backend. Sending card data from a client exposes credentials to end users.
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,
 "threeDSecure": {
   "id": "9e8cf073-c854-4534-97ae-1cea65695efb",
   "verificationMethod": "ThreeDSecure",
   "channel": "Browser",
   "status": "Created"
 }
}
For full details on payment creation, see the API reference.

​
2. Handle the Payment Response

If the response contains code BYRD207, 3D Secure authentication is required before the payment can complete. The response will include the following fields relevant to 3DS execution:
PropertyDescription
codeIndicates that 3DS authentication is required before the payment can complete.
actionRoot node for any action available based on the request.
threeDSecureRoot node with information about 3DS.
threeDSecure.idA unique identifier for initiating the 3DS flow using the SDK.
threeDSecure.verificationMethodVerification method used. Default is ThreeDSecure.
threeDSecure.channelAuthentication channel. Default is Browser.
threeDSecure.statusStatus of the 3DS process. Initially, this should be Created.
requestIdThe 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 proceed based on the returned status.
The SDK handles 3DS authentication inside your application without redirecting the customer.