Requirements
The only requirement is an API key.You can find your API key in the Developers section of the dashboard.
Select the correct environment before making requests.
Step-by-step Guide
1. Initiate the flow
Send 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())
Execute this request from your backend. Sending card data from a client exposes credentials to end users.
{
"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 full details on payment creation, see the API reference.
2. Handle the response
The response includes these fields relevant to the 3DS flow:| Property | Description |
|---|---|
| action | Contains action data for the request. |
| action.type | Action type. |
| action.url | When type is redirect, the URL to send the customer to. |
| threeDSecure | Contains 3DS authentication data. |
| threeDSecure.id | Identifier for the 3DS process. |
| threeDSecure.verificationMethod | Verification method used. Default is ThreeDSecure. |
| threeDSecure.channel | Authentication channel. Default is Browser. |
| threeDSecure.status | Status of the 3DS process. Initially Created. |
action.url to continue the payment.
3. Authentication challenge
The customer sees an authentication screen (challenge) to verify their identity with the card issuer. After authentication, the customer is redirected to theredirectUrl specified during payment creation.
Redirection happens in both success and failure scenarios. Query the transaction to determine the outcome. See Query transactions.
The final transaction result is also sent via webhook. See Webhooks.

