# iDEAL | Wero
Source: https://docs.paybyrd.com/accept-payments/bank-transfers/ideal-wero
iDEAL | Wero is an online payment method that enables consumers to pay online through their own bank. In addition to webshops, other organizations that are not part of the e-commerce market also offer this payment method. iDEAL | Wero is used beyond e-commerce — for energy bills, donations, mobile credits, and local taxes.
## How it works
![Flowchart depicting iDEAL | Wero payment flow]()
When a customer selects iDEAL | Wero, they are redirected to their bank's online banking page to log in and complete the payment. Regardless of the outcome, the customer is then redirected to the merchant store. The transaction result is delivered via webhook. Query the API or listen for webhook notifications to confirm the final status.
We accept the following banks:
| Bank code | Bank name |
| --------- | ------------- |
| BUNQNL2A | Bunq |
| INGBNL2A | Ing |
| KNABNL2H | Knab |
| RABONL2U | Rabobank |
| RBRBNL21 | RegioBank |
| SNSBNL2A | SNS Bank |
| TRIONL2U | Triodos Bank |
| ABNANL2A | ABN AMRO |
| FVLBNL22 | Van Lanschot |
| ASNBNL21 | ASN |
| HANDNL2A | Handelsbanken |
| REVOLT21 | Revolut |
```bash theme={null}
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":"OnlineTransfer",
"amount": "10.00",
"currency": "EUR",
"brand":"ideal",
"bankIdentifierCode": "INGBNL2A"
}'
```
```json theme={null}
{
"bankIdentifierCode": "INGBNL2A",
"type": "OnlineTransfer",
"currency": "EUR",
"brand": "ideal",
"action": {
"type": "redirect",
"url": "https://webapp-redirect-api-stg.azurewebsites.net/api/v1/Redirect/58d75973-87e3-4da7-b8f4-ab2bfb3ea9da"
},
"code": "BYRD207",
"description": "Pending redirect",
"transactionId": "58d75973-87e3-4da7-b8f4-ab2bfb3ea9da",
"amount": "10.00"
}
```
# Ref. Multibanco
Source: https://docs.paybyrd.com/accept-payments/bank-transfers/multibanco
Multibanco is the most popular payment method in Portugal, allowing consumers to pay via online banking or in cash at a bank branch.
**Expiration:** The payment must be completed in seven days.
## How it works
![Flowchart depicting Multibanco payment flow]()
Multibanco is an asynchronous payment method. When you create a payment, Paybyrd receives a response from Multibanco confirming the payment was created. The transaction then remains in a processing status until the customer pays.
Once a Multibanco reference is generated, the order is locked — the customer cannot switch to a different payment method. If the customer needs to pay with a different method, a new order must be created. As soon as the customer completes the payment, the Multibanco system notifies Paybyrd, and the transaction is updated to succeeded or failed. The customer can complete the payment through any ATM or online banking, using the payment data returned in the payment creation response.
## Create payment
The example below shows a simple request to create a Multibanco payment and the corresponding response:
```bash Create payment request theme={null}
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": "OnlineTransfer",
"amount": "8.15",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "Sibs_Multibanco",
"redirectUrl": "https://your-shop-url?orderRef=ABC12345"
}'
```
```json Create payment request theme={null}
{
"multibanco": {
"serviceSupplierId": "11854",
"paymentReference": "999999935",
"waitForNotification": "1",
"redirectOptional": "1"
},
"type": "OnlineTransfer",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "Sibs_Multibanco",
"redirectUrl": "https://your-shop-url?orderRef=ABC12345",
"code": "BYRD207",
"description": "Pending redirect",
"transactionId": "39824983-4a13-42d4-8e85-e2821e494975",
"amount": "8.15",
"action": {
"type": "redirect",
"url": "https://gateway.paybyrd.com/api/v1/Redirect/39824983-4a13-42d4-8e85-e2821e494975"
}
}
```
See the [full API reference](/api-reference/payments/create-payment) for more details.
Check the `code` field to know whether the transaction was accepted. A successful scenario returns the code `BYRD207`. You can find the list of all status codes in the [Respone code reference](/api-reference/api-code-reference).
# Multicaixa Express
Source: https://docs.paybyrd.com/accept-payments/bank-transfers/multicaixa-express
Multicaixa Express is an interbank mobile channel that allows users to add multiple Multicaixa cards to the Multicaixa Express mobile app.
The customer only needs their mobile phone to make a payment. The customer authorizes the payment within 90 seconds. Multicaixa Express is well suited for mobile applications and websites.
Multicaixa Express is only available in Angola.
## How it works
![Flowchart depicting Multicaixa Express payment flow]()
Multicaixa Express is an asynchronous payment method. When you create a payment, the system confirms its creation and the transaction enters a "processing" status. The status remains "processing" until the customer completes the payment.
Once a reference is generated, the order is locked — the customer cannot switch to a different payment method. If the customer needs to pay with a different method, a new order must be created. Once the customer pays, Multicaixa Express sends a notification and the payment status updates to either "successful" or "failed".
## Create order
The following example creates an order:
```bash theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"orderRef": "MULTICAIXAEXPRESS",
"isoAmount": 30010,
"currency": "EUR",
"marketId": "PT",
"orderOptions": {
"culture": "pt-PT"
},
"paymentOptions": {
"allowedPaymentMethods": [
"MULTICAIXAEXPRESS"
]
},
"shopper": {
"firstName": "Peter",
"lastName": "Parker",
"email": "peter@parker.com"
}
}'
```
## Create payment
The following example creates a Multicaixa Express payment:
```bash theme={null}
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":"OnlineTransfer",
"amount": "100.00",
"currency": "EUR",
"brand":"MULTICAIXAEXPRESS",
"phoneNumber": "351#900000000"
}'
```
## Payment Flow
The Multicaixa Express integration now supports a new payment experience built around QR Code payments and deeplink redirection, in addition to the existing phone-initiated flow.
### Desktop and Web
Once the order is created, Paybyrd Checkout displays a QR Code for the buyer to scan. Scanning it redirects them into the MultiCaixa Express app to complete the payment.
### Mobile
If the buyer is already on a mobile device, tapping the **Pay** button in Paybyrd Checkout automatically redirects them to the MultiCaixa Express app, where the payment is completed directly.
## Response Fields
When the transaction brand is `MULTICAIXAEXPRESS`, the API response includes a `multicaixaExpress` object with the following fields:
| Field | Type | Description |
| ------------------ | ----------------- | ------------------------------------------------------------------------ |
| `deeplink` | string (uri) | Direct deeplink for the MultiCaixa Express app. |
| `deeplinkRedirect` | string (uri) | Redirect URL for mobile and browser flows to the MultiCaixa Express app. |
| `qrCodeUrl` | string (uri) | QR Code image URL. |
| `expiresAt` | string (ISO 8601) | Payment expiration timestamp. |
```json theme={null}
{
"multicaixaExpress": {
"deeplink": "mcxwallet://purchase?qrref=...",
"deeplinkRedirect": "https://api.sandbox.proxypay.co.ao/deeplink/...",
"qrCodeUrl": "https://api.sandbox.proxypay.co.ao/qrcode/...",
"expiresAt": "2026-05-21T18:00:37"
}
}
```
Visit the [API reference](/api-reference/payments/create-payment) for more details.
## Testing
The mobile number you use in the Create payment request determines the final status of the transaction. Use these phone numbers to test different scenarios:
| Mobile | Status | Reason | Details |
| :-------- | :------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 900000000 | accepted | N/A | Simulates an accepted transaction by the customer. Occurs 5 to 20 seconds after request. |
| 900002004 | rejected | 2004 | Simulates the timeout incurred when the customer receives the payment request but fails to accept it within the time limit. Occurs 90 seconds after request. |
| 900003000 | rejected | 3000 | Simulates a customer refusal. Occurs in 5 to 20 seconds after request. |
| 9XXXXXXXX | rejected | 2010 | Simulates a refusal from the processor. Occurs immediately after request. |
# SEPA
Source: https://docs.paybyrd.com/accept-payments/bank-transfers/sepa
The Single Euro Payments Area (SEPA) simplifies payments within and across member countries. It establishes and enforces banking standards that allow direct debiting of any EUR-denominated bank account within the SEPA region.
Businesses must collect their customer's name and bank account number in IBAN format to debit an account. Customers must accept a mandate that gives the business authorization to debit the account during the payment flow. We will generate this mandate for businesses to present to their customers.
## How it works
![Flowchart depicting SEPA payment flow]()
SEPA is an asynchronous payment method. When you create a payment, Paybyrd receives confirmation that it was created, and the transaction enters a processing status while waiting for the customer to accept the debit mandate. As soon as the customer accepts the debit, we will continue the process. Once the debit is confirmed or rejected, Paybyrd receives a notification and updates the payment status to succeeded or failed.
SEPA Direct Debit is a delayed notification payment method. This means that it can take up to 14 business days to receive notification on the success or failure payment after you initiate. The average confirmation takes five business days.
## Create payment
The following example shows a simple request to create a SEPA payment and its response:
```bash theme={null}
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":"OnlineTransfer",
"amount": "10.00",
"currency": "EUR",
"brand":"SEPA",
"iban": "PT55003506519623339578249",
"email": "peter@parker.com",
"country": "PRT"
}'
```
```json theme={null}
{
"type": "OnlineTransfer",
"currency": "EUR",
"brand": "SEPA",
"action": {
"type": "redirect",
"url": "https://webapp-redirect-api-stg.azurewebsites.net/api/v1/Redirect/677b2968-41b5-4886-94f6-c77c2d4791bf"
},
"code": "BYRD207",
"description": "Pending redirect",
"transactionId": "677b2968-41b5-4886-94f6-c77c2d4791bf",
"amount": "10.00"
}
```
See the full API reference [here](/api-reference/payments/create-payment).
Check the `code` field to know whether the transaction was accepted. A successful scenario returns the code `BYRD207`. You can find the list of all status codes in the [Respone code reference](/api-reference/api-code-reference).
# Floa
Source: https://docs.paybyrd.com/accept-payments/buy-now-pay-later/floa
Floa is a Buy Now Pay Later (BNPL) payment solution: customers can split the payment for their purchases into multiple installments.
FLOA is only available in France, Portugal, Italy, Spain, Belgium, and Germany.
## How it works
![Flowchart depicting Floa payment flow]()
Floa is a synchronous payment method — no redirect occurs. The customer fills in the required fields and submits the payment. Paybyrd processes the request and returns a success or failure response directly, without redirecting to an external page.
If shopper information is provided in the order, the payment form fields are pre-filled, though the customer must still confirm and submit.
We provide the following Floa payment methods:
| Method | Code | Description |
| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Payment in 3 times | `FLOA3X` | The customer pays in 3 installments, each 30 days apart. |
| Payment in 4 times | `FLOA4X` | The customer pays in 4 installments, each 30 days apart. |
| Deferred cash payment | `FLOA1XD` | The customer pays in a single deferred payment. In France, deferral can be between 1 and 30 days. In all other supported countries, deferral must be either 14 or 30 days. |
## Create order
The following example shows how to create an order and the response it generates:
### Generic shopping cart
```bash Request theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"marketId": "PT",
"isoAmount": 5000,
"orderRef": "New Order",
"currency": "EUR",
"orderOptions": {
"culture": "en-US"
},
"shopper": {
"email": "peter@parker.com",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "999999999",
"homeAddress": "Rua Rodrigo da Fonseca, 15 - 3H",
"homePostalCode": "1250189",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"ipAddress": "192.168.0.1",
"firstPurchaseDate": "2023-12-19T19:30:00Z",
"lastPurchaseDate": "2023-12-19T19:30:00Z",
"shippingAddress": "Av. Guerra Junqueiro 2A",
"shippingPostalCode": "1000167",
"shippingCity": "Lisbon",
"shippingState": "LB",
"shippingCountry": "PRT",
"customReference": "spiderman"
},
"shoppingCart": {
"items": [
{
"description": "Web launcher",
"amount": 5000,
"categories": [
"Category 2",
"Category 1"
],
"shipping": {
"shippingMethod": "STD"
},
"type": "Product"
}
]
},
"paymentOptions": {
"allowedPaymentMethods": [
"FLOA3X",
"FLOA4X",
"FLOA1XD"
]
}
}'
```
```json Response theme={null}
{
"orderDate": "2024-05-06T18:03:45Z",
"status": "created",
"checkoutUrl": "https://link-s.paybyrd.com/chk_KydBswaR5",
"tags": 0,
"index": 1,
"transactions": [],
"orderId": "4d438d44-5609-4aic-ac5d-a948c7e39455",
"amount": "5000",
"currency": "EUR",
"orderRef": "New Order",
"shopper": {
"customReference": "spiderman",
"shopperId": "ecbd5431-af46-4c3e-9e0c-0117671fd907",
"email": "peter.parker@spidermail.com",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "999999999",
"shippingAddress": "Av. Guerra Junqueiro 2A",
"shippingPostalCode": "1000167",
"shippingCity": "Lisbon",
"shippingState": "LB",
"shippingCountry": "PRT",
"homeAddress": "Rua Rodrigo da Fonseca, 15 - 3H",
"homePostalCode": "1250189",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"shippingType": "Undefined",
"firstPurchaseDate": "2023-12-19T19:30:00+00:00",
"lastPurchaseDate": "2023-12-19T19:30:00+00:00"
},
"orderOptions": {
"redirectUrl": "https://paybyrd.com/",
"culture": "en-US",
"sendBy": []
},
"paymentOptions": {
"useSimulated": true,
"cardOptions": {
"isPreAuth": false,
"isDccEnabled": false
},
"tokenOptions": {
"tokenizationMethod": "none"
},
"allowedPaymentMethods": [
"FLOA3X",
"FLOA4X",
"FLOA1XD"
]
},
"terminalOptions": {
"notifyChanges": false
},
"shoppingCart": {
"items": [
{
"amount": 5000,
"categories": [
"Category 2",
"Category 1"
],
"description": "Web launcher",
"shipping": {
"shippingMethod": "STD"
},
"type": "Product"
}
]
},
"marketId": "PT",
"code": "BYRD200",
"description": "Operation successfully completed",
"checkoutKey": "eyJPcmRlcklkIjoiNGQ0MzhkNDQtNTYwOS00YWRjLWFjNWQtYTk0OGM3ZTM5NDU1IiwiT3JkZXJSZWYiOiJOZXcgT3JkZXIiLCJQZXJzb25JZCI6MzMwOCwiTGl2ZSI6ZmFsc2UsIkVudGl0eUlkIjoiNGQ0MzhkNDQtNTYwOS00YWRjLWFjNWQtYTk0OGM3ZTM5NDU1IiwiQW1vdW50IjoiMjUwMC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0="
}
```
### Airline shopping cart
For an airline shopping cart, you must set the item type to `Travel` and the category to `AIRLINE TICKET`.
```bash Request theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"marketId": "PT",
"isoAmount": 100000,
"orderRef": "New Order",
"currency": "EUR",
"orderOptions": {
"culture": "en-US"
},
"shopper": {
"email": "peter.parker@spidermail.com",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "999999999",
"homeAddress": "Rua Rodrigo da Fonseca, 15 - 3H",
"homePostalCode": "1250189",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"ipAddress": "192.168.0.1",
"firstPurchaseDate": "2023-12-19T19:30:00Z",
"lastPurchaseDate": "2023-12-19T19:30:00Z",
"shippingAddress": "Av. Guerra Junqueiro 2A",
"shippingPostalCode": "1000167",
"shippingCity": "Lisbon",
"shippingState": "LB",
"shippingCountry": "PRT",
"customReference": "spiderman"
},
"shoppingCart": {
"items": [
{
"description": "Travel",
"amount": 100000,
"categories": [
"AIRLINE TICKET"
],
"shipping": {
"shippingMethod": "VIR"
},
"type": "Travel",
"hasInsurance": false,
"travelType": "TwoWay",
"departureDate": "2024-12-19T19:30:00Z",
"returnDate": "2024-12-31T15:30:00Z",
"departure": "GIG",
"destination": "LIS",
"destinationCountryCode": "PRT",
"travelersCount": 1,
"mainDepartureCompany": "LP"
}
]
},
"paymentOptions": {
"allowedPaymentMethods": [
"FLOA3X",
"FLOA4X",
"FLOA1XD"
]
}
}'
```
```json Response theme={null}
{
"orderDate": "2024-05-06T18:03:45Z",
"status": "created",
"checkoutUrl": "https://link-s.paybyrd.com/chk_KydBswaR5",
"tags": 0,
"index": 1,
"transactions": [],
"orderId": "4d438d44-5609-4aic-ac5d-a948c7e39455",
"amount": "100000",
"currency": "EUR",
"orderRef": "New Order",
"shopper": {
"customReference": "spiderman",
"shopperId": "ecbd5431-af46-4c3e-9e0c-0117671fd907",
"email": "peter.parker@spidermail.com",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "999999999",
"shippingAddress": "Av. Guerra Junqueiro 2A",
"shippingPostalCode": "1000167",
"shippingCity": "Lisbon",
"shippingState": "LB",
"shippingCountry": "PRT",
"homeAddress": "Rua Rodrigo da Fonseca, 15 - 3H",
"homePostalCode": "1250189",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"shippingType": "Undefined",
"firstPurchaseDate": "2023-12-19T19:30:00+00:00",
"lastPurchaseDate": "2023-12-19T19:30:00+00:00"
},
"orderOptions": {
"redirectUrl": "https://paybyrd.com/",
"culture": "en-US",
"sendBy": []
},
"paymentOptions": {
"useSimulated": true,
"cardOptions": {
"isPreAuth": false,
"isDccEnabled": false
},
"tokenOptions": {
"tokenizationMethod": "none"
},
"allowedPaymentMethods": [
"FLOA3X",
"FLOA4X",
"FLOA1XD"
]
},
"terminalOptions": {
"notifyChanges": false
},
"shoppingCart": {
"items": [
{
"description": "Travel",
"amount": 100000,
"categories": [
"AIRLINE TICKET"
],
"shipping": {
"shippingMethod": "VIR"
},
"type": "Travel",
"hasInsurance": false,
"travelType": "TwoWay",
"departureDate": "2024-12-19T19:30:00Z",
"returnDate": "2024-12-31T15:30:00Z",
"departure": "GIG",
"destination": "LIS",
"destinationCountryCode": "PRT",
"travelersCount": 1,
"mainDepartureCompany": "LP"
}
]
},
"marketId": "PT",
"code": "BYRD200",
"description": "Operation successfully completed",
"checkoutKey": "eyJPcmRlcklkIjoiNGQ0MzhkNDQtNTYwOS00YWRjLWFjNWQtYTk0OGM3ZTM5NDU1IiwiT3JkZXJSZWYiOiJOZXcgT3JkZXIiLCJQZXJzb25JZCI6MzMwOCwiTGl2ZSI6ZmFsc2UsIkVudGl0eUlkIjoiNGQ0MzhkNDQtNTYwOS00YWRjLWFjNWQtYTk0OGM3ZTM5NDU1IiwiQW1vdW50IjoiMjUwMC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0="
}
```
### Hotel shopping cart
For a hotel or stay shopping cart, you must set the item type to `TravelWithStay` and the category to `HOTEL` or `STAY`.
```bash Request theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"marketId": "PT",
"isoAmount": 80000,
"orderRef": "New Order",
"currency": "EUR",
"orderOptions": {
"culture": "en-US"
},
"shopper": {
"email": "peter.parker@spidermail.com",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "999999999",
"homeAddress": "Rua Rodrigo da Fonseca, 15 - 3H",
"homePostalCode": "1250189",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"ipAddress": "192.168.0.1",
"firstPurchaseDate": "2023-12-19T19:30:00Z",
"lastPurchaseDate": "2023-12-19T19:30:00Z",
"shippingAddress": "Av. Guerra Junqueiro 2A",
"shippingPostalCode": "1000167",
"shippingCity": "Lisbon",
"shippingState": "LB",
"shippingCountry": "PRT",
"customReference": "spiderman"
},
"shoppingCart": {
"items": [
{
"description": "Stay",
"amount": 80000,
"categories": [
"HOTEL"
],
"shipping": {
"shippingMethod": "VIR"
},
"CheckInDate": "2024-12-01",
"CheckOutDate": "2024-12-07",
"destinationCountryCode": "PRT",
"guestsCount": 2,
"type": "TravelWithStay",
"roomRange": 4
}
]
},
"paymentOptions": {
"allowedPaymentMethods": [
"FLOA3X",
"FLOA4X",
"FLOA1XD"
]
}
}'
```
```json Response theme={null}
{
"orderDate": "2024-05-06T18:03:45Z",
"status": "created",
"checkoutUrl": "https://link-s.paybyrd.com/chk_KydBswaR5",
"tags": 0,
"index": 1,
"transactions": [],
"orderId": "4d438d44-5609-4aic-ac5d-a948c7e39455",
"amount": "80000",
"currency": "EUR",
"orderRef": "New Order",
"shopper": {
"customReference": "spiderman",
"shopperId": "ecbd5431-af46-4c3e-9e0c-0117671fd907",
"email": "peter.parker@spidermail.com",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "999999999",
"shippingAddress": "Av. Guerra Junqueiro 2A",
"shippingPostalCode": "1000167",
"shippingCity": "Lisbon",
"shippingState": "LB",
"shippingCountry": "PRT",
"homeAddress": "Rua Rodrigo da Fonseca, 15 - 3H",
"homePostalCode": "1250189",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"shippingType": "Undefined",
"firstPurchaseDate": "2023-12-19T19:30:00+00:00",
"lastPurchaseDate": "2023-12-19T19:30:00+00:00"
},
"orderOptions": {
"redirectUrl": "https://paybyrd.com/",
"culture": "en-US",
"sendBy": []
},
"paymentOptions": {
"useSimulated": true,
"cardOptions": {
"isPreAuth": false,
"isDccEnabled": false
},
"tokenOptions": {
"tokenizationMethod": "none"
},
"allowedPaymentMethods": [
"FLOA3X",
"FLOA4X",
"FLOA1XD"
]
},
"terminalOptions": {
"notifyChanges": false
},
"shoppingCart": {
"items": [
{
"roomRange": 4,
"checkInDate": "2024-12-01T00:00:00-03:00",
"checkOutDate": "2024-12-07T00:00:00-03:00",
"destinationCountryCode": "PRT",
"guestsCount": 2,
"amount": 80000,
"categories": [
"HOTEL"
],
"description": "Stay",
"shipping": {
"shippingMethod": "VIR"
},
"type": "TravelWithStay"
}
]
},
"marketId": "PT",
"code": "BYRD200",
"description": "Operation successfully completed",
"checkoutKey": "eyJPcmRlcklkIjoiNGQ0MzhkNDQtNTYwOS00YWRjLWFjNWQtYTk0OGM3ZTM5NDU1IiwiT3JkZXJSZWYiOiJOZXcgT3JkZXIiLCJQZXJzb25JZCI6MzMwOCwiTGl2ZSI6ZmFsc2UsIkVudGl0eUlkIjoiNGQ0MzhkNDQtNTYwOS00YWRjLWFjNWQtYTk0OGM3ZTM5NDU1IiwiQW1vdW50IjoiMjUwMC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0="
}
```
***
## Create payment from order
You can create a Floa payment by passing the `checkoutKey` from the order response:
```bash Request theme={null}
curl --request POST \
--url 'https://gateway.paybyrd.com/api/v2/payment?checkoutKey=eyJPcmRlcklkIjoiNGQ0MzhkNDQtNTYwOS00YWRjLWFjNWQtYTk0OGM3ZTM5NDU1IiwiT3JkZXJSZWYiOiJOZXcgT3JkZXIiLCJQZXJzb25JZCI6MzMwOCwiTGl2ZSI6ZmFsc2UsIkVudGl0eUlkIjoiNGQ0MzhkNDQtNTYwOS00YWRjLWFjNWQtYTk0OGM3ZTM5NDU1IiwiQW1vdW50IjoiMjUwMC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0%3D' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"type": "BNPL",
"amount": "50.00",
"currency": "EUR",
"culture": "en-US",
"brand": "FLOA3X",
"salesChannel": "Desktop",
"orderRef": "New Order",
"shopper": {
"phoneCountryCode": 351,
"phoneNumber": "11953259340",
"email": "peter.parker@spidermail.com",
"firstName": "Peter",
"lastName": "Parker",
"homeAddress": "Rua Rodrigo da Fonseca, 15 - 3H",
"homeCountry": "PRT",
"homePostalCode": "1250-189",
"homeCity": "Lisbon",
"civility": "Mr",
"birthName": "Peter",
"birthDate": "1962-08-01",
"documentNumber": "123456789",
"birthPostalCode": "99"
}
}'
```
```json Response theme={null}
{
"culture": "en-US",
"salesChannel": "Desktop",
"type": "Bnpl",
"currency": "EUR",
"orderRef": "New Order",
"brand": "FLOA3X",
"paymentMethod": "floa",
"redirectUrl": "https://paybyrd.com/",
"action": {
"type": "redirect",
"url": "https://webapp-redirect-api-stg.azurewebsites.net/api/v1/Redirect/8cc2ee46-0380-4687-b56b-0079f4c53850"
},
"shopper": {
"customReference": "spiderman",
"email": "peter.parker@spidermail.com",
"firstName": "Peter",
"lastName": "Parker",
"birthName": "Peter",
"birthDate": "1962-08-01T00:00:00",
"birthPostalCode": "99",
"civility": "Mr",
"phoneCountryCode": 351,
"phoneNumber": "11953259340",
"ipAddress": "189.113.67.75",
"shippingAddress": "Av. Guerra Junqueiro 2A",
"shippingPostalCode": "1000167",
"shippingCity": "Lisbon",
"shippingCountry": "PRT",
"homeAddress": "Rua Rodrigo da Fonseca, 15 - 3H",
"homePostalCode": "1250-189",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"documentNumber": "123456789",
"firstPurchaseDate": "2023-12-19T19:30:00+00:00",
"lastPurchaseDate": "2023-12-19T19:30:00+00:00"
},
"code": "BYRD207",
"description": "Pending redirect",
"status": "Processing",
"requestId": "4fc10ecd-46b1-4e0e-8702-40f62e3d2e24",
"ipAddress": "139.113.64.75",
"externalTransactionIdentifier": "0c3b24c9-97b6-4b3f-8f0d-556ea38fabb2",
"marketId": "PT",
"transactionId": "8cc2ee46-0380-4687-b56b-0079f4c53850",
"amount": "50.00",
"isoAmount": 5000
}
```
To check whether the transaction was accepted, look at the **code** field. A successful response returns **BYRD207**. See the [Create Payment](/api-reference/payments/create-payment) API reference for the full list of request parameters, and the [API code reference](/api-reference/api-code-reference) for all possible codes.
# Klarna
Source: https://docs.paybyrd.com/accept-payments/buy-now-pay-later/klarna
Klarna is a Buy Now Pay Later (BNPL) payment method that lets customers defer or split payments at checkout.
## How it works
When a customer selects Klarna, they are redirected to the Klarna checkout page to complete payment. After payment, the customer is redirected back, but the transaction status may not be immediately available at that point. The final status is delivered asynchronously — use webhooks or query the API to confirm it.
Klarna provides the following payment methods:
| Method | Description |
| ------------------ | ------------------------------------------------- |
| Payment in 30 days | Buy now and pay within 30 days. |
| Financing | Spread the cost over monthly payments. |
| Payment in 3 times | Split the cost into 3 interest-free installments. |
## Create order
The following example shows how to create a Klarna order:
### Generic order
```bash Request theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"marketId": "PT",
"isoAmount": 5000,
"orderRef": "Klarna Product Order",
"currency": "EUR",
"orderOptions": {
"redirectUrl": "https://paybyrd.com",
"culture": "pt-PT"
},
"shopper": {
"email": "peter@parker.com",
"firstName": "Test",
"lastName": "Person-pt",
"phoneCountryCode": 351,
"phoneNumber": "935556731",
"shippingAddress": "Avenida Dom João II 40",
"shippingPostalCode": "1990-094",
"shippingCity": "Lisboa",
"shippingState": "LB",
"shippingCountry": "PRT",
"customReference": "spiderman",
"billingAddress": "Avenida Dom João II 40",
"billingPostalCode": "1990-094",
"billingCity": "Lisboa",
"billingCountry": "PRT"
},
"shoppingCart": {
"items": [
{
"description": "Web launcher",
"quantity": 1,
"unitPrice": 5000,
"amount": 5000,
"categories": [
"weapons",
"launchers"
],
"shipping": {
"shippingMethod": "STD"
},
"type": "Product"
}
]
},
"paymentOptions": {
"allowedPaymentMethods": [
"KLARNA"
]
}
}'
```
```json Response theme={null}
{
"orderDate": "2024-08-06T13:38:31Z",
"status": "created",
"checkoutUrl": "https://link-s.paybyrd.com/chk_5zBliRhln",
"tags": 0,
"index": 1,
"transactions": [],
"orderId": "351cd5c6-5865-4e7c-ba4e-aff337f7bdd2",
"amount": "50.00",
"currency": "EUR",
"orderRef": "Klarna Product Order",
"shopper": {
"customReference": "spiderman",
"shopperId": "f900c01b-2624-4619-bd49-26fed1f79471",
"email": "customer@email.pt",
"firstName": "Test",
"lastName": "Person-pt",
"phoneCountryCode": 351,
"phoneNumber": "935556731",
"shippingAddress": "Avenida Dom João II 40",
"shippingPostalCode": "1990-094",
"shippingCity": "Lisboa",
"shippingState": "LB",
"shippingCountry": "PRT",
"shippingType": "Undefined",
"billingAddress": "Avenida Dom João II 40",
"billingPostalCode": "1990-094",
"billingCity": "Lisboa",
"billingCountry": "PRT"
},
"orderOptions": {
"redirectUrl": "https://paybyrd.com",
"culture": "pt-PT",
"sendBy": []
},
"paymentOptions": {
"useSimulated": true,
"cardOptions": {
"isPreAuth": false,
"isDccEnabled": false
},
"tokenOptions": {
"tokenizationMethod": "none"
},
"allowedPaymentMethods": [
"KLARNA"
]
},
"terminalOptions": {
"notifyChanges": false
},
"shoppingCart": {
"items": [
{
"amount": 5000,
"categories": [
"weapons",
"launchers"
],
"description": "Web launcher",
"shipping": {
"shippingMethod": "STD"
},
"type": "Product",
"quantity": 1,
"unitPrice": 5000
}
]
},
"marketId": "PT",
"code": "BYRD200",
"description": "Operation successfully completed",
"checkoutKey": "eyJPcmRlcklkIjoiMzUxY2Q1YzYtNTg2NS00ZTdjLWJhNGUtYWZmMzM3ZjdiZGQyIiwiT3JkZXJSZWYiOiJLbGFybmEgUHJvZHVjdCBPcmRlciIsIlBlcnNvbklkIjo4MDYsIkxpdmUiOmZhbHNlLCJFbnRpdHlJZCI6IjM1MWNkNWM2LTU4NjUtNGU3Yy1iYTRlLWFmZjMzN2Y3YmRkMiIsIkFtb3VudCI6IjUwLjAwIiwiQ3VycmVuY3kiOiJFVVIifQ==",
"splitPayments": []
}
```
### Airline order
```bash Request theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"marketId": "PT",
"isoAmount": 5000,
"orderRef": "Klarna Order",
"currency": "EUR",
"orderOptions": {
"redirectUrl": "https://paybyrd.com",
"culture": "pt-PT"
},
"shopper": {
"email": "customer@email.pt",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "935556731",
"homeAddress": "Avenida Dom João II 40",
"homePostalCode": "1990-094",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"billingAddress": "Avenida Dom João II 40",
"billingPostalCode": "1990-094",
"billingCity": "Lisboa",
"billingCountry": "PRT"
},
"paymentOptions": {
"allowedPaymentMethods": [
"KLARNA"
]
},
"airline": {
"TravelType": "Roundtrip",
"typeOperation": "EMD",
"departureDate": "2024-12-19T19:30:00Z",
"passengerName": "Peter Parker",
"airlinePassengers": [
{
"ticketNumber": "123456",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "935556731",
"email": "peter.parker@spidermail.com",
"membershipId": "6e419621-e2f1-4133-bc63-978c0b3d5562"
}
],
"airlineLegs": [
{
"flightNumber": "TP120",
"cabin": "4",
"serviceClass": "Y",
"departureDate": "2024-12-19T19:30:00Z",
"arrivalDate": "2024-12-20T09:30:00Z",
"operatingAirline": "TP",
"departureAirport": "GIG",
"arrivalAirport": "LIS",
"arrivalCountry": "PRT",
"travellersNumber": 1,
"hoursBeforeDeparture": 5,
"isDepartureDateChanged": false,
"segmentCodeStatus": "ABC123",
"fareBasisCode": "Y12R456",
"ticketDeliveryMethod": "PHONE",
"ticketDeliveryRecipient": "5511953259340",
"segmentPrice": 5000
}
]
}
}'
```
```json Response theme={null}
{
"orderDate": "2024-08-06T13:57:44Z",
"status": "created",
"checkoutUrl": "https://link-s.paybyrd.com/chk_jdghAASb6",
"tags": 0,
"index": 1,
"transactions": [],
"orderId": "121656cf-a6de-4641-a4cd-4523c1c6b5e6",
"amount": "50.00",
"currency": "EUR",
"orderRef": "Klarna Order",
"shopper": {
"shopperId": "408f80b2-26a4-4744-824b-acf9eda9c92f",
"email": "customer@email.pt",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "935556731",
"homeAddress": "Avenida Dom João II 40",
"homePostalCode": "1990-094",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"shippingType": "Undefined",
"billingAddress": "Avenida Dom João II 40",
"billingPostalCode": "1990-094",
"billingCity": "Lisboa",
"billingCountry": "PRT"
},
"orderOptions": {
"redirectUrl": "https://paybyrd.com",
"culture": "pt-PT",
"sendBy": []
},
"paymentOptions": {
"useSimulated": true,
"cardOptions": {
"isPreAuth": false,
"isDccEnabled": false
},
"tokenOptions": {
"tokenizationMethod": "none"
},
"allowedPaymentMethods": [
"KLARNA"
]
},
"terminalOptions": {
"notifyChanges": false
},
"marketId": "PT",
"code": "BYRD200",
"description": "Operation successfully completed",
"checkoutKey": "eyJPcmRlcklkIjoiMTIxNjU2Y2YtYTZkZS00NjQxLWE0Y2QtNDUyM2MxYzZiNWU2IiwiT3JkZXJSZWYiOiJLbGFybmEgT3JkZXIiLCJQZXJzb25JZCI6ODA2LCJMaXZlIjpmYWxzZSwiRW50aXR5SWQiOiIxMjE2NTZjZi1hNmRlLTQ2NDEtYTRjZC00NTIzYzFjNmI1ZTYiLCJBbW91bnQiOiI1MC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0=",
"airline": {
"exchangeTicketAmount": 0,
"travelType": "Roundtrip",
"typeOperation": "EMD",
"airlineLegs": [
{
"serviceClass": "Y",
"stopOverCode": "O",
"flightNumber": "TP120",
"fareBasisCode": "Y12R456",
"arrivalAirport": "LIS",
"arrivalDate": "2024-12-20T09:30:00Z",
"cabin": "4",
"departureAirport": "GIG",
"departureDate": "2024-12-19T19:30:00Z",
"hoursBeforeDeparture": 5,
"isDepartureDateChanged": false,
"operatingAirline": "TP",
"segmentCodeStatus": "ABC123",
"travellersNumber": 1,
"arrivalCountry": "PRT"
}
],
"airlinePassengers": [
{
"documentType": 0,
"email": "peter.parker@spidermail.com",
"firstName": "Peter",
"lastName": "Parker",
"membershipId": "6e419621-e2f1-4133-bc63-978c0b3d5562",
"ticketNumber": "123456"
}
]
},
"splitPayments": []
}
```
### Marketplace order
```bash Request theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"marketId": "PT",
"isoAmount": 5000,
"orderRef": "Klarna MarketPlace Order",
"currency": "EUR",
"orderOptions": {
"redirectUrl": "https://paybyrd.com",
"culture": "pt-PT"
},
"shopper": {
"email": "customer@email.pt",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "935556731",
"homeAddress": "Avenida Dom João II 40",
"homePostalCode": "1990-094",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"shippingAddress": "Avenida Dom João II 40",
"shippingPostalCode": "1990-094",
"shippingCity": "Lisboa",
"shippingState": "LB",
"shippingCountry": "PRT",
"billingAddress": "Avenida Dom João II 40",
"billingPostalCode": "1990-094",
"billingCity": "Lisboa",
"billingCountry": "PRT",
"FirstPurchaseDate": "2021-07-15T20:56:22Z",
"LastPurchaseDate": "2021-07-15T20:56:22Z",
"PaidPurchasesCount": 10,
"PaidPurchasesAmount": 65000
},
"shoppingCart": {
"items": [
{
"description": "Web launcher",
"quantity": 1,
"unitPrice": 5000,
"amount": 5000,
"categories": [
"weapons",
"launchers"
],
"shipping": {
"shippingMethod": "STD"
},
"type": "Product"
}
]
},
"splitPayments": [
{
"IsoAmount": 4000,
"merchantId": "ABC123",
"merchantName": "Seller Test",
"merchantRating": 4.5,
"productCategory": "Computers",
"merchantAccountInfo": {
"registrationDate": "2021-07-15T20:56:22Z",
"passwordLastModified": "2021-07-15T20:56:22Z",
"emailLastModified": "2021-07-15T20:56:22Z",
"listingLastModified": "2021-07-15T20:56:22Z",
"loginLastModified": "2021-07-15T20:56:22Z",
"addressLastModified": "2021-07-15T20:56:22Z"
},
"tradesCount": 10,
"tradesVolume": 135000,
"isDigitalProduct": false
},
{
"IsoAmount": 1000,
"merchantId": 806
}
],
"paymentOptions": {
"allowedPaymentMethods": [
"KLARNA"
]
}
}'
```
```json Response theme={null}
{
"orderDate": "2024-08-06T13:26:05Z",
"status": "created",
"checkoutUrl": "https://link-s.paybyrd.com/chk_G82dSOgFJ",
"tags": 0,
"index": 1,
"transactions": [],
"orderId": "695b4790-f27c-482e-9e85-b453ddb8309e",
"amount": "50.00",
"currency": "EUR",
"orderRef": "Klarna MarketPlace Order",
"shopper": {
"shopperId": "d253b9fb-9677-4618-819a-92597b02608c",
"email": "customer@email.pt",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "935556731",
"shippingAddress": "Avenida Dom João II 40",
"shippingPostalCode": "1990-094",
"shippingCity": "Lisboa",
"shippingState": "LB",
"shippingCountry": "PRT",
"homeAddress": "Avenida Dom João II 40",
"homePostalCode": "1990-094",
"homeCity": "Lisbon",
"homeCountry": "PRT",
"shippingType": "Undefined",
"billingAddress": "Avenida Dom João II 40",
"billingPostalCode": "1990-094",
"billingCity": "Lisboa",
"billingCountry": "PRT",
"FirstPurchaseDate": "2021-07-15T20:56:22Z",
"LastPurchaseDate": "2021-07-15T20:56:22Z",
"PaidPurchasesCount": 10,
"PaidPurchasesAmount": 65000
},
"orderOptions": {
"redirectUrl": "https://paybyrd.com",
"culture": "pt-PT",
"sendBy": []
},
"paymentOptions": {
"useSimulated": true,
"cardOptions": {
"isPreAuth": false,
"isDccEnabled": false
},
"tokenOptions": {
"tokenizationMethod": "none"
},
"allowedPaymentMethods": [
"KLARNA"
]
},
"terminalOptions": {
"notifyChanges": false
},
"shoppingCart": {
"items": [
{
"amount": 5000,
"categories": [
"weapons",
"launchers"
],
"description": "Web launcher",
"shipping": {
"shippingMethod": "STD"
},
"type": "Product",
"quantity": 1,
"unitPrice": 5000
}
]
},
"marketId": "PT",
"code": "BYRD200",
"description": "Operation successfully completed",
"checkoutKey": "eyJPcmRlcklkIjoiNjk1YjQ3OTAtZjI3Yy00ODJlLTllODUtYjQ1M2RkYjgzMDllIiwiT3JkZXJSZWYiOiJLbGFybmEgTWFya2V0UGxhY2UgT3JkZXIiLCJQZXJzb25JZCI6ODA2LCJMaXZlIjpmYWxzZSwiRW50aXR5SWQiOiI2OTViNDc5MC1mMjdjLTQ4MmUtOWU4NS1iNDUzZGRiODMwOWUiLCJBbW91bnQiOiI1MC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0=",
"splitPayments": [
{
"isoAmount": 4000,
"merchantId": "ABC123",
"isPartner": false,
"merchantName": "Seller Test",
"merchantRating": 4.5,
"productCategory": "Computers",
"merchantAccountInfo": {
"registrationDate": "2021-07-15T20:56:22Z",
"passwordLastModified": "2021-07-15T20:56:22Z",
"emailLastModified": "2021-07-15T20:56:22Z",
"listingLastModified": "2021-07-15T20:56:22Z",
"loginLastModified": "2021-07-15T20:56:22Z",
"addressLastModified": "2021-07-15T20:56:22Z"
},
"tradesCount": 10,
"tradesVolume": 135000,
"isDigitalProduct": false
},
{
"isoAmount": 1000,
"merchantId": "806",
"isPartner": false,
"merchantRating": 0.0,
"tradesCount": 0,
"tradesVolume": 0,
"isDigitalProduct": false
}
]
}
```
### Bus reservation
```bash Request theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"marketId": "PT",
"isoAmount": 6000,
"orderRef": "Klarna Bus Reservation Order",
"currency": "EUR",
"orderOptions": {
"redirectUrl": "https://paybyrd.com",
"culture": "pt-br"
},
"paymentOptions": {
"allowedPaymentMethods": [
"KLARNA",
"card"
],
"maxAttempts": "3"
},
"shopper": {
"email": "customer@email.pt",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "935556731",
"shippingAddress": "Avenida Dom João II 40",
"shippingPostalCode": "1990-094",
"shippingCity": "Lisboa",
"shippingState": "LB",
"shippingCountry": "PRT",
"billingAddress": "Avenida Dom João II 40",
"billingPostalCode": "1990-094",
"billingCity": "Lisboa",
"billingCountry": "PRT"
},
"shoppingCart": {
"items": [
{
"amount": 6000,
"categories": [
"Bus Tickets"
],
"description": "Bilhetes",
"shipping": {
"shippingMethod": "STD"
},
"type": "Product",
"quantity": 1,
"unitPrice": 6000
}
]
},
"busReservations": [
{
"pnr": "ABC123",
"affiliateName": "FlixBus",
"itineraries": [
{
"departureCity": "Los Angeles",
"arrivalCity": "San Francisco",
"carrier": "FlixBus",
"segmentPrice": 4000,
"departureDate": "2025-03-06T14:38:49.371Z",
"ticketDeliveryMethod": "Email",
"ticketDeliveryRecipient": "customer@email.pt"
}
],
"passengers": [
{
"firstName": "John",
"lastName": "Doe"
},
{
"firstName": "Jane",
"lastName": "Doe"
}
]
},
{
"pnr": "ABC123",
"affiliateName": "FlixBus",
"itineraries": [
{
"departureCity": "San Francisco",
"arrivalCity": "Los Angeles",
"carrier": "FlixBus",
"segmentPrice": 2000,
"departureDate": "2025-03-06T14:38:49.371Z",
"ticketDeliveryMethod": "Email",
"ticketDeliveryRecipient": "customer@email.pt"
}
],
"passengers": [
{
"firstName": "John",
"lastName": "Doe"
}
]
}
]
}'
```
```json Response theme={null}
{
"orderDate": "2025-03-06T13:37:04Z",
"status": "created",
"checkoutUrl": "https://link-s.paybyrd.com/chk_Qyb1imi9o",
"tags": 0,
"index": 1,
"transactions": [],
"orderId": "037f5069-aec9-413b-a7d9-1167b131c1c2",
"amount": "60.00",
"currency": "EUR",
"orderRef": "Klarna Bus Reservation",
"shopper": {
"customReference": "shp_GeQJEuk1cqv15B11",
"shopperId": "31d2b911-5c6a-43d2-a302-e87286b7a611",
"email": "customer@email.pt",
"firstName": "Peter",
"lastName": "Parker",
"phoneCountryCode": 351,
"phoneNumber": "935556731",
"shippingAddress": "Avenida Dom João II 40",
"shippingPostalCode": "1990-094",
"shippingCity": "Lisboa",
"shippingState": "LB",
"shippingCountry": "PRT",
"shippingType": "Undefined",
"firstPurchaseDate": "2025-03-06T13:37:04.2065037+00:00",
"lastPurchaseDate": "2025-03-06T13:37:04.2065037+00:00",
"billingAddress": "Avenida Dom João II 40",
"billingPostalCode": "1990-094",
"billingCity": "Lisboa",
"billingCountry": "PRT"
},
"orderOptions": {
"redirectUrl": "https://paybyrd.com",
"culture": "pt-br",
"sendBy": []
},
"paymentOptions": {
"useSimulated": true,
"cardOptions": {
"isPreAuth": false,
"isDccEnabled": true
},
"tokenOptions": {
"tokenizationMethod": "none"
},
"allowedPaymentMethods": [
"card"
],
"maxAttempts": 3
},
"terminalOptions": {
"notifyChanges": false
},
"shoppingCart": {
"items": [
{
"amount": 6000,
"categories": [
"Bus Tickets"
],
"description": "Bilhetes",
"shipping": {
"shippingMethod": "STD"
},
"type": "Product",
"quantity": 1,
"unitPrice": 6000
}
]
},
"busReservations": [
{
"pnr": "ABC123",
"affiliateName": "FlixBus",
"itineraries": [
{
"departureCity": "Los Angeles",
"arrivalCity": "San Francisco",
"carrier": "FlixBus",
"segmentPrice": 4000,
"departureDate": "2025-03-06T14:37:02.955Z",
"ticketDeliveryMethod": "EMAIL",
"ticketDeliveryRecipient": "customer@email.pt"
}
],
"passengers": [
{
"firstName": "John",
"lastName": "Doe"
},
{
"firstName": "Jane",
"lastName": "Doe"
}
]
},
{
"pnr": "ABC123",
"affiliateName": "FlixBus",
"itineraries": [
{
"departureCity": "San Francisco",
"arrivalCity": "Los Angeles",
"carrier": "FlixBus",
"segmentPrice": 2000,
"departureDate": "2025-03-06T14:37:02.955Z",
"ticketDeliveryMethod": "EMAIL",
"ticketDeliveryRecipient": "customer@email.pt"
}
],
"passengers": [
{
"firstName": "John",
"lastName": "Doe"
}
]
}
],
"marketId": "PT",
"code": "BYRD200",
"description": "Operation successfully completed",
"checkoutKey": "eyJPcmRlcklkIjoiMDM3ZjUwNjktYWVjOS00MzNiLWE3ZDktOTY2N2I0MzFjNGMyIiwiT3JkZXJSZWYiOiJLbGFybmEgQnVzIFJlc2VydmF0aW9uIiwiUGVyc29u111iOjEwLCJMaXZlIjpmYWxzZSwiRW50aXR5SWQiOiIwMzdmNTA2OS1hZWM5LTQzM2ItYTdkOS05NjY3YjQzMWM0YzIiLCJBbW91bnQiOiI2MC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0=",
"splitPayments": []
}
```
### Working with shipping
There are two ways to send the shipping fee:
1. Add a shopping cart item with type `ShippingFee` when creating the order.
2. In the shopping cart item, set the `amount` inside the `shipping` property. This amount is used only if there is no `ShippingFee` item in the cart.
```json ShippingFee item theme={null}
"shoppingCart": {
"items": [
{
"description": "Web launcher",
"quantity": 1,
"unitPrice": 5000,
"amount": 5000,
"categories": [
"weapons",
"launchers"
],
"shipping": {
"shippingMethod": "STD"
},
"type": "Product"
},
{
"description": "Shipping",
"quantity": 1,
"unitPrice": 199,
"amount": 199,
"shipping": {
"shippingMethod": "STD"
},
"type": "ShippingFee"
}
]
}
```
```json Shipping amount theme={null}
"shoppingCart": {
"items": [
{
"description": "Web launcher",
"quantity": 1,
"unitPrice": 5000,
"amount": 5000,
"categories": [
"weapons",
"launchers"
],
"shipping": {
"shippingMethod": "STD",
"amount": 199
},
"type": "Product"
}
]
}
```
***
## Create payment from order
You can create a Klarna payment by passing the `checkoutKey` from the order response:
```bash Request theme={null}
curl --request POST \
--url 'https://gateway.paybyrd.com/api/v2/payment?checkoutKey=eyJPcmRlcklkIjoiNGQ0MzhkNDQtNTYwOS00YWRjLWFjNWQtYTk0OGM3ZTM5NDU1IiwiT3JkZXJSZWYiOiJOZXcgT3JkZXIiLCJQZXJzb25JZCI6MzMwOCwiTGl2ZSI6ZmFsc2UsIkVudGl0eUlkIjoiNGQ0MzhkNDQtNTYwOS00YWRjLWFjNWQtYTk0OGM3ZTM5NDU1IiwiQW1vdW50IjoiMjUwMC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0%3D' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"type": "BNPL",
"amount": "50.00",
"currency": "EUR",
"culture": "pt-PT",
"brand": "KLARNA",
"salesChannel": "Desktop",
"shopper": {
"phoneCountryCode": "+351",
"phoneNumber": "935556731",
"email": "customer@email.pt",
"firstName": "Test",
"lastName": "Person-pt",
"billingAddress": "Avenida Dom João II 40",
"billingCountry": "PRT",
"billingPostalCode": "1990-094",
"billingCity": "Lisboa"
}
}'
```
```json Response theme={null}
{
"culture": "pt-PT",
"salesChannel": "Desktop",
"type": "Bnpl",
"currency": "EUR",
"orderRef": "Klarna Product Order",
"brand": "KLARNA",
"paymentMethod": "klarna",
"redirectUrl": "https://paybyrd.com",
"action": {
"type": "redirect",
"url": "https://webapp-redirect-api-stg.azurewebsites.net/api/v1/Redirect/4333c3d2-0d34-4597-bf24-a6b987ad8666"
},
"shopper": {
"customReference": "spiderman",
"email": "customer@email.pt",
"firstName": "Test",
"lastName": "Person-pt",
"phoneCountryCode": 351,
"phoneNumber": "935556731",
"ipAddress": "131.0.31.137",
"shippingAddress": "Avenida Dom João II 40",
"shippingPostalCode": "1990-094",
"shippingCity": "Lisboa",
"shippingCountry": "PRT",
"billingAddress": "Avenida Dom João II 40",
"billingPostalCode": "1990-094",
"billingCity": "Lisboa",
"billingCountry": "PRT"
},
"code": "BYRD207",
"description": "Pending redirect",
"status": "Processing",
"requestId": "59abd567-2988-4b9b-92de-15719d432768",
"ipAddress": "131.0.31.137",
"marketId": "PT",
"acceptTokenization": false,
"transactionMode": "None",
"transactionId": "4333c3d2-0d34-4597-bf24-a6b987ad8666",
"amount": "50.00",
"isoAmount": 5000
}
```
To check whether the transaction was accepted, look at the **code** field. A successful response returns **BYRD207**. See the [Create Payment](/api-reference/payments/create-payment) API reference for the full list of request parameters, and the [API code reference](/api-reference/api-code-reference) for all possible codes.
# Card
Source: https://docs.paybyrd.com/accept-payments/card/card-payments
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, take a look at the [Paybyrd Checkout](/embed/checkout) and [Card Collect](/embed/card-collect) solutions.
## 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:
```bash Card Payment and Redirect URL Request theme={null}
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"
}
}'
```
```json Card Payment and Redirect URL Response theme={null}
{
"transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
"type": "Card",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "VISA",
"fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
"amount": "8.15",
"isPreAuth": false,
"redirectUrl": "https://your-shop-url?orderRef=ABC12345",
"action": {
"type": "redirect",
"url": "https://link-s.paybyrd.com/3ds_Q44clBT77"
},
"card": {
"number": "420000******0000",
"expiration": "12/25",
"cvv": "***",
"holder": "Peter Parker"
},
"code": "BYRD207",
"description": "Pending redirect"
}
```
### 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`.
```json theme={null}
{
"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:
```bash Card Payment and 3DSecure Callback URL Request theme={null}
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"
}
}'
```
```json Card Payment and 3DSecure Callback URL Response theme={null}
{
"transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
"type": "Card",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "VISA",
"fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
"amount": "8.15",
"isPreAuth": false,
"action": {
"type": "redirect",
"url": "https://link-s.paybyrd.com/3ds_Q44clBT77"
},
"card": {
"number": "420000******0000",
"expiration": "12/25",
"cvv": "***",
"holder": "Peter Parker"
},
"threeDSecure": {
"callbackUrl": "https://your-threedsresult-handle-url.com"
},
"code": "BYRD207",
"description": "Pending redirect"
}
```
See the [full API reference](/api-reference/payments/create-payment) 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](/api-reference/api-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:
```json Authorized theme={null}
{
"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"
}
```
```json Unauthorized theme={null}
{
"transactionId": "5051e95a-977e-4925-a9af-3f05ce39c890",
"status": "Unauthorized",
"authenticationData": {
"threeDsVersion": "V2",
"dsTransactionId": "2b771583-f9a4-4562-a71d-badab879d7d7",
"eci": "07",
"verificationMethod": "ThreeDSecure"
},
"message": "Authorization failed",
"details": "Security failure",
"transStatus": "N",
"transStatusReason": "09"
}
```
```json NotEnrolled theme={null}
{
"transactionId": "0160b04d-61b4-47ce-bbf9-067bc939f0e5",
"status": "NotEnrolled",
"authenticationData": {
"threeDsVersion": "V1",
"eci": "06",
"verificationMethod": "None"
},
"code": "999",
"message": "Simulated not enrolled error",
"details": "Simulated not enrolled error"
}
```
| Field | Description |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TransactionId | Transaction id generated by Paybyrd |
| Status | `Authorized` — Authentication succeeded. `Unauthorized` — Authentication was declined. `NotEnrolled` — Card is not enrolled for 3D Secure. |
| AuthenticationData.ThreeDsVersion | V2 / V1 |
| AuthenticationData.Aav | Authentication value received by the 3DS provider |
| AuthenticationData.DsTransactionId | Transaction id in the directory server |
| AuthenticationData.ECI | Response code returned by the schemes |
| AuthenticationData.VerificationMethod | ThreeDSecure - 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 |
| Code | Error code |
| Message | Error message |
| Details | Error message details |
| TransStatus | Transaction status returned by ACS |
| TransStatusReason | Transaction 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:
```bash Request theme={null}
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"
}
}'
```
```json Response theme={null}
{
"code": "BYRD200",
"description": "Operation successfully completed",
"status": "Success"
}
```
## 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`.
```bash theme={null}
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:
```bash Card 3DS V2 request theme={null}
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"
}
}'
```
```json Card 3DS V2 Success response theme={null}
{
"type": "Card",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "MASTER",
"fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
"code": "BYRD200",
"description": "Operation successfully completed",
"transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
"amount": "8.15",
"isPreAuth": false,
"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`.
# Apple Pay
Source: https://docs.paybyrd.com/accept-payments/digital-wallets/apple-pay
Apple Pay is a digital wallet payment method that enables your customers to pay via their Apple Wallet, without the need to type any card details. When your customers select this payment method, the Paybyrd payment gateway calls the Apple Pay SDK to display a native Apple payment modal.
***
## How it works
### Browser & device compatibility
The Apple Pay SDK identifies compatibility with the `userAgent` property, checking the customer’s device and browser type.
* Apple Pay is **supported** by Apple devices running iOS, as well as desktop systems running Safari or other third-party browsers.
* Apple Pay is **not supported** on Android devices or Samsung devices by default.
***
### Payment flow
![Flowchart depicting Apple Pay payment flow]()
1. When the customer’s device or browser is supported, Paybyrd Checkout launches the native Apple Pay flow, enabling the customer to select a preferred card and pay with their configured Wallets.
2. When the customer’s device or browser not supported, the Paybyrd payment gateway calls the Apple Pay SDK to display a payment modal with a QR code. This enables customers to scan the code with an iPhone or iPad and pay with their configured Wallets.
**Outcomes**
| Result | Behaviour |
| ---------------- | ---------------------------------------------------------------------------- |
| Success | Confirmation screen shown, customer redirected to `redirectUrl`. |
| Error / Declined | "Try again" screen shown. Customer can retry or pick another payment method. |
***
## How to integrate
You can integrate Apple Pay as a payment method in several ways. The first step is to manage domain validation, which is a hard requirement from Apple. This section guides you through the process.
### Requirements
| **Requirement** | **Details** |
| ----------------- | --------------------------------------------------------------------------------------- |
| Registered domain | The exact domain must be validated with Apple via Paybyrd. See Domain Validation below. |
| HTTPS | Your domain must be served over HTTPS. |
| Web only | Apple Pay through Paybyrd is available via the Paybyrd Checkout on the web. |
***
### Domain validation
**This step is mandatory.** Apple Pay only functions in production on a domain that is validated by Apple.
1. **Notify Paybyrd support** — provide the exact domain where Paybyrd Checkout will run.
2. **Paybyrd generates the validation file** — the domain association file tied to your domain will be sent to you.
3. **Upload the file to your server** at this exact path:
```
/.well-known/apple-developer-merchantid-domain-association
```
4. **Confirm to Paybyrd** once the file is live and accessible.
5. **Paybyrd completes verification** with Apple and notifies you when Apple Pay is ready.
### Integration
### Paybyrd Checkout
When adding Apple Pay as an available payment method in an ecommerce setting, you need to **create an order**, then **initiate a Checkout instance** with the correct parameters.
1. **Create an Order**
Include `"APPLE"` in `allowedPaymentMethods` under the `paymentOptions` object when creating your order via the Paybyrd API:
```bash theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '{
"amount":"15.00",
"currency":"EUR",
"orderRef":"ABC123456",
"expiresIn":24,
"shopper":{
"firstName":"John",
"lastName":"Doe",
"email":"john@doe.com",
"phoneNumber":"+319999999921"
},
"orderOptions":{
"redirectUrl":"https://your-site-url/payment-finished",
"checkoutVersion": 2
},
"paymentOptions":{
"allowedPaymentMethods": ["APPLEPAY"],
"tokenOptions":{
"customReference":"+319999999921"
}
}
}'
```
```json theme={null}
{
"orderId":"13a8a157-81c9-46ea-84b4-2bef6daad3fa",
"orderDate":"2026-02-24T17:45:27Z",
"expiresAt":"2026-02-25T17:45:27Z",
"checkoutUrl":"https://chk.paybyrd.com/chk_a321as123a",
"checkoutKey":"eyJPcmRlcklkIjoiMzFhMDYzMmItODcxMy00NjIwLThiZjItMDdiN2UyZTk5MTRjIiwiT3JkZXJSZWYiOiI0MTAxMjA3MTU0IiwiUGVyc29uSWQiOjEwLCJMaXZlIjpmYWxzZSwiRW50aXR5SWQiOiIzMWEwNjMyYi04NzEzLTQ2MjAtOGJmMi0wN2I3ZTJlOTkeNGMiLCJBbW91bnQiOiI1MC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0=",
"status":"created",
"isoAmount":15,
"currency":"EUR",
"orderRef":"ABC123456",
"shopper":{
"shopperId":"176b5023-1624-1d19-cdd2-c61b1be803b7",
"firstName":"John",
"lastName":"Doe",
"email":"john@doe.com",
"phoneNumber":"+319999999921"
},
"orderOptions":{
"redirectUrl":"https://your-site-url/payment-finished",
"culture":"en-US",
"expiresIn":"24",
"checkoutVersion": 2
},
"paymentOptions":{
"allowedPaymentMethods": ["APPLEPAY"],
"tokenOptions":{
"customReference":"+319999999921"
}
},
"code":"BYRD200",
"description":"Operation successfully completed"
}
```
You can combine Apple Pay with other methods, for example `["APPLEPAY", "CARD", "MBWAY"]`. Each is shown or hidden based on device support and the parameter values you use.
2. **Initiate a Checkout instance**
You can initiate a Checkout instance in an iframe, or via a direct URL. In both cases, you can use the `defaultPaymentMethod` parameter to set Apple Pay as the default payment method. Simply add `APPLEPAY` as a value:
```json theme={null}
{
"redirectUrl":"https://your-site-url/payment-finished",
"locale":"en_US",
"defaultPaymentMethod": "APPLEPAY"
}
```
Learn more about integrating Paybyrd Checkout and the available configuration options in the [Paybyrd Checkout](/embed/checkout) documentation.
***
### Pay by Link
You can create a payment and provide it directly via a URL to your customers. Optionally, use the [Payments API](/api-reference/payments/create-payment) and configure the allowed payment methods programmatically.
```bash theme={null}
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":"DIGITALWALLET",
"wallet":"APPLEPAY",
"encryptedData":{
"data":"qwsW672WX21Knduzd4cI5QzOCI3sbMidHuMxb4GnPwZpPKdh7OCf3c0dr6irOqDQvWG2iMYyCc4HAgH22n0kYj8BX1zIVqNvADMc7yIjM5lSuGPp3M45JU+H75Mw+sXnTL86yn69G4+c0JwIBmMw4cALzGWzg3h3HLX0/IYMQP9Sk9mvVYVlagCT3pDwQ2xFpjaF79AwP7UZxCkSrPsKmWIxlax2buG4PE5HgEDe5AWU04AFVvLNk4hJM8R6shMpOLbusAUL9OKn5Oimo5lzYN4lvNziEzfR8ImAWsV22TrOehqK0OQsAVbwblwDm3XyOcJQ2WDty11gdgdXLI9iOscS4Ik8U/P+wKCylOQFZs0hKX+QbFYhXgECY1eqzjGH5Ltdln4hJopU0w==",
"header":{
"publicKeyHash":"lWo3lMXY12OQNpy0XprCW5sDIor3EhWCKt9E748+7bc=",
"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJv9ngO1jNvlicQY9vL/9QlRCgWfHbfnx6Te1JZeYpn9ufe5Qlbte3ZP6SKHFTvM16p/3tfrNprE8n29NuHCwgw==",
"transactionId":"1155d7ff481074b066bf85f37c534e3d28be89ca7161068d9c969cc17ccdefe8"
},
"version":"EC_v1"
}
}'
```
You can find more details about this method in the [Pay by Link](/embed/pay-by-link) documentation.
***
### Going live
1. Request Apple Pay activation from Paybyrd Support
2. Provide your domain to Paybyrd Support
3. Receive the domain validation file from Paybyrd
4. Upload the file to `/.well-known/apple-developer-merchantid-domain-association`
5. Confirm the file is live to Paybyrd Support
6. Paybyrd completes Apple domain verification
7. Create an order and initiate a Checkout instance, or create a Pay by Link payment with the correct configuration parameters.
# MB WAY
Source: https://docs.paybyrd.com/accept-payments/digital-wallets/mb-way
MB WAY is a digital payment method created by SIBS.
## How it works
![Flowchart depicting MB WAY payment flow]()
MB WAY is an asynchronous payment method. When you create a payment, SIBS confirms that the payment was created and the transaction enters a processing status while waiting for the customer to pay. Once the customer completes the payment, SIBS sends a notification and the transaction status is updated to succeeded or failed.
## Make a payment
This example shows the request that creates an MB WAY payment, and the response it returns:
```bash theme={null}
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": "OnlineTransfer",
"isoAmount": 1000,
"currency": "EUR",
"orderRef": "ABC123456",
"brand": "MBWAY",
"phoneCountryCode": "351",
"phoneNumber": "969770085",
"shopper": {
"firstName": "John",
"lastName": "Snow",
"email": "john@snow.com",
"shippingAddress": "Rua da Igreja Velha",
"shippingPostalCode": "4715-591",
"shippingCity": "Braga",
"shippingCountry": "PRT",
"billingAddress": "Rua da Igreja Velha",
"billingPostalCode": "4715-591",
"billingCity": "Braga",
"billingCountry": "PRT"
}
}'
```
```json theme={null}
{
"phoneCountryCode": "351",
"phoneNumber": "969770085",
"mbWay": {
"phoneCountryCode": 31,
"phoneNumber": "625413019",
"entityCode": "53939"
},
"type": "OnlineTransfer",
"currency": "EUR",
"orderRef": "ABC123456",
"brand": "MBWAY",
"paymentMethod": "mbway",
"shopper": {
"email": "john@snow.com",
"firstName": "John",
"lastName": "Snow",
"shippingAddress": "Rua da Igreja Velha",
"shippingPostalCode": "4715-591",
"shippingCity": "Braga",
"shippingCountry": "PRT",
"billingAddress": "Rua da Igreja Velha",
"billingPostalCode": "4715-591",
"billingCity": "Braga",
"billingCountry": "PRT"
},
"code": "BYRD201",
"description": "Payment being processed. Waiting for shopper",
"status": "Processing",
"requestId": "a325f758-edc1-4a4e-ba84-b630b0528217",
"expiresAt": "2024-08-01T08:40:21.397267Z",
"externalTransactionIdentifier": "s2NaTwRc28ujX3p8hpph",
"acceptTokenization": false,
"tokenType": "None",
"transactionId": "81ebf619-e9e1-49ca-aa9d-5c8cf06a41c6",
"amount": "10.00",
"isoAmount": 1000
}
```
See the [full API reference](/api-reference/transactions/query) for all available fields.
## Required Fields
| Field | Description |
| ---------------- | --------------------------------------------------- |
| Type | "OnlineTransfer" |
| IsoAmount | Total purchase amount in "ISO" format. |
| Currency | Three letter "ISO" currency code. |
| OrderRef | Merchant's order reference |
| Brand | "MBWAY" |
| phoneCountryCode | MBWay phone country code without symbols e.g. "351" |
| phoneNumber | MBWay phone number e.g. "969770085" |
To determine whether the transaction was accepted, check the `code` field. For successful scenarios, the expected code is `BYRD201`. See the full list of possible codes.
## Notification
When the payment is finished by the user, Paybyrd will send a notification to the webhook URL defined in the Merchant's account configuration.
Your server will receive a request from Paybyrd with the `transactionId` of the updated transaction. Your server must return an HTTP success status: `200 OK`, `201 CREATED`, or `202 ACCEPTED`. Any other response is treated as a failed delivery.
The following is a sample webhook payload:
```json theme={null}
{
"webhookId": "1642449226",
"contextType": "event:paymentStatusChanged",
"transactionId": "81ebf619-e9e1-49ca-aa9d-5c8cf06a41c6"
}
```
After receiving the webhook, query the transaction to get its full status details.
## Query payment result
The example below shows how to query a transaction and the response it returns:
```bash theme={null}
curl --request GET \
--url https://gateway.paybyrd.com/api/v2/transactions/{transactionId} \
--header 'Accept: application/json' \
--header 'x-api-key: {your_api_key}'
```
# NuPay
Source: https://docs.paybyrd.com/accept-payments/digital-wallets/nupay
NuPay is only available for the Brazilian market.
NuPay is a payment method powered by Nubank, available exclusively for Brazilian customers.
## How it works
![Flowchart depicting NuPay payment flow]()
NuPay is an asynchronous payment method. The customer enters their CPF (Brazilian tax ID) to proceed. Paybyrd validates the CPF, verifies the customer has a NuPay account, and determines which payment conditions are available based on the order amount. The available payment conditions are displayed to the customer before they confirm.
Once the customer confirms, they complete the payment in the Nubank app on their phone. Paybyrd polls the order status and updates the transaction to succeeded or failed accordingly.
## Payment flow
1. The customer creates an order and selects NuPay as the payment method.
2. The customer enters their CPF and submits.
3. Paybyrd queries the NuPay API to validate the CPF and retrieve the available payment conditions for that customer and order amount.
4. NuPay returns the payment options available for the order:
* **Debit only** — for lower order amounts.
* **Debit, credit, and installments** — for higher amounts; up to 10 installments are available.
5. If the CPF is invalid or the customer does not have a Nubank account, NuPay is unavailable and an error screen is displayed.
6. If the CPF is valid, a confirmation screen shows the available payment conditions. The customer reviews and clicks **Pay**.
7. How the payment is completed depends on the device:
* **Mobile** — the Nubank app opens automatically for the customer to complete the payment.
* **Desktop** — a polling screen is displayed. The customer opens the Nubank app manually to complete the payment. There is no QR code available.
8. Paybyrd polls the order status to confirm whether the payment was completed or cancelled.
NuPay transactions expire 30 minutes after creation.
## Make a payment
This example shows the request that creates a NuPay payment, and the response it returns:
```bash Request theme={null}
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": "OnlineTransfer",
"isoAmount": 10000,
"currency": "BRL",
"marketId": "BR",
"orderRef": "ORDER-123456",
"brand": "NUPAY",
"shopper": {
"firstName": "Maria",
"lastName": "Silva",
"email": "maria@silva.com"
}
}'
```
```json Response theme={null}
{
"type": "OnlineTransfer",
"currency": "BRL",
"orderRef": "ORDER-123456",
"brand": "NUPAY",
"paymentMethod": "nupay",
"shopper": {
"email": "maria@silva.com",
"firstName": "Maria",
"lastName": "Silva"
},
"code": "BYRD201",
"description": "Payment being processed. Waiting for shopper",
"status": "Processing",
"requestId": "b8a1c4d9-3f52-4e7a-9b0e-7d6e2f8a3c91",
"expiresAt": "2024-08-01T08:40:21.397267Z",
"transactionId": "c4d2a7f8-9e31-4b5a-8c2d-1e9f3b6a0d74",
"amount": "100.00",
"isoAmount": 10000
}
```
# PayPal
Source: https://docs.paybyrd.com/accept-payments/digital-wallets/paypal
PayPal is one of the largest payment methods in the world. Consumers can pay using their PayPal wallet balance, credit or debit cards, or Pay Later products.
The payment must be completed in 73 hours. The validity of the refund is 180 days.
## How it works
![Flowchart depicting PayPal payment flow]()
PayPal is an asynchronous payment method. When you create a payment, the customer authenticates and approves it through the PayPal interface:
* **Desktop:** a modal opens within the page.
* **Mobile:** a new browser tab opens and closes automatically on completion.
The transaction remains in a processing status until the customer acts. Once the customer completes the payment, PayPal sends a notification and the transaction is updated to either succeeded or failed.
## Create payment
The following example shows how to create a PayPal payment and the response it returns:
```bash theme={null}
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": "OnlineTransfer",
"amount": "8.15",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "PAYPAL",
"culture": "pt-PT"
}'
```
```json theme={null}
{
"type": "OnlineTransfer",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "PAYPAL",
"redirectUrl": "https://your-shop-url?orderRef=ABC12345",
"code": "BYRD207",
"description": "Pending redirect",
"transactionId": "39824983-4a13-42d4-8e85-e2821e494975",
"amount": "8.15",
"action": {
"type": "redirect",
"url": "https://gateway.paybyrd.com/api/v1/Redirect/39824983-4a13-42d4-8e85-e2821e494975"
}
}
```
See the full API reference [here](/api-reference/payments/create-payment).
Check the `code` field to know whether the transaction was accepted. A successful scenario returns the code `BYRD207`. You can find the list of all status codes in the [Respone code reference](/api-reference/api-code-reference).
# Revolut Pay
Source: https://docs.paybyrd.com/accept-payments/digital-wallets/revolut-pay
Revolut Pay allows you to make online payments directly from your Revolut account without entering card or bank details.
## How it works
![Flowchart depicting Revolut Pay payment flow]()
Revolut Pay is an asynchronous payment method. When you create a payment, the customer authenticates and approves it through the Revolut Pay interface:
* **Desktop:** a modal opens within the page.
* **Mobile:** the customer is redirected to the Revolut Pay page or native app, then redirected back on completion.
The transaction remains in a processing status until the customer acts. Once the customer completes the payment, Revolut sends a notification and the transaction is updated to either succeeded or failed.
## Create order
### Generic order
The following request creates a generic Revolut Pay order:
```bash theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '
{
"isoamount": 2510,
"orderRef": "Revolut Pay",
"currency": "EUR",
"shopper": {
"email": "peter@parker.com",
"firstName": "peter",
"lastName": "parker",
"phoneCountryCode": 55,
"phoneNumber": ""
},
"orderOptions": {
"redirectUrl": "https://www.paybyrd.com",
"allowedPaymentMethods": [
"REVOLUTPAY"
]
}
}'
```
```json theme={null}
{
"orderDate": "2024-12-11T17:40:56Z",
"status": "created",
"checkoutUrl": "https://link-s.paybyrd.com/chk_Wkjf5Bt8f",
"tags": 0,
"index": 1,
"transactions": [],
"orderId": "e83aa1a1-152c-439e-af1e-fc4178520807",
"amount": "25.10",
"currency": "EUR",
"orderRef": "Revolut Pay",
"shopper": {
"customReference": "shp_KX9AvxCODFeaUQl4",
"shopperId": "bc110bf5-d6df-4c65-a044-d1d5526846c2",
"email": "peter@parker.com",
"firstName": "peter",
"lastName": "parker",
"phoneCountryCode": 55,
"phoneNumber": "",
"shippingType": "Undefined",
"firstPurchaseDate": "2024-12-11T17:40:56.9508076+00:00",
"lastPurchaseDate": "2024-12-11T17:40:56.9508076+00:00"
},
"orderOptions": {
"redirectUrl": "https://www.paybyrd.com",
"culture": "en-US",
"sendBy": []
},
"paymentOptions": {
"useSimulated": true,
"cardOptions": {
"isPreAuth": false,
"isDccEnabled": false
},
"tokenOptions": {
"tokenizationMethod": "none"
},
"allowedPaymentMethods": []
},
"terminalOptions": {
"notifyChanges": false
},
"code": "BYRD200",
"description": "Operation successfully completed"
}
```
# Create Payment
Source: https://docs.paybyrd.com/accept-payments/how-it-works
The payments API offers you a set of different payment methods to facilitate the checkout experience. The API handles the underlying complexity, so you can integrate and start accepting payments quickly.
## Starting with the payments API
All the payment requests should be addressed to the endpoint `/api/v2/payment`. All payment methods follow the same request and response structure. The example below shows a simple card payment request:
```bash Card payment request theme={null}
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"
}
}'
```
```json Response theme={null}
{
"transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
"type": "Card",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "VISA",
"fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
"amount": "8.15",
"isPreAuth": false,
"redirectUrl": "https://your-shop-url?orderRef=ABC12345",
"action": {
"type": "redirect",
"url": "https://gateway.paybyrd.com/v1/ThreeDSecure/InitiatePayment?transactionId=0e443bff-9052-4eec-a5f1-9db474f2077a"
},
"card": {
"number": "420000******0000",
"expiration": "12/25",
"cvv": "***",
"holder": "Peter Parker"
},
"code": "BYRD207",
"description": "Pending redirect"
}
```
The following example shows the same request using the iDeal payment method:
```bash iDeal payment request theme={null}
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":"OnlineTransfer",
"amount": "8.15",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "ideal",
"bankIdentifierCode": "INGBNL2A",
"redirectUrl": "https://your-shop-url?orderRef=ABC12345"
}'
```
```json Response theme={null}
{
"transactionId": "6a842a44-790b-47c1-bfd1-0d9ffbe766d3",
"amount": "8.15",
"bankIdentifierCode": "INGBNL2A",
"type": "OnlineTransfer",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "ideal",
"redirectUrl": "https://your-shop-url?orderRef=ABC12345",
"action": {
"type": "redirect",
"url": "https://redirect.paybyrd.com/api/v1/redirect/6a842a44-790b-47c1-bfd1-0d9ffbe766d3"
},
"code": "BYRD207",
"description": "Pending redirect"
}
```
Although these payment methods differ significantly, the request and response structure is consistent across all of them.
## Understanding the API
A successful integration starts with understanding the API's base structure. The table below describes the most important fields common to nearly all payment requests.
| Name | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Type | Indicates the type of the payment you want to create. For card payments, the type to be provided is "card". If you want to create a Multibanco reference for example, "onlineTransfer" must be chosen. |
| Amount | The amount to be charged or reserved from the shopper. The value must be provided as a string with the format "#.##". |
| Currency | The currency which the shopper will be charged. The value must be in a valid ISO-4217 alpha code. E.g "EUR". |
| OrderRef | The merchant reference for the payment. Use it to identify the transaction in the Paybyrd dashboard or for reconciliation on your side. |
| RedirectUrl | The URL where the shopper is redirected after the payment is completed. Many payment methods involve two steps — for example, card payment creation followed by 3D Secure authentication. After the shopper completes the second step, they are redirected to this URL. Paybyrd appends the `transactionId` as a query string, so you can query the final transaction status. |
| shopper | Contains details about the buyer, including their full name, phone number, and billing address. |
`RedirectUrl` can also be configured on your subscription. If set there, you do not need to include it in every request.
# 3DS authentication
Source: https://docs.paybyrd.com/advanced/3ds-authentication/overview
## What is 3D Secure (3DS)?
3D Secure (3DS) is an authentication protocol that adds a verification step to online card transactions. It requires cardholders to confirm their identity before a transaction is completed, reducing unauthorized card use.
## Why 3DS Matters
* **Fraud prevention:** Authenticates the cardholder, reducing unauthorized card use.
* **Chargeback protection:** Liability typically shifts to the card issuer for authenticated transactions.
* **Regulatory compliance:** Required for Strong Customer Authentication (SCA) under PSD2 in the EU and other regions.
## Challenges of Implementing 3DS
While 3DS provides many benefits, implementing it can be complex:
* Integration with card networks and issuers.
* Managing redirects for authentication.
* Handling variations across card brands and regions.
* Maintaining a seamless user experience.
## How Paybyrd handles 3DS
* A single API call enables 3DS in your payment flow. Paybyrd handles authentication and redirection automatically.
* The API response includes a 3DS action URL you can use to redirect the customer for authentication.
* Transaction status updates are delivered via webhooks — no polling required.
* Paybyrd supports SCA compliance for global and regional payment regulations.
## Integration options
Paybyrd offers two ways to integrate 3DS:
* [Simplified setup](/advanced/3ds-authentication/simplified-setup) — Paybyrd handles the full 3DS flow. Recommended for most integrations.
* [SDK setup](/advanced/3ds-authentication/sdk-setup) — Use Paybyrd's SDK for more control over the authentication flow.
# SDK setup
Source: https://docs.paybyrd.com/advanced/3ds-authentication/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:
```bash cURL theme={null}
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"
}
}'
```
```javascript Node.js theme={null}
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);
```
```csharp C# theme={null}
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);
```
```php PHP theme={null}
$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;
```
```python Python theme={null}
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())
```
```json Example response theme={null}
{
"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](/api-reference/payments/create-payment).
### 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
1. Use the `threeDSecure.id` and `requestId` values from the payment response to initiate 3DS authentication in the Paybyrd SDK.
2. 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:
```shell npm theme={null}
npm i @paybyrd/threedsecure-service-js
```
```shell yarn theme={null}
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](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:
```javascript theme={null}
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.
```javascript theme={null}
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.
```json 3DS Authenticated and Payment Approved theme={null}
{
"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
}
```
```json 3DS Not Enrolled and Payment Approved theme={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"
}
```
```json 3DS Unauthorized theme={null}
{
"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"
}
```
```json 3DS Authenticated and Payment Declined theme={null}
{
"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"
}
```
```json 3DS Authenticated and Payment With Error theme={null}
{
"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` | |
# Simplified setup
Source: https://docs.paybyrd.com/advanced/3ds-authentication/simplified-setup
Paybyrd handles 3DS authentication. One payment request starts the flow.
## Requirements
The only requirement is an API key.
You can find your API key in the [Developers section](https://backoffice.paybyrd.com/#/apikeys) 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:
```bash cURL theme={null}
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"
}
}'
```
```javascript Node.js theme={null}
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);
```
```csharp C# theme={null}
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);
```
```php PHP theme={null}
$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;
```
```python Python theme={null}
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.
Response example:
```json theme={null}
{
"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](/api-reference/payments/create-payment).
### 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`. |
Redirect the customer to `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 the `redirectUrl` specified during payment creation.
Redirection happens in both success and failure scenarios. Query the transaction to determine the outcome. See [Query transactions](/manage-payments/payment-lifecycle/query-transactions).
The final transaction result is also sent via webhook. See [Webhooks](/api-reference/webhooks).
### 4. Process overview
```mermaid theme={null}
sequenceDiagram
Customer->>+Merchant: Click on payment button
Merchant->>+Paybyrd: Create the payment
Paybyrd->>-Merchant: Returns 3DS action URL
Merchant->>-Customer: Redirects to 3DS
Customer->>+Paybyrd: Authorize transaction through 3DS
Paybyrd->>-Customer: Redirects customer to merchant URL
Paybyrd-->>+Merchant: Notifies the status of the transaction
Merchant-->>-Paybyrd: Acknowledge the hook
Merchant->>+Paybyrd: Query the transaction status
Paybyrd->>-Merchant: Returns transaction status
Merchant->>+Customer: Shows success or failure message
```
# Tokenization
Source: https://docs.paybyrd.com/advanced/tokenization
Tokenization replaces sensitive card data with a reusable token. Tokens support one-click payments, subscriptions, and recurring charges without storing raw card numbers on your servers.
## How it works
1. The customer enters card details once (via [Card Collect](/embed/card-collect) or [Checkout](/embed/checkout))
2. Paybyrd authenticates the cardholder, verifies the card, and stores it securely
3. Paybyrd returns a `tokenId` or stores the token against a `customReference` you define
4. On future payments, pass the `tokenId` or `customReference` instead of card details
## Server-side tokenization
Create a token by calling the tokens endpoint directly from your backend. Token creation runs in five steps:
1. You send a token creation request with card data
2. Paybyrd triggers 3DS authentication for the cardholder
3. After successful authentication, Paybyrd runs a zero-amount card verification
4. The card data is stored securely and a token is generated
5. Paybyrd redirects the customer to your `redirectUrl`
```bash Create token request theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/tokens \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '{
"card": {
"number": "4111111111111111",
"expiration": "12/30",
"cvv": "123",
"holder": "Jane Doe"
},
"customReference": "CUSTOMER-42",
"alias": "Main card",
"redirectUrl": "https://your-site.com/tokenization-complete"
}'
```
```json Response theme={null}
{
"card": {
"number": "411111******1111",
"expiration": "12/30",
"cvv": "**********************************",
"holder": "Jane Doe"
},
"action": {
"type": "redirect",
"url": "https://link.paybyrd.com/3ds_yvLu4cxe8"
},
"transactionId": "cb503fa2-fb6e-45ba-a97f-0283cce5cc30",
"tokenId": "2349c7fd-3f1b-4188-b98e-3dcead913ef6",
"customReference": "CUSTOMER-42",
"alias": "Main card",
"code": "BYRD207",
"description": "Pending redirect"
}
```
Always tokenize from your backend — never from client-side JavaScript with raw card data.
The initial response returns code `BYRD207` (pending redirect). Provide a `redirectUrl` in your request so the customer can be redirected back after 3DS authentication completes.
The `customReference` field acts as a virtual wallet identifier — multiple tokens can be stored under the same reference and queried together later. The `alias` field is an optional human-readable label for the token.
## Client-side tokenization with Card Collect
Use the [Card Collect](/embed/card-collect) library to collect card details in a PCI-compliant iframe and receive a `tokenId` client-side, which you then send to your backend.
## Checkout tokenization
When using [Checkout](/embed/checkout), tokenization is triggered through the order creation request and handled automatically by Paybyrd.
### Create a token via Checkout
![Checkout tokenization flow]()
Include `tokenOptions.customReference` in your order creation request. During the payment flow, the customer sees a checkbox to consent to saving their card.
```bash Create payment with tokenization highlight={18-22} theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '{
"amount": "100.00",
"orderRef": "ORDER-001",
"currency": "EUR",
"shopper": {
"email": "customer@example.com",
"firstName": "Jane",
"lastName": "Doe"
},
"orderOptions": {
"redirectUrl": "https://your-site.com/order-complete"
},
"paymentOptions": {
"tokenOptions": {
"customReference": "CUSTOMER-42"
}
}
}'
```
```json Response theme={null}
{
"orderId": "5d46449e-d3d8-41ce-af56-5fb74313beb2",
"status": "created",
"checkoutUrl": "https://link.paybyrd.com/chk_d1OSV7s2N",
"amount": "100.00",
"currency": "EUR",
"orderRef": "ORDER-001",
"paymentOptions": {
"tokenOptions": {
"customReference": "CUSTOMER-42"
}
},
"code": "BYRD200",
"description": "Operation successfully completed"
}
```
If the customer consents and the payment is approved, Paybyrd delivers the token details via webhook. If the webhook is not received, query the token by `customReference` using the tokens API.
The Checkout handles card collection, 3DS authentication, and payment completion — no direct calls to the tokens endpoint are needed.
### Use a token via Checkout
![Checkout payment with token flow]()
To use a saved token in a subsequent Checkout payment, create an order with the same `customReference` used during token creation. The Checkout page will display the saved card to the customer.
The `customReference` in the order must match the `customReference` used during tokenization. If they differ, the payment will fail.
For security, Paybyrd requires two-factor authentication before charging a saved card. A one-time code is sent to the customer's email and phone number.
## Using a token for payment
Pass the `tokenId` in place of card details:
```json highlight={7} theme={null}
{
"type": "Card",
"isoAmount": 1000,
"currency": "EUR",
"orderRef": "ORDER-001",
"card": {
"tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2"
}
}
```
Alternatively, pay using a `customReference`:
```json highlight={7} theme={null}
{
"type": "Card",
"isoAmount": 1000,
"currency": "EUR",
"orderRef": "ORDER-001",
"card": {
"customReference": "CUSTOMER-42"
}
}
```
## Managing tokens
### Get token by tokenId
```bash Retrieve token using tokenID theme={null}
curl --request GET \
--url https://gateway.paybyrd.com/api/v2/tokens/2349c7fd-3f1b-4188-b98e-3dcead913ef6 \
--header 'x-api-key: {your_api_key}'
```
```json Response theme={null}
{
"tokenId": "2349c7fd-3f1b-4188-b98e-3dcead913ef6",
"customReference": "CUSTOMER-42",
"alias": "Main card"
}
```
### Get tokens by customReference
Returns all tokens stored under the same `customReference`, with paginated results.
```bash Return all tokens for a customer reference theme={null}
curl --request GET \
--url 'https://gateway.paybyrd.com/api/v2/tokens?customReference=CUSTOMER-42' \
--header 'x-api-key: {your_api_key}'
```
```json Response theme={null}
{
"pagination": {
"pageNumber": 0,
"pageSize": 10,
"total": 1,
"totalAvailable": 1,
"returned": 1
},
"success": true,
"data": [
{
"tokenId": "2349c7fd-3f1b-4188-b98e-3dcead913ef6",
"customReference": "CUSTOMER-42",
"alias": "Main card"
}
]
}
```
## Security considerations
* Tokens are bound to your API key and cannot be used by other merchants.
* CVV is never stored and is not required for subsequent tokenized payments (subject to payment method rules).
* 3DS may still be triggered on tokenized payments depending on issuer and transaction risk.
# Tracking requests
Source: https://docs.paybyrd.com/advanced/tracking-requests
## Request identifier
Each API request is associated with a request ID. You can find this value in the response headers, under `RequestId` key. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.
## Idempotency keys
The Paybyrd API supports idempotency for safely retrying HTTP POST requests without accidentally duplicating operations.
An idempotency key is a unique value generated by the client that the server uses to recognize subsequent retries of the same request.
This is useful when no response is received due to a network connection error. Sending an idempotency key will allow you to repeat exactly the same request and obtain the response from the previous one.
To perform an idempotent request, provide an `idempotency-key` header as follows:
```bash theme={null}
curl -H 'idempotency-key: a5ce4eb7-86e9-4569-a722-091d06643201'
```
Paybyrd's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.
Using V4 UUIDs for idempotency keys will guarantee enough entropy and avoid collisions.
Idempotency keys expire after 24 hours after they are created. After expiry, a request with the same key is treated as a new operation.
# Response code reference
Source: https://docs.paybyrd.com/api-reference/api-code-reference
## Return codes
The `code` and `description` fields are included in responses from all payment and transaction endpoints, including [Create Payment](/api-reference/payments/create-payment), [Capture](/api-reference/transactions/capture), [Refund](/api-reference/transactions/refund), [Release](/api-reference/transactions/release), and [Query Transaction](/api-reference/transactions/query). For example:
```json theme={null}
{
"code": "BYRD200",
"description": "Operation successfully completed",
"transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
"amount": "10.00"
}
```
| Code | Description | Transaction status |
| ------- | ---------------------------------------------------------------------------------------------------------- | ------------------ |
| BYRD010 | Request accepted. | N/A |
| BYRD200 | Operation successfully completed. | Success |
| BYRD201 | Payment being processed. Waiting for shopper. | Processing |
| BYRD203 | An error occurred while processing the payment. Please query the transaction to confirm its status. | TemporaryFailed |
| BYRD205 | Operation rejected. This code is related to operation denial from the acquirer. | Denied |
| BYRD206 | Operation blocked by velocity. | Denied |
| BYRD207 | Pending redirect. | Processing |
| BYRD208 | Payment canceled by the shopper. | Canceled |
| BYRD230 | Payment already refunded. | Denied |
| BYRD231 | The refund amount exceeds the remaining balance of the original payment. | Denied |
| BYRD240 | Token is expired. | Error |
| BYRD290 | An error occurred while pre-processing the transaction. Please review your request and try again. | Error |
| BYRD291 | An error occurred while preparing the transaction for acquiring. Please review your request and try again. | Error |
| BYRD292 | No payment methods available for this operation. Please contact Paybyrd support. | Error |
| BYRD294 | Transaction could not be updated. Please review your request and try again. | Error |
| BYRD299 | Operation could not be completed. Please review your request and try again. | Error |
| BYRD401 | Resource access unauthorized. | Error |
| BYRD403 | Resource access is forbidden. | Error |
| BYRD900 | Invalid input. | Error |
| BYRD901 | Resource not found. | Error |
| BYRD999 | Operation failed. This code is related to unhandled errors. | Error |
## Transaction statuses
The `status` field at the transaction level is returned by the [Create Payment](/api-reference/payments/create-payment) endpoint (`POST /api/v2/payment`) and the [Query Transaction](/api-reference/transactions/query) endpoint (`GET /api/v2/transactions/{transactionId}`):
```json theme={null}
{
"code": "BYRD200",
"status": "Success",
"operationType": "Payment",
"brand": "VISA",
"transactionId": "8cb922ee-01cd-453d-90b9-b377e4f1c3cb",
"amount": "5.00"
}
```
| Status | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| Created | The transaction was created, but no payment method was selected. |
| Processing | Waiting for additional steps. |
| TemporaryFailed | An error occurred during the operation and it is not possible to confirm whether the transaction was completed. |
| Denied | The transaction was denied. |
| Success | The transaction was completed successfully. |
| Canceled | The transaction was canceled. |
| Error | An unexpected error occurred. |
## Order statuses
The order `status` field is returned by the [Create Order](/api-reference/orders/create-order) endpoint (`POST /api/v2/orders`) and the Query Order endpoint (`GET /api/v2/orders/{orderId}`):
```json theme={null}
{
"orderId": "e83aa1a1-152c-439e-af1e-fc4178520807",
"status": "created",
"code": "BYRD200",
"description": "Operation successfully completed"
}
```
| Status | Description |
| -------- | ----------------------------------------------------------------------------------------------- |
| created | The order has no payments associated to it, or all payment attempts have failed. |
| pending | The order has a payment in progress that has not yet completed. |
| paid | The order has a successful payment. |
| canceled | The order was canceled — by the shopper, by a system routine, or via the cancel order endpoint. |
| expired | The order reached its expiration date without a completed payment. |
| refunded | The order's payment was refunded. |
## Operation types
The `operationType` field is returned by the [Query Transaction](/api-reference/transactions/query) endpoint (`GET /api/v2/transactions/{transactionId}`):
```json theme={null}
{
"operationType": "Payment",
"status": "Success",
"brand": "VISA",
"transactionId": "8cb922ee-01cd-453d-90b9-b377e4f1c3cb",
"amount": "5.00"
}
```
| Operation type | Description |
| -------------- | ----------------------------------- |
| Payment | Regular payment. |
| PreAuth | Pre-authorization. |
| Capture | Capture of a pre-authorized amount. |
| Refund | Refund of a captured payment. |
| Chargeback | Chargeback. |
## Brands
The `brand` field is returned by the [Create Payment](/api-reference/payments/create-payment) endpoint (`POST /api/v2/payment`) and the [Query Transaction](/api-reference/transactions/query) endpoint (`GET /api/v2/transactions/{transactionId}`):
```json theme={null}
{
"brand": "VISA",
"operationType": "Payment",
"status": "Success",
"transactionId": "8cb922ee-01cd-453d-90b9-b377e4f1c3cb",
"amount": "5.00"
}
```
| Brand code |
| ---------------- |
| AMEX |
| DANKORT |
| DINERS |
| DISCOVER |
| ELO |
| FLOA1XD |
| FLOA3X |
| FLOA4X |
| IDEAL |
| JCB |
| MASTER |
| MBWAY |
| MULTICAIXA\_REF |
| PAYPAL |
| SEPA |
| SIBS\_MULTIBANCO |
| VISA |
| VPAY |
# API intro
Source: https://docs.paybyrd.com/api-reference/api-intro
The Paybyrd Gateway API is a REST API. All requests are made over HTTPS, request and response bodies are JSON, and all endpoints are versioned under `/api/v2/`.
## Environments
Two environments are available. Your API key determines which one is active — there is no extra configuration required.
| Environment | Base URL |
| --------------------- | ------------------------------------ |
| **Sandbox** (testing) | `https://gatewaysandbox.paybyrd.com` |
| **Production** | `https://gateway.paybyrd.com` |
Use the sandbox to build and test your integration without processing real transactions. Sandbox API keys and production API keys are separate — you can manage both in the [API keys](https://backoffice.paybyrd.com/#/apikeys) section of the Paybyrd dashboard.
## Authentication
All requests must include your API key in the `x-api-key` request header.
```bash theme={null}
curl --request POST
--url 'https://gateway.paybyrd.com/api/v2/payment'
--header 'x-api-key: {your_api_key}'
--header 'Content-Type: application/json'
--data '{...}'
```
Requests made without a valid API key will receive a `401 Unauthorized` response. Requests made with a key that lacks permission for the operation will receive a `403 Forbidden` response.
Keep your API key secret. Do not expose it in client-side code, public repositories, or logs. If a key is compromised, rotate it immediately from the dashboard.
## Request format
All request bodies must be JSON. Include the following headers on every request that has a body:
| Header | Value |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |
| `Accept` | `application/json` |
| `x-api-key` | Your API key |
## Idempotency
The API supports idempotent requests on `POST` endpoints. Sending the same `idempotency-key` header value on a repeated request returns the original response rather than executing the operation again — useful for safely retrying after a network failure.
```bash theme={null}
curl --request POST
--url 'https://gateway.paybyrd.com/api/v2/payment'
--header 'x-api-key: {your_api_key}'
--header 'Content-Type: application/json'
--header 'idempotency-key: a5ce4eb7-86e9-4569-a722-091d06643201'
--data '{...}'
```
Use a unique value per logical operation (e.g. a UUID). The same key always returns the original result — including error responses.
## Request tracking
Every API response includes a `RequestId` header. Include this value when contacting support so requests can be traced end to end.
## Responses
All responses follow a consistent structure. The `success` field indicates whether the operation succeeded, and Paybyrd-specific result codes are returned in `paybyrdCode` and `paybyrdDescription`.
```json theme={null}
{
"success": true,
"paybyrdCode": "BYRD200",
"paybyrdDescription": "Operation successfully completed",
...
}
```
Standard HTTP status codes apply: `200` for success, `400` for invalid input, `401` for missing or invalid authentication, `403` for insufficient permissions, and `404` for resources not found.
## Pagination
Endpoints that return collections support pagination. Pass `pageNumber` and `pageSize` as query parameters to control which page is returned. Responses include a `pagination` object:
```json theme={null}
{
"data":"{...}",
"pagination":{
"pageNumber":1,
"pageSize":10,
"total":100,
"totalAvailable":100
}
}
```
| Field | Description |
| ---------------- | ------------------------------------------------ |
| `pageNumber` | Current page (1-based) |
| `pageSize` | Number of items on this page |
| `total` | Total number of items in the collection |
| `totalAvailable` | Total number of items accessible to your account |
# Cancel Order
Source: https://docs.paybyrd.com/api-reference/orders/cancel-order
/openapi.yml delete /api/v2/orders/{orderId}
Cancel an order by id
# Create Order
Source: https://docs.paybyrd.com/api-reference/orders/create-order
/openapi.yml post /api/v2/orders
This endpoint allows you to create a new order. Orders are used in Paybyrd Checkout or the Pay By Link feature.
# Query Order
Source: https://docs.paybyrd.com/api-reference/orders/query-order
/openapi.yml get /api/v2/orders/{orderId}
Query order data by order id
# resend
Source: https://docs.paybyrd.com/api-reference/paybylink/resend
/openapi.yml post /api/v2/paybylink/{orderId}/resend
# Create Payment
Source: https://docs.paybyrd.com/api-reference/payments/create-payment
/openapi.yml post /api/v2/payment
# Finish two-step card payment
Source: https://docs.paybyrd.com/api-reference/payments/finish-two-step-card-payment
/openapi.yml post /api/v2/payment/{transactionId}/pay
# List settlement files
Source: https://docs.paybyrd.com/api-reference/settlement-files/list-settlement-files
/settlements-api.yml get /api/v1/SettlementFiles
Returns a list of settlement files generated within the specified time period. Days with no settlement file are omitted from the results. When more than one file exists for the same day, all files are complementary and must all be processed to obtain complete settlement information.
# Create
Source: https://docs.paybyrd.com/api-reference/subscription/create
/openapi.yml post /api/v2/subscriptions
# Create Token
Source: https://docs.paybyrd.com/api-reference/tokenization/create-token
/openapi.yml post /api/v2/tokens
Create a Token for future transactions
# Get Token By Id
Source: https://docs.paybyrd.com/api-reference/tokenization/get-token-by-id
/openapi.yml get /api/v2/tokens/{tokenId}
Get a created token By Id
# Get Token by reference
Source: https://docs.paybyrd.com/api-reference/tokenization/get-token-by-reference
/openapi.yml get /api/v2/tokens
Get created tokens by aggregated reference
# Adjust
Source: https://docs.paybyrd.com/api-reference/transactions/adjust
/openapi.yml post /api/v2/adjust/{transactionId}
Changes the reserved amount before the capture occurs.
# Cancel
Source: https://docs.paybyrd.com/api-reference/transactions/cancel
/openapi.yml post /api/v2/cancel/{transactionId}
# Capture
Source: https://docs.paybyrd.com/api-reference/transactions/capture
/openapi.yml post /api/v2/capture/{transactionId}
For the charge to be carried out from a pre-authorization, it's necessary to send from your cash register to our API a request to capture the value of the payment-related transaction.
# Query
Source: https://docs.paybyrd.com/api-reference/transactions/query
/openapi.yml get /api/v2/transactions/{transactionId}
# Query by acquirer custom identifier
Source: https://docs.paybyrd.com/api-reference/transactions/query-by-acquirer-custom-identifier
/openapi.yml get /api/v2/transactions?acquirerCustomId=${customIdentifier}
# Receipt
Source: https://docs.paybyrd.com/api-reference/transactions/receipt
/openapi.yml get /api/v2/transactions/{transactionId}/receipt
Retrieve receipt data for POS transactions
# Refund
Source: https://docs.paybyrd.com/api-reference/transactions/refund
/openapi.yml post /api/v2/refund/{transactionId}
When you want to refund values from a transaction, you need to send from your cash register to our API a request to do a refund value from the transaction.
# Release
Source: https://docs.paybyrd.com/api-reference/transactions/release
/openapi.yml post /api/v2/release/{transactionId}
In order to release a reserved amount through a pre-authorization is necessary to send a request from your cash register to our API.
# Webhook API
Source: https://docs.paybyrd.com/api-reference/webhooks
Webhooks deliver real-time notifications about events related to orders, transactions, and chargebacks.
**Base URL:** `https://webhook.paybyrd.com`
## Authentication
Authenticate all requests with your API key in the `x-api-key` request header.
## Settings
Configure webhook subscriptions at `https://webhook.paybyrd.com/api/v1/settings`.
### Events
If no events are specified, Paybyrd subscribes to all available events.
#### Orders
| Event | Description |
| --------------------- | -------------------------------------------------------------- |
| order.created | A new order was created. |
| order.pending | The order is awaiting further action or confirmation. |
| order.paid | The order has been fully paid. |
| order.refunded | The order amount was refunded. |
| order.canceled | The order was canceled. |
| order.expired | The order expired without a completed payment. |
| order.temporaryfailed | A temporary failure occurred during the order payment process. |
#### Transactions
**Pre-authorisation**
| Event | Description |
| ---------------------------- | ------------------------------------------- |
| transaction.preauth.pending | Pre-authorisation is awaiting approval. |
| transaction.preauth.success | Pre-authorisation was approved. |
| transaction.preauth.failed | Pre-authorisation failed. |
| transaction.preauth.error | An error occurred during pre-authorisation. |
| transaction.preauth.canceled | Pre-authorisation was canceled. |
**Capture**
| Event | Description |
| ---------------------------- | --------------------------------- |
| transaction.capture.pending | Capture is awaiting confirmation. |
| transaction.capture.success | Capture completed successfully. |
| transaction.capture.failed | Capture failed. |
| transaction.capture.error | An error occurred during capture. |
| transaction.capture.canceled | Capture was canceled. |
**Payment**
| Event | Description |
| ---------------------------- | --------------------------------- |
| transaction.payment.pending | Payment is awaiting confirmation. |
| transaction.payment.success | Payment completed successfully. |
| transaction.payment.failed | Payment failed. |
| transaction.payment.error | An error occurred during payment. |
| transaction.payment.canceled | Payment was canceled. |
**Refund**
| Event | Description |
| --------------------------- | -------------------------------- |
| transaction.refund.pending | Refund is awaiting confirmation. |
| transaction.refund.success | Refund completed successfully. |
| transaction.refund.failed | Refund failed. |
| transaction.refund.error | An error occurred during refund. |
| transaction.refund.canceled | Refund was canceled. |
#### Chargebacks
| Event | Description |
| ------------------------ | --------------------------------------- |
| chargeback.created | A chargeback was initiated. |
| chargeback.disputing | The chargeback is being disputed. |
| chargeback.pendingaction | The chargeback requires further action. |
| chargeback.closed | The chargeback case was closed. |
| chargeback.won | The chargeback dispute was won. |
| chargeback.lost | The chargeback dispute was lost. |
### Payment methods
If no payment methods are specified, Paybyrd subscribes to all available payment methods.
| Payment method | Description |
| -------------- | ------------------------------------------- |
| card | Credit or debit card transactions. |
| ideal | iDEAL transactions (Netherlands). |
| multibanco | Multibanco transactions (Portugal). |
| mbway | MB WAY transactions (Portugal). |
| multicaixa | Multicaixa transactions (Angola). |
| pickup | In-store or designated pickup transactions. |
| paypal | PayPal transactions. |
| banktransfer | Bank transfers. |
| floa | Floa transactions. |
| pix | Pix instant payment transactions (Brazil). |
### Webhook authentication
When Paybyrd sends requests to your webhook URL, it authenticates them using one of two credential types:
| Type | Value | How it works |
| ------- | --------- | --------------------------------------------------------------------------------------------------------------- |
| API Key | `api-key` | Paybyrd adds an `x-api-key` header to each request. |
| Basic | `basic` | Paybyrd generates a username and password sent in the `Authorization` header using Basic authentication format. |
You select the credential type when creating the webhook configuration.
### Managing configurations
**Create a configuration:**
```bash theme={null}
curl --location 'https://webhook.paybyrd.com/api/v1/settings' \
--header 'x-api-key: {your_api_key}' \
--header 'Content-Type: application/json' \
--data '{
"url": "",
"credentialType": "",
"events": [
"...events you want to subscribe to"
],
"paymentMethods": [
"...payment methods you want to subscribe to"
]
}'
```
**List configurations:**
```bash theme={null}
curl --location 'https://webhook.paybyrd.com/api/v1/settings' \
--header 'x-api-key: {your_api_key}'
```
**Delete a configuration:**
```bash theme={null}
curl --location --request DELETE 'https://webhook.paybyrd.com/api/v1/settings/' \
--header 'x-api-key: {your_api_key}'
```
## Querying webhooks
Query generated webhooks, check their status, review attempt responses, and resend them at `https://webhook.paybyrd.com/api/v1/webhooks`.
### Parameters
* **`referenceId`**: An `orderId`, `transactionId`, or `chargebackId`. Filters results to webhooks associated with that entity.
### Pagination
Use the following request headers to paginate results:
* **`x-page`**: Page number to retrieve.
* **`x-page-size`**: Number of results per page.
Results are ordered from most recent to oldest.
### Examples
**Query by referenceId:**
```bash theme={null}
curl --location 'https://webhook.paybyrd.com/api/v1/webhooks?referenceId=' \
--header 'x-api-key: {your_api_key}'
```
**Query with pagination:**
```bash theme={null}
curl --location 'https://webhook.paybyrd.com/api/v1/webhooks' \
--header 'x-api-key: {your_api_key}' \
--header 'x-page-size: 25' \
--header 'x-page: 1'
```
## Retry behaviour
The webhook engine retries failed deliveries automatically. Any HTTP response outside the `2xx` range is treated as a failure and triggers a retry.
* Up to **50 retry attempts** per webhook.
* Retry intervals follow an arithmetic progression: the first retry is 1 minute after the failed attempt, increasing by 1 minute per retry, up to a maximum delay of 1 hour.
## Querying attempts
Retrieve the attempt history for a specific webhook:
`GET https://webhook.paybyrd.com/api/v1/webhooks/{webhookId}/attempts`
Pagination is supported using the same `x-page` and `x-page-size` headers described above.
## Resending webhooks
Manually resend one or more webhooks:
```bash theme={null}
curl --location 'https://webhook.paybyrd.com/api/v1/webhooks/resend' \
--header 'x-api-key: {your_api_key}' \
--header 'Content-Type: application/json' \
--data '{
"ids": [
"...webhook IDs to resend"
]
}'
```
## Data retention
| Outcome | Retention period |
| ------------------- | -------------------------------------------------------- |
| Failed webhooks | Up to 1 month (all attempts, payloads sent and received) |
| Successful webhooks | 1 week from creation timestamp |
## SDK
A .NET SDK is available on [NuGet](https://www.nuget.org/packages/Paybyrd.Clients.Webhook) and open source on [GitHub](https://github.com/paybyrd/paybyrd-clients-dotnet).
# Creates a new webhook setting
Source: https://docs.paybyrd.com/api-reference/webhooks/creates-a-new-webhook-setting
/openapi.yml post /api/v2/webhooks
This endpoint allows you to configure more than one address for webhooks notifications.
# Disables a webhook setting
Source: https://docs.paybyrd.com/api-reference/webhooks/disables-a-webhook-setting
/openapi.yml post /api/v2/webhooks/{webhookId}/disable
# Enables a webhook setting
Source: https://docs.paybyrd.com/api-reference/webhooks/enables-a-webhook-setting
/openapi.yml post /api/v2/webhooks/{webhookId}/enable
# Gets a webhook settings by its Id
Source: https://docs.paybyrd.com/api-reference/webhooks/gets-a-webhook-settings-by-its-id
/openapi.yml get /api/v2/webhooks/{webhookId}
This endpoint allows you to recover a specific webhook settings by its Id.
# Gets all webhook settings
Source: https://docs.paybyrd.com/api-reference/webhooks/gets-all-webhook-settings
/openapi.yml get /api/v2/webhooks
This endpoint allows you to recover all webhook settings.
# Setup URL
Source: https://docs.paybyrd.com/api-reference/webhooks/setup-url
/openapi.yml put /api/v1/webhook
When your server is ready to handle the notifications, you need to set up your URL into your merchant account. To achieve this you need to call the following endpoint
# Updates a webhook setting url
Source: https://docs.paybyrd.com/api-reference/webhooks/updates-a-webhook-setting-url
/openapi.yml patch /api/v2/webhooks/{webhookId}/url
# Updates a webhook setting url
Source: https://docs.paybyrd.com/api-reference/webhooks/updates-a-webhook-setting-url-1
/openapi.yml patch /api/v2/webhooks/{webhookId}/credentials
# Changelog
Source: https://docs.paybyrd.com/changelog
Product updates and improvements to the Paybyrd API and documentation.
### FinanceHub: Settlements API
Paybyrd's settlement reporting is now served through **FinanceHub**. Use `GET /api/v1/SettlementFiles` via the `https://financehub.paybyrd.com` server URL to retrieve a list of settlement CSV files for a given date range. Filter by `createdFrom` and `createdTo`. Scope results to a specific merchant or store with `merchantId` and `storeId`.
Download URLs in the response are valid for 7 days from the time of the request. Error responses now use the `problemDetails` format.
Two legacy endpoints using the `settlements.paybyrd.com` server URL are now deprecated:
* **Settlement files** — `GET /api/v1/SettlementFiles`. See [Settlement files (legacy)](/manage-payments/settlements/legacy-settlement-files).
* **Refunds before clearing** — `GET /api/v1/authorization-files`. See [Refunds before clearing files (legacy)](/manage-payments/settlements/refunds-before-clearing).
Paybyrd continues to support the legacy endpoints for an indefinite period. However, we recommend using the new endpoints; see the [Settlement files](/manage-payments/settlements/settlement-files) guide and the [Settlements API reference](/api-reference) for details.
### Multicaixa Express: QR code and deeplink response fields
Multicaixa Express payments now return a `multicaixaExpress` object in the payment response, containing QR code and deeplink data to support the full checkout experience across desktop and mobile.
When `brand` is `MULTICAIXAEXPRESS`, the response includes:
| Field | Type | Description |
| ------------------ | ----------------- | ----------------------------------------------------- |
| `deeplink` | string (uri) | Direct deeplink to open the Multicaixa Express app. |
| `deeplinkRedirect` | string (uri) | Redirect URL for browser and mobile flows to the app. |
| `qrCodeUrl` | string (uri) | URL of the QR code image. |
| `expiresAt` | string (ISO 8601) | Payment expiration timestamp. |
```json theme={null}
{
"multicaixaExpress": {
"deeplink": "mcxwallet://purchase?qrref=...",
"deeplinkRedirect": "https://api.sandbox.proxypay.co.ao/deeplink/...",
"qrCodeUrl": "https://api.sandbox.proxypay.co.ao/qrcode/...",
"expiresAt": "2026-05-22T19:14:04Z"
}
}
```
On desktop, Paybyrd Checkout uses `qrCodeUrl` to display a QR code for the buyer to scan. On mobile, tapping **Pay** uses `deeplinkRedirect` to open the Multicaixa Express app directly.
See the [Multicaixa Express](/accept-payments/bank-transfers/multicaixa-express) guide for full details.
### New field: `softDescriptor` for card payments
Card payments now support a `softDescriptor` field, which controls the text that appears on the cardholder's bank statement for that transaction.
* Maximum length: **22 characters**
* Requests exceeding this limit return a `400 Bad Request` error
```bash theme={null}
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 '{
"softDescriptor": "MYSTORE*ORDER123",
...
}'
```
See the [card payments](/accept-payments/card/card-payments) guide and the [Create Payment](/api-reference/payments/create-payment) API reference for full details.
# Card Collect
Source: https://docs.paybyrd.com/embed/card-collect
This guide explains how to integrate the Paybyrd Card Collect widget.
## Overview
Card Collect is a JavaScript plugin that lets you process credit card payments without handling card data directly, so your integration does not require PCI compliance.
The widget provides secure, customizable fields where the cardholder enters their card details. The widget converts those details into a temporary token you can use with any Paybyrd API that requires card data.
## Installation
Install the package:
```bash theme={null}
npm install @paybyrd/card-collect
```
or
```bash theme={null}
yarn add @paybyrd/card-collect
```
Then import the module into your project:
```javascript theme={null}
import CardCollect from "@paybyrd/card-collect";
```
For usage in the browser please visit github, download `dist/cardCollect-web.js` and include it in your HTML file.
## Quick Start
Designate the HTML elements where your fields will render, then initialize the library.
```javascript theme={null}
const form = await CardCollect({ options });
```
or for web
```javascript theme={null}
const form = await cardCollect({ options });
```
You can pass the following options when initializing the library:
| Property | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onStageChanged | This handler will be called whenever the form state changes. The only argument passed is a state object with the current status of the form fields. You can use this handler to enable/disable the submit button to prevent the user from misusing your form. |
Finally, you can create fields and configure the submit handler.
```javascript theme={null}
form.cardCollect_field({
id: '#cc-number',
type: 'card-number',
name: 'card_number',
placeholder: 'Card number',
showCardIcon: true,
validations: ['required', 'validCardNumber'],
});
const submitButton = document.getElementById("submit-button");
submitButton.onclick = handleSubmit;
function handleSubmit() {
form.cardCollect_submit().then(({ status, response }) => {
console.log(response);
}).catch((error) => console.log(error));
}
```
You should have at least one field with the name `card_number` and one with `card_exp`. These are **mandatory**.
The response is a JSON object that will contain the `TokenId`. These tokens are different from tokenization API tokens. Card Collect tokens are short-lived and are discarded after use.
```json theme={null}
{
"tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2",
"correlationId": "5c9b4c3a-9602-4c4e-9a3d-4e4af8a3d872"
}
```
With the `TokenId`, you can call any Paybyrd API that requires card data. Inside the Card node, instead of sending the raw card data, you will send the `TokenId` as shown in the sample below:
```bash theme={null}
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": {
"tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2"
}
}'
```
```json theme={null}
{
"transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
"type": "Card",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "VISA",
"fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
"amount": "8.15",
"isPreAuth": false,
"redirectUrl": "https://your-shop-url?orderRef=ABC12345",
"action": {
"type": "redirect",
"url": "https://link-s.paybyrd.com/3ds_Q44clBT77"
},
"card": {
"number": "420000******0000",
"expiration": "12/25",
"cvv": "***",
"holder": "Peter Parker"
},
"code": "BYRD207",
"description": "Pending redirect"
}
```
## Adding fields
```javascript theme={null}
form.cardCollect_field({
id: '#cc-number',
type: 'card-number',
name: 'card_number',
placeholder: 'Card number',
showCardIcon: true,
validations: ['required', 'validCardNumber'],
});
```
### Mandatory fields
You must include at minimum:
* `card_number` (`type: 'card-number'`)
* `card_exp` (`type: 'card-expiration-date'`)
### Field properties
| Property | Required | Description |
| -------------- | -------- | ---------------------------------------------------------------------------------------- |
| `name` | Yes | Field identifier |
| `type` | Yes | `text`, `card-number`, `card-expiration-date`, `card-security-code` |
| `validations` | No | Array of validation rules |
| `css` | No | Style object with CSS properties |
| `classes` | No | CSS class mapping for states: `dirty`, `empty`, `focused`, `valid`, `invalid`, `touched` |
| `serializers` | No | Data transformation rules applied before submission |
| `showCardIcon` | No | Display the detected card brand icon |
| `yearLength` | No | For expiry fields: `'2'` or `'4'` |
### Supported validations
| Rule | Description |
| ------------------------- | ----------------------------------------------------- |
| `required` | Field must not be empty |
| `validCardNumber` | Luhn algorithm check |
| `validCardExpirationDate` | Validates date format and future date |
| `validCardSecurityCode` | CVV/CVC validation |
| Custom RegExp | Pass a regular expression for custom pattern matching |
## Styling
```javascript theme={null}
form.cardCollect_field({
// ...
css: {
'color': '#1b1d1f',
'border': 'solid 1px #1b1d1f',
'&:focus': { 'border-color': '#11bef5' },
'&.invalid.touched': { 'color': 'red' },
'@font-face': { /* custom font */ }
}
});
```
## Submitting
```javascript theme={null}
form.cardCollect_submit()
.then(({ status, response }) => {
// response.tokenId contains the token
console.log(response.tokenId);
})
.catch((error) => console.error(error));
```
### Response
```json theme={null}
{
"tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2",
"correlationId": "5c9b4c3a-9602-4c4e-9a3d-4e4af8a3d872"
}
```
## Using the token in a payment
Pass `tokenId` in place of raw card fields:
```json theme={null}
{
"type": "Card",
"isoAmount": 815,
"currency": "EUR",
"orderRef": "ORDER-001",
"card": {
"tokenId": "ecf4a873-59fd-4300-a6e6-330d267ebbb2"
}
}
```
## Supported card brands
Visa, Mastercard, Amex, Maestro, Discover, Diners Club, JCB, UnionPay, Elo, and others.
## Advanced: Smart CVC
Link the CVC field to the card number field for brand-specific CVC length validation:
```javascript theme={null}
cardNumber.setCVCDependency(cvc);
```
## Advanced: Data serializers
Use serializers to transform field data before submission:
| Serializer | Description |
| ---------- | ----------------------------------- |
| `replace` | Find-and-replace on the field value |
| `separate` | Split value at a delimiter |
| `toBase64` | Base64-encode the field value |
# Checkout
Source: https://docs.paybyrd.com/embed/checkout
Checkout is a flexible payment integration solution that enables you to embed a complete payment workflow in your product. It handles payment method integrations and processes sensitive payment information securely, reducing the scope of PCI compliance for you. It integrates with the Paybyrd Gateway to provide a seamless payment experience for your customers and simplifies integration with complex payment infrastructure.
***
## How it works
![Full user workflow of a payment process through Paybyrd Checkout]()
Paybyrd Checkout abstracts the complexity of payment processing by handling all payment method integrations and API communication on your behalf. Instead of building separate integrations for each payment method, you create an order through the Paybyrd API, which generates a secure checkout session. Your customers then complete their payment through the Paybyrd-hosted payment gateway, while you receive status updates and validation data through API responses and webhooks.
**Ways to access Checkout**
Customers can reach the Paybyrd Checkout payment gateway through several scenarios:
* **Ecommerce integration** Customers shop on your online store and select Paybyrd as their payment option at checkout. Your backend (whether using plugins like [WooCommerce](/integrations/ecommerce-plugins/woocommerce.md), [nopCommerce](/integrations/ecommerce-plugins/nopcommerce.md), [Adobe Commerce (Magento)](/integrations/ecommerce-plugins/adobe-commerce-magento.md), or custom implementations) automatically generates an order and redirects the customer to Checkout, either embedded in an iframe or in a separate tab. After completing payment, users are redirected back to your store.
* **[Pay by Link](/embed/pay-by-link)** You create an order (via API or the Paybyrd Dashboard) and send the generated checkout link directly to the customer via email, SMS, or other channels. The customer clicks the link and completes their payment through the Checkout interface.
* **[Point of Sale (POS)](/integrations/point-of-sale/payment-sdk-android)** A staff member initiates the payment through a POS device. The POS backend generates an order and displays Checkout within the device interface. The customer completes the payment directly on the POS device.
### Display variants
Paybyrd Checkout supports 4 display variants: `default`, `detailed`, `minimal`, and `immersive`.
![The 4 display variants of Paybyrd Checkout]()
* `default` is similar to the previous version, showing all necessary details in a central view.
* `detailed` shows a clear overview of the payment details and the available payment methods all within one screen.
* `minimal` is recommended for using in iframes. It focuses on only displaying sections that the user can interact with.
* `immersive` is based on `default` with an extra banner image at the top. Banner styles are available for different merchant categories:
![Immersive banner for airline merchants]()
![Immersive banner for restaurant merchants]()
![Immersive banner for marketplace merchants]()
![Immersive banner for hospitality merchants]()
![Immersive banner for generic merchants]()
You can set the display variant by adding a pathname parameter to the checkout URL. For example: `https://chk.paybyrd.com/detailed?checkoutKey=...`
***
## How to integrate
To integrate Paybyrd Checkout into your ecommerce website, your workflow follows 3 steps:
1. Generate an order
2. Initialize a Checkout instance
3. Validate the payment
***
### 1. Generate an order
When a customer proceeds to the checkout page in your ecommerce website, you need to create an order using the Paybyrd API. Use the request body to add all order details, define the available payment methods, and set up redirects after payment conclusion.
The API’s response to your request contains all information needed to load the payment gateway and enable the end user to finish their payment.
```bash Example request theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '{
"amount":"15.00",
"currency":"EUR",
"orderRef":"ABC123456",
"expiresIn":24,
"shopper":{
"firstName":"John",
"lastName":"Doe",
"email":"john@doe.com",
"phoneNumber":"+319999999921"
},
"orderOptions":{
"redirectUrl":"https://your-site-url/payment-finished",
"checkoutVersion": 2
},
"paymentOptions":{
"tokenOptions":{
"customReference":"+319999999921"
}
}
}'
```
```json Success response theme={null}
{
"orderId":"13a8a157-81c9-46ea-84b4-2bef6daad3fa",
"orderDate":"2026-02-24T17:45:27Z",
"expiresAt":"2026-02-25T17:45:27Z",
"checkoutUrl":"https://chk.paybyrd.com/chk_a321as123a",
"checkoutKey":"eyJPcmRlcklkIjoiMzFhMDYzMmItODcxMy00NjIwLThiZjItMDdiN2UyZTk5MTRjIiwiT3JkZXJSZWYiOiI0MTAxMjA3MTU0IiwiUGVyc29uSWQiOjEwLCJMaXZlIjpmYWxzZSwiRW50aXR5SWQiOiIzMWEwNjMyYi04NzEzLTQ2MjAtOGJmMi0wN2I3ZTJlOTkeNGMiLCJBbW91bnQiOiI1MC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0=",
"status":"created",
"isoAmount":15,
"currency":"EUR",
"orderRef":"ABC123456",
"shopper":{
"shopperId":"176b5023-1624-1d19-cdd2-c61b1be803b7",
"firstName":"John",
"lastName":"Doe",
"email":"john@doe.com",
"phoneNumber":"+319999999921"
},
"orderOptions":{
"redirectUrl":"https://your-site-url/payment-finished",
"culture":"en-US",
"expiresIn":"24",
"checkoutVersion": 2
},
"paymentOptions":{
"tokenOptions":{
"customReference":"+319999999921"
}
},
"code":"BYRD200",
"description":"Operation successfully completed"
}
```
See the [API reference](/api-reference/orders/create-order) for full details.
Paybyrd Checkout supports Tokenized Payments, which enable future payments by storing card information. To enable Tokenized Payments, include the `tokenOptions` object with a `customReference` item in the request body when creating an order. `customReference` should be unique information from the end user. See the [Tokenization guide](/advanced/tokenization) to learn more.
After creating an order, the response from the Paybyrd API contains the necessary information you need for initializing a Checkout instance. These are:
* `orderId`: a unique identifier for the order,
* `checkoutKey`: order details encoded in Base64 format,
* `checkoutUrl`: a URL that points to the payment gateway.
See the [Checkout reference page](/embed/checkout-parameter-reference) for more information.
***
### 2. Initialize a Checkout instance
When the order is ready, you can initialize a Checkout instance in two ways:
* as an iframe embedded in your website,
* by taking users directly to the Checkout instance hosted by Paybyrd, via the checkout URL.
Both methods enable you to customize and fine-tune the payment experience using parameters that control:
* the language of the payment gateway,
* which display variant is shown,
* what payment methods are available for the user,
* whether you redirect the user to a different page after the payment is done,
* different UI elements like logo, header, footer, and colors.
***
**Using an iframe**
You can use an iframe to directly embed Paybyrd Checkout into your website. Use this code snippet to load the payment gateway in an iframe:
```jsx Example snippet for loading in an iframe theme={null}
(function() {
function initCheckout(data) {
const configs = btoa(JSON.stringify(data));
const ENV_URL = `https://chk.paybyrd.com/?checkoutKey=${data.checkoutKey}&orderId=${data.orderId}&configs=${configs}`;
const container = document.createElement('DIV');
container.style.width = '100%';
container.style.height = '100vh';
const iframe = document.createElement('IFRAME');
iframe.style.width = '100%';
iframe.style.height = '100%';
iframe.style.border = 'none';
iframe.style.position = 'fixed';
iframe.style.zIndex = 999999;
iframe.style.top = 0;
iframe.style.left = 0;
iframe.id = 'pb-hf-ifrm';
// Prod
iframe.src = ENV_URL;
iframe.onload = function() {
document.body.style.overflow = 'hidden';
}
container.append(iframe);
document.body.append(container);
}
const paybyrd_params = THIS_DATA_SHOULD_BE_DEFINED_BY_THE_SERVER;
initCheckout({
redirectUrl: paybyrd_params.redirectUrl,
locale: paybyrd_params.locale
theme: {
backgroundColor: paybyrd_params.theme.hfBackgroundColor,
formBackgroundColor: paybyrd_params.theme.hfFormBackgroundColor,
primaryColor: paybyrd_params.theme.hfPrimaryColor,
textColor: paybyrd_params.theme.hfTextColor,
effectsBackgroundColor: paybyrd_params.hfEffectsBackgroundColor,
},
autoRedirect: true,
showCancelButton: false,
skipATMSuccessPage: false,
compact: false
});
})();
```
Note the configuration parameters under `initCheckout`.
***
**Using a direct URL**
You can also use a direct URL to take your customers to the Paybyrd payment gateway within the same page or in a new tab. This URL requires the `?checkoutKey` and `?orderId` query parameters:
```http Example for a direct URL theme={null}
https://chk.paybyrd.com/?checkoutKey={CHECKOUT_ID}&orderId={ORDER_ID}&configs={CONFIGS}
```
You can also use the `?configs` query parameter to enable further customization. The value of this parameter is the `configs` JSON object **encoded to base64 format.**
```json The raw configuration object theme={null}
{
"redirectUrl":"https://your-site-url/payment-finished",
"locale":"en_US",
"theme":{
"backgroundColor":"#F0F0F0",
"formBackgroundColor":"#3C3C3C",
"primaryColor":"#CCCCCC",
"textColor":"#FFFFFF",
"effectsBackgroundColor":"#DBDBDB"
},
"autoRedirect":true,
"showCancelButton":false
}
```
```json Encoded to Base64 theme={null}
ewogICAicmVkaXJlY3RVcmwiOiJodHRwczovL3lvdXItc2l0ZS11cmwvcGF5bWVudC1maW5pc2hlZCIsCiAgICJsb2NhbGUiOiJlbl9VUyIsCiAgICJvcmRlcklkIjoiMTNhOGExNTctODFjOS00NmVhLTg0YjQtMmJlZjZkYWFkM2ZhIiwKICAgImNoZWNrb3V0S2V5IjoiZXlKUGNtUmxja2xrSWpvaU16RmhNRFl6TW1JdE9EY3hNeTAwTmpJd0xUaGlaakl0TURkaU4yVXlaVGs1TVRSaklpd2lUM0prWlhKU1pXWWlPaUkwTVRBeE1qQTNNVFUwSWl3aVVHVnljMjl1U1dRaU9qRXdMQ0pNYVhabElqcG1ZV3h6WlN3aVJXNTBhWFI1U1dRaU9pSXpNV0V3TmpNeVlpMDROekV6TFRRMk1qQXRPR0ptTWkwd04ySTNaVEpsT1RrZU5HTWlMQ0pCYlc5MWJuUWlPaUkxTUM0d01DSXNJa04xY25KbGJtTjVJam9pUlZWU0luMD0iLAogICAidGhlbWUiOnsKICAgICAgImJhY2tncm91bmRDb2xvciI6IiNGMEYwRjAiLAogICAgICAiZm9ybUJhY2tncm91bmRDb2xvciI6IiMzQzNDM0MiLAogICAgICAicHJpbWFyeUNvbG9yIjoiI0NDQ0NDQyIsCiAgICAgICJ0ZXh0Q29sb3IiOiIjRkZGRkZGIiwKICAgICAgImVmZmVjdHNCYWNrZ3JvdW5kQ29sb3IiOiIjREJEQkRCIgogICB9LAogICAiYXV0b1JlZGlyZWN0Ijp0cnVlLAogICAic2hvd0NhbmNlbEJ1dHRvbiI6ZmFsc2UsCn0=
```
After the payment gateway initializes, your user can go through the whole payment process.
***
### 3. Validate the payment
Payment validation works differently depending on whether the payment method is synchronous or asynchronous.
**Synchronous payments**
For synchronous payments, like credit cards, the entire payment flow completes within the Checkout session. When the user finishes the payment process, the payment gateway redirects them to the URL you defined in the `redirectUrl` parameter.
Set your `redirectUrl` to an intermediate page in your application (for example, `yourstore.com/payment-verification/{orderId}`) where you can query the order status via the Paybyrd API to confirm the payment result:
```bash theme={null}
curl --request GET \
--url https://gateway.paybyrd.com/api/v2/orders/{ORDERID} \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}'
```
This verification step ensures your application reflects the correct order status, whether the payment succeeded or failed.
**Asynchronous payments**
For asynchronous payments, like Multibanco, the user completes the payment outside of the Checkout session, for example, at a physical ATM. Since the payment happens independently, redirecting the user back to your application does not provide payment confirmation.
Instead, configure a webhook to receive automatic updates when the order status changes. The Paybyrd API sends `POST` requests to your webhook URL, notifying you when payments are completed or failed. This enables you to update order statuses in your application reliably, keeping your system synchronized with Paybyrd.
**Best practice: Use webhooks for all payment types**
Make sure you configure webhooks regardless of payment method type. Webhooks provide a reliable fallback for scenarios where users close their browser before being redirected, or when network issues interrupt the payment flow. When an order status changes, you receive the `paymentId` and `transactionId` in the webhook payload, enabling you to verify and update the payment status accordingly.
Read the [Webhooks reference](/api-reference/webhooks) to learn more about creating and managing webhooks.
***
## Customizing Paybyrd Checkout
You can customize the colors and appearance of Checkout. Whether you use an iframe or a direct URL to load the payment gateway, you can use the same parameters to define a visual experience that fits your branding.
Add a `theme` object to `configs` when you initialize Checkout. You can include any of these parameters:
| **Parameter** | **Description** | **Accepted values** | **Required** |
| ------------------------ | --------------------------------------------------------------------------------------- | ------------------- | ------------ |
| `backgroundColor` | Defines the background color of the entire page. | Hex color code | No |
| `formBackgroundColor` | Defines the background color of the Checkout form. | Hex color code | No |
| `primaryColor` | Defines the color of accents: borders, input field backgrounds, and button backgrounds. | Hex color code | No |
| `textColor` | Defines the font color. | Hex color code | No |
| `effectsBackgroundColor` | Defines the background color of the effects layer. | Hex color code | No |
```json theme={null}
{
... // other configuration options
"theme":{
"backgroundColor":"#000",
"textColor":"#dccfcf"
}
}
```
Read more about each parameter in the [Checkout reference](/embed/checkout-parameter-reference).
# Migration guide
Source: https://docs.paybyrd.com/embed/checkout-migration-guide
In a recent update, we have released a new version of Paybyrd’s payment gateway solution. Previously known as the Hosted Form, Paybyrd Checkout is now available for use. This update introduces new display functionality, a more streamlined payment flow, and several user experience improvements.
We have created this guide to help you migrate to the new version of Paybyrd Checkout.
To ensure that transition to the new version is seamless, Paybyrd continues to support implementations of the previous version for an indefinite period.
***
## List of changes
This section gives you a summary of the updates.
### Important changes
* The new version is now served through a different host URL. `checkout.paybyrd.com` changes to `chk.paybyrd.com`
* The payment gateway’s pathname is now formed differently. `/#/payment?checkoutKey=` changes to `/?checkoutKey=`
* A new request body parameter is now available for the `orderOptions` object in the [Create order endpoint](/api-reference/orders/create-order): `checkoutVersion`. This parameter enables you to set the version of Paybyrd Checkout that you want to generate for an order. Accepted values are:
* `1`: previous version
* `2`: new version
```json theme={null}
"orderOptions": {
"checkoutVersion": 2
},
```
* Checkout can now also support displaying external modals in full screen. When using the previous version within an iframe, any external modals that open up during the payment process were confined within the iframe. You can now define these to load in full screen. Examples include 3DSecure checks and other MFA methods that would open up in an external modal.
![A diagram showing the 4 display variants of Paybyrd Checkout]()
* Paybyrd Checkout now supports 4 different display variants: `default`, `detailed`, `minimal`, and `immersive`
* `default` is similar to the previous version.
* `detailed` shows a clear overview of the payment details and the available payment methods all within one screen.
* `minimal` is recommended for using in iframes. It focuses on only displaying sections that the user can interact with.
* `immersive` is based on `default` with an extra banner image at the top. Banner styles include airline, restaurant, marketplace, hospitality, and generic.
* You can set the display variant by adding a pathname property to the checkout URL. For example: `https://chk.paybyrd.com/detailed?checkoutKey=...`
***
### UX updates
![Full user workflow of a payment process through Paybyrd Checkout]()
* We have introduced an extra confirmation step in the payment process. This step gives end users a chance to confirm their selected payment methods before generating an order. The goal of this improvement is to eliminate user error by enabling end users to change their payment method selection.
* We have also added clear status messages and explanations so end users always know where they are within the payment process.
* Paybyrd now offers improved error messaging that show the cause of payment errors for specific payment methods.
* Checkout can now display extended information like flight or shopping cart details right within the landing page of the payment gateway.
### New and updated parameters
The new Checkout version now supports these parameters to customize the payment gateway:
**Set display variant**
Use this property in the pathname of the checkout URL to set a display variant.
| **Property** | **Type** | **Required** | **Example value** | **Description** |
| --------------------------------------------------- | -------- | ------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `https://chk.paybyrd.com/?checkoutKey=...` | pathname | No | `https://chk.paybyrd.com/detailed?checkoutKey=...` | Accepted values: `default`, `detailed`, `minimal`, `immersive`. When not set, falls back to `default`. |
**Customize UX**
Use these parameters to further customize the checkout experience. Learn how to set these parameters in the [Checkout guide](/embed/checkout).
| **Parameter** | **Type** | **Required** | **Example value** | **Description** |
| ---------------------------------- | ------------ | ------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `logoUrl` | string / uri | No | `https://domain.com/files/logo.png` | A URL pointing to your logo. Accepted file types are `JPG`, `PNG`, and `SVG`. Keep file sizes small to avoid slowing down page loads. |
| `hideLogo` | boolean | No | `true` or `false` | Controls whether your logo is visible to the end user. Defaults to `false`. |
| `showHeader` | boolean | No | `true` or `false` | Show or hide a UI section with your logo at the top. Defaults to `true`. |
| `showOrderSummary` | boolean | No | `true` or `false` | Controls whether an order summary screen is shown at the beginning of the payment process. Defaults to `true`. |
| `fullscreenModals` | boolean | No | `true` or `false` | When `true`, external modals such as 3DS checks or other MFA methods open in full screen. Defaults to `false`. |
| `skipMBWayWaitingForPaymentScreen` | boolean | No | `true` or `false` | Skips the polling screen for MB WAY payments. When `true`, the user is redirected to `redirectUrl` immediately. Defaults to `false`. |
See the [documentation](/embed/checkout-parameter-reference) for a complete list of parameters.
***
## Migrating to the new version
If you need support in migrating to the new version, reach out to the [Paybyrd operations team](mailto:help@paybyrd.com).
### 1. Define the version during order creation
To create a Checkout instance that uses the new version, add the `checkoutVersion` body parameter to the `orderOptions` object in your [Create order](/api-reference/orders/create-order) request, and set the value to `2`:
```jsx theme={null}
"orderOptions": {
... // other order options
"checkoutVersion": 2
},
```
This enables the Paybyrd API to return a `checkoutUrl` that points to the new version, using `chk.paybyrd.com` as the host URL.
You can then use the resulting checkout URL in your implementation when displaying the payment gateway.
### 2. Update URL references in your implementation
* When using an iframe to display the Paybyrd payment gateway, make sure you update the value of the `ENV_URL` constant to use the new host URL: `chk.paybyrd.com`
* When using a standalone link to direct the user to the payment gateway, make sure that you present a checkout URL that uses the new host URL: `chk.paybyrd.com`
Other methods, such as Pay by Link and PoS payments also use the new URL.
To ensure that transition to the new version is seamless, Paybyrd continues to support implementations of the previous version for an indefinite period.
If you do not want to update yet, set the `checkoutVersion` body parameter to `1` in the `orderOptions` object when you [Create an order](/api-reference/orders/create-order). This forces the Paybyrd API to provide a legacy checkout URL in the response, enabling your implementation to use the previous version of Paybyrd Checkout:
```json theme={null}
"orderOptions": {
... // other order options
"checkoutVersion": 1
}
```
Note that you will not be able to use any new features this way.
# Checkout parameter reference
Source: https://docs.paybyrd.com/embed/checkout-parameter-reference
This page contains all available parameters and properties that you can use to initialize and customize Paybyrd Checkout.
***
## Query parameters
These parameters are part of the Checkout URL. Use them to generate and customize the payment gateway.
| **Parameter** | **Type** | **Required** | **Description** |
| ------------- | ------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `orderId` | GUID | Yes | Identifies the order that the user sees during checkout. Generated during [order creation](/api-reference/orders/create-order). |
| `checkoutKey` | GUID | Yes | Identifies the checkout session that the user accesses. Generated during [order creation](/api-reference/orders/create-order). |
| `configs` | JSON object encoded to base64 string | No | Enables further customization for the payment gateway. See [Checkout customization](/embed/checkout#how-to-integrate). |
***
## Pathname properties
Set a display variant by adding it to the URL path between the domain and the query string. When not set, falls back to `default`.
| **Variant** | **Description** |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | Standard layout. |
| `detailed` | Shows payment details and available methods on a single screen. |
| `minimal` | Recommended for iframes. Displays only the sections the user can interact with. |
| `immersive` | Based on `default` with an extra banner image at the top. Banner styles include airline, restaurant, marketplace, hospitality, and generic. |
```
https://chk.paybyrd.com/?checkoutKey=…&orderId=…&configs=…
```
**Examples**
* No variant (falls back to `default`): `https://chk.paybyrd.com/?checkoutKey=<…>&orderId=<…>&configs=<…>`
* `default`: `https://chk.paybyrd.com/default?checkoutKey=<…>&orderId=<…>&configs=<…>`
* `detailed`: `https://chk.paybyrd.com/detailed?checkoutKey=<…>&orderId=<…>&configs=<…>`
* `minimal`: `https://chk.paybyrd.com/minimal?checkoutKey=<…>&orderId=<…>&configs=<…>`
* `immersive`: `https://chk.paybyrd.com/immersive?checkoutKey=<…>&orderId=<…>&configs=<…>`
***
## Checkout customization parameters
Add these parameters to the `configs` object during initialization to further customize the checkout experience. The `configs` object should be **encoded to base64 format and then used as a query parameter in the checkout URL.**
Learn how to set these parameters in the [Checkout usage guide](/embed/checkout#how-to-integrate).
***
### `locale`
Sets the display language of Checkout. Defaults to `en-US` (English).
**Accepted values:** `en-US`, `en-UK`, `pt-PT`, `pt-BR`
| **Parameter** | **Type** | **Required** | **Example value** |
| ------------- | ------------- | ------------ | ----------------- |
| `locale` | string / enum | No | `en-US` |
***
### `logoUrl`
A URL pointing to your logo. Accepted file types are `JPG`, `PNG`, and `SVG`. Keep file sizes small to avoid slowing down page loads.
| **Parameter** | **Type** | **Required** | **Example value** |
| ------------- | ------------ | ------------ | ----------------------------------- |
| `logoUrl` | string / uri | No | `https://domain.com/files/logo.png` |
***
### `hideLogo`
Controls whether your logo is visible to the end user within the payment gateway.
| **Parameter** | **Type** | **Required** | **Example value** |
| ------------- | -------- | ------------ | ----------------- |
| `hideLogo` | boolean | No | `true` or `false` |
***
### `showHeader`
Show or hide the header. Defaults to `true`.
| **Parameter** | **Type** | **Required** | **Example value** |
| ------------- | -------- | ------------ | ----------------- |
| `showHeader` | boolean | No | `true` or `false` |
***
### `showFooter`
Show or hide the footer. Defaults to `true`.
| **Parameter** | **Type** | **Required** | **Example value** |
| ------------- | -------- | ------------ | ----------------- |
| `showFooter` | boolean | No | `true` or `false` |
***
### `showCancelButton`
Controls whether a **Cancel Payment** button is displayed. When clicked, the order status is set to Cancelled and the user is redirected to `redirectUrl`. Defaults to `false`.
| **Parameter** | **Type** | **Required** | **Example value** |
| ------------------ | -------- | ------------ | ----------------- |
| `showCancelButton` | boolean | No | `true` or `false` |
***
### `showOrderSummary`
Controls whether an order summary screen is shown at the beginning of the payment process. Defaults to `true`.
| **Parameter** | **Type** | **Required** | **Example value** |
| ------------------ | -------- | ------------ | ----------------- |
| `showOrderSummary` | boolean | No | `true` or `false` |
***
### `fullscreenModals`
When `true`, external modals such as 3DS checks or other MFA methods open in full screen. Defaults to `false`.
| **Parameter** | **Type** | **Required** | **Example value** |
| ------------------ | -------- | ------------ | ----------------- |
| `fullscreenModals` | boolean | No | `true` or `false` |
***
### `defaultPaymentMethod`
Redirects the user directly to a predefined payment method on load. If the specified method is unavailable, the user sees the default payment method list.
When there is only one available payment method, Checkout automatically redirects to it and `defaultPaymentMethod` is ignored. When multiple methods are available, the user is redirected to the defined method and Checkout shows a back button so the user can select a different method.
Defaults to undefined.
**Accepted values:** `AMEX`, `APPLE`, `ELO`, `MASTER`, `MASTERDEBIT`, `MASTERCARD`, `PAYPAL`, `VISAELECTRON`, `VISADEBIT`, `VISA`, `DISCOVER`, `SIBS_MULTIBANCO`, `MULTIBANCO`, `SIBS_MBWAY`, `MBWAY`, `IDEAL`, `MAESTRO`, `CARTEBANCAIRE`, `DANKORT`, `DINERS`, `JCB`, `VPAY`, `SEPA`, `MULTICAIXA`, `MULTICAIXA_REF`, `MULTICAIXAEXPRESS`, `BANKTRANSFER`, `PICKUP`, `FLOA`, `FLOA3X`, `FLOA4X`, `FLOA1XD`, `PIX`, `REVOLUTPAY`, `SAMSUNGPAY`, `APPLEPAY`, `NUPAY`, `CREDITCARD`, `KLARNA`, `HIPERCARD`, `UNIONPAY`
| **Parameter** | **Type** | **Required** | **Example value** |
| ---------------------- | ------------- | ------------ | ----------------- |
| `defaultPaymentMethod` | string / enum | No | `CARD` |
***
### `redirectUrl`
The URL the user is redirected to after the payment is finished.
| **Parameter** | **Type** | **Required** | **Example value** |
| ------------- | ------------ | ------------ | --------------------------------------- |
| `redirectUrl` | string / uri | Yes | `https://domain.com/payment-validation` |
***
### `autoRedirect`
Controls whether the user is automatically redirected to `redirectUrl` after payment. When `false`, the user sees the Paybyrd payment validation page. Defaults to `false`.
| **Parameter** | **Type** | **Required** | **Example value** |
| -------------- | -------- | ------------ | ----------------- |
| `autoRedirect` | boolean | No | `true` or `false` |
***
### `skipATMSuccessPage`
When `true`, redirects the user to `redirectUrl` instead of displaying the entity and reference values for ATM payments. Use this to handle the post-payment flow on your own side. Defaults to `false`.
| **Parameter** | **Type** | **Required** | **Example value** |
| -------------------- | -------- | ------------ | ----------------- |
| `skipATMSuccessPage` | boolean | No | `true` or `false` |
***
### `skipMBWayWaitingForPaymentScreen`
Skips the polling screen shown while waiting for MB WAY payments. When `true`, the user is redirected to `redirectUrl` immediately. Defaults to `false`.
| **Parameter** | **Type** | **Required** | **Example value** |
| ---------------------------------- | -------- | ------------ | ----------------- |
| `skipMBWayWaitingForPaymentScreen` | boolean | No | `true` or `false` |
***
### `theme`
Controls the visual appearance of Checkout using hex color values. Pass this as a nested object inside `configs`.
| **Property** | **Type** | **Description** |
| ------------------------ | ------------ | --------------------------------------------------------- |
| `backgroundColor` | string (hex) | Page background color. |
| `formBackgroundColor` | string (hex) | Form container background color. |
| `primaryColor` | string (hex) | Accent color for borders, input backgrounds, and buttons. |
| `textColor` | string (hex) | Font color. |
| `effectsBackgroundColor` | string (hex) | Effects layer background color. |
```json theme={null}
"theme": {
"backgroundColor": "#F0F0F0",
"formBackgroundColor": "#3C3C3C",
"primaryColor": "#CCCCCC",
"textColor": "#FFFFFF",
"effectsBackgroundColor": "#DBDBDB"
}
```
***
**Usage example**
Form the URL using this pattern:
```json Example URL theme={null}
https://chk.paybyrd.com/?checkoutKey={CHECKOUT_ID}&orderId={ORDER_ID}&configs={CONFIGS}
```
Where `{CONFIGS}` is a JSON object encoded to **base64 format**:
```json Raw JSON configuration theme={null}
{
"redirectUrl":"https://your-site-url/payment-finished",
"locale":"en_US",
"theme":{
"backgroundColor":"#F0F0F0",
"formBackgroundColor":"#3C3C3C",
"primaryColor":"#CCCCCC",
"textColor":"#FFFFFF",
"effectsBackgroundColor":"#DBDBDB"
},
"autoRedirect":true,
"showCancelButton":false
}
```
```json Encoded to Base64 theme={null}
ewogICAicmVkaXJlY3RVcmwiOiJodHRwczovL3lvdXItc2l0ZS11cmwvcGF5bWVudC1maW5pc2hlZCIsCiAgICJsb2NhbGUiOiJlbl9VUyIsCiAgICJvcmRlcklkIjoiMTNhOGExNTctODFjOS00NmVhLTg0YjQtMmJlZjZkYWFkM2ZhIiwKICAgImNoZWNrb3V0S2V5IjoiZXlKUGNtUmxja2xrSWpvaU16RmhNRFl6TW1JdE9EY3hNeTAwTmpJd0xUaGlaakl0TURkaU4yVXlaVGs1TVRSaklpd2lUM0prWlhKU1pXWWlPaUkwTVRBeE1qQTNNVFUwSWl3aVVHVnljMjl1U1dRaU9qRXdMQ0pNYVhabElqcG1ZV3h6WlN3aVJXNTBhWFI1U1dRaU9pSXpNV0V3TmpNeVlpMDROekV6TFRRMk1qQXRPR0ptTWkwd04ySTNaVEpsT1RrZU5HTWlMQ0pCYlc5MWJuUWlPaUkxTUM0d01DSXNJa04xY25KbGJtTjVJam9pUlZWU0luMD0iLAogICAidGhlbWUiOnsKICAgICAgImJhY2tncm91bmRDb2xvciI6IiNGMEYwRjAiLAogICAgICAiZm9ybUJhY2tncm91bmRDb2xvciI6IiMzQzNDM0MiLAogICAgICAicHJpbWFyeUNvbG9yIjoiI0NDQ0NDQyIsCiAgICAgICJ0ZXh0Q29sb3IiOiIjRkZGRkZGIiwKICAgICAgImVmZmVjdHNCYWNrZ3JvdW5kQ29sb3IiOiIjREJEQkRCIgogICB9LAogICAiYXV0b1JlZGlyZWN0Ijp0cnVlLAogICAic2hvd0NhbmNlbEJ1dHRvbiI6ZmFsc2UsCn0=
```
# Pay by Link
Source: https://docs.paybyrd.com/embed/pay-by-link
Payment Links let you collect payments from customers by sharing a URL, regardless of where they are. A Payment Link is a simple web address that can be shared via SMS or email with your customers. When your customers click the link, they can complete the payment via Paybyrd checkout page.
Payment links are automatically sent through email and SMS when the shopper's email and phone number are provided. If the shopper's contact details are not provided, the link is still generated and you can send it manually.
Payment Links can be created via your Paybyrd Backoffice, via API, or directly at your Paybyrd terminal.
## 01. Customize your Pay by Link
The text displayed in the Pay by Link sent via SMS and/or e-mail can be customized to best suit your business needs.
The text displayed has a maximum of 1.000 characters. To customize it, [send an email to the Paybyrd Support team](mailto:help@paybyrd.com) with your preferred text in each language you want to support.
Paybyrd currently supports the following languages: PT, ES, FR, DE, EN, and NL
## 02. Creating a payment link via API
The following example shows how to create a payment link and the response it returns:
```bash theme={null}
curl --location --request POST 'https://gateway.paybyrd.com/api/v2/paybylink' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '{
"Amount": "10.00",
"SellerEmailAddress": "best@store.com",
"OrderRef": "ABC12345",
"ShopperEmailAddress": "john@test.com",
"ShopperFirstName": "John",
"ShopperLastName": "Test",
"ShopperPhoneNumber": "",
"Culture":"en-US",
"ExpiresIn": 24
}'
```
```json theme={null}
{
"paybyLink": "https://gateway.paybyrd.com/en-US/hostedform?paymentId=ad4293ed-7055-48b2-8bc5-2efaa4fdd34d",
"transactionId": "ad4293ed-7055-48b2-8bc5-2efaa4fdd34d"
}
```
See the [full API reference](/api-reference/payments/create-payment) for all available parameters.
## 03. Creating a payment link via Backoffice
Go to Paybyrd's backoffice and click on the Pay by link menu.
Fill in the form with the payment information, then click Send link.
The link will be automatically sent to the shopper's email or phone number, according to the provided information.
Payment link messages are customizable. You can also send the link in multiple languages.
# Start building
Source: https://docs.paybyrd.com/get-started/start-building
Learn how to access the merchant dashboard and start using the tools Paybyrd provides to build your product.
## Logging in
Your merchant credentials and account details are provided by Paybyrd via email during onboarding. You will need these to access the [merchant dashboard](https://backoffice.paybyrd.com/).
Sign up first if you do not have an account yet.
After logging in, you can [retrieve your API key](https://backoffice.paybyrd.com/#/apikeys), needed to authenticate all API requests.
You can invite team members to your merchant group or store. Visit the [Team Users](https://backoffice.paybyrd.com/#/users) page in the Dashboard to set each user’s access level and send an email invitation.
From the merchant dashboard, you can:
* Search and view transactions
* Issue refunds
* Manage store settings and team members
* Download settlement reports
* Configure refund passwords and account settings
***
## Start building
You can now start integrating Paybyrd. Your integration path depends on your setup: configure a POS terminal, build a custom online checkout, or install a plugin for your e-commerce platform. This section covers the available options depending on your use case.
![Diagram showing integration options]()
![Diagram showing integration options]()
***
### **POS terminal**
If you have been set up with a Paybyrd POS device, it will arrive pre-charged and ready to use. Follow the setup instructions included in the box. Once connected via Wi-Fi or 4G, the terminal is ready to accept payments.
For full usage instructions, see the [POS Terminal Starter Manual](https://www.notion.so/POS-Terminal-Starter-Manual-d4c64742e25e4791a22b53473d0e83f1?pvs=21).
***
### **E-commerce API**
If you are building a custom online checkout, Paybyrd provides REST APIs and front-end components for secure payment collection.
See the [API Reference](/api-reference/payments/create-payment) and the [Paybyrd Checkout](/embed/checkout) documentation to get started.
***
### **No-code plugins**
If you are using Adobe Commerce (Magento), WooCommerce, or nopCommerce, Paybyrd offers ready-made plugins that add payment support without custom integration.
See the available plugin documentation:
* [WooCommerce](/integrations/ecommerce-plugins/woocommerce)
* [nopCommerce](/integrations/ecommerce-plugins/nopcommerce)
* [Adobe Commerce (Magento)](/integrations/ecommerce-plugins/adobe-commerce-magento)
***
## **Need help?**
* **Chat:** Available from the merchant dashboard (bottom right). On the POS terminal, tap the chat icon in the bottom-left corner.
* **Email:** [help@paybyrd.com](mailto:help@paybyrd.com)
* **Phone:** +351 910 042 417
* **Help Center:** [help.paybyrd.com](http://help.paybyrd.com)
# Test your integration
Source: https://docs.paybyrd.com/get-started/test-your-integration
Follow these steps to start testing your Paybyrd integration.
## Request your credentials
You can retrieve your test API keys from the [API Keys](https://backoffice.paybyrd.com/#/apikeys) page in the dashboard. If you don't have an account yet, contact our [Sales team](mailto:sales@paybyrd.com).
The Paybyrd API operates in two modes: test and live. In test mode, requests do not interact with banking networks. The API key you use to authenticate determines which mode is active.
You can manage your API keys in the Developer section of the Paybyrd dashboard.
***
Paybyrd provides specific card numbers for test scenarios. These work only with your test API key and do not result in a real transaction or transfer of funds. The following test scenarios are supported:
* Successful payments with different card schemes.
* Declined payments for different reasons.
* Processing errors caused by unexpected events.
* Capture, refunds, and reversals.
* Different outcomes for 3D Secure authentication.
You can also use the sandbox for automated integration testing. Test cases will not be modified without sufficient advance notice.
## How to use the test cards
When using test cards, use your test API keys in all API calls.
### Testing via API
Pass any of the card numbers on this page in the `card.number` field of the payment request:
```bash Payment creation request example theme={null}
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": "5555341244441115",
"expiration": "02/25",
"cvv": "123",
"holder": "Peter Parker"
}
}'
```
```json Response theme={null}
{
"transactionId": "0e443bff-9052-4eec-a5f1-9db474f2077a",
"type": "Card",
"currency": "EUR",
"orderRef": "ABC12345",
"brand": "VISA",
"fingerprint": "b53b68c8-43af-4acc-bc79-e892dd6a9a38",
"amount": "8.15",
"isPreAuth": false,
"redirectUrl": "https://your-shop-url?orderRef=ABC12345",
"action": {
"type": "redirect",
"url": "https://link-s.paybyrd.com/3ds_Q44clBT77"
},
"card": {
"number": "555534******1115",
"expiration": "12/25",
"cvv": "***",
"holder": "Peter Parker"
},
"code": "BYRD207",
"description": "Pending redirect"
}
```
See the [full API reference](/api-reference/payments/create-payment) for all request parameters.
### Testing Checkout and Pay by Link
When using Paybyrd Checkout or Pay by Link, enter a test card number in the card number field and complete the payment as normal.
## Test cards
Any card number not listed below will result in a declined transaction.
### Successful scenarios
| Card number | Scheme | Type | Requires 3DS |
| ---------------- | ---------- | ------ | ------------ |
| 5555341244441115 | Mastercard | Credit | No |
| 5448280000000007 | Mastercard | Credit | Yes |
| 5277696455399733 | Mastercard | Debit | Yes |
| 4235647728025682 | Visa | Credit | Yes |
| 4761120000000148 | Visa | Debit | Yes |
| 36490101441625 | Diners | Credit | Yes |
| 3569990012290937 | JCB | Credit | Yes |
| 346267217553369 | AMEX | Credit | Yes |
| 6011000990139424 | Discover | Credit | Yes |
### Error scenarios
| Card number | Scheme | Type | Expected result |
| ---------------- | ---------- | ------ | ----------------- |
| 4000000000000119 | Visa | Credit | Error |
| 5201282999005515 | Mastercard | Credit | Timeout (success) |
| 5201288134424891 | Mastercard | Credit | Timeout (error) |
### Refund errors
| Card number | Scheme | Type | Requires 3DS | Expected result |
| ---------------- | ---------- | ------ | ------------ | --------------- |
| 5186170000000006 | Mastercard | Credit | No | Declined |
| 5186170000000014 | Mastercard | Credit | No | Error |
| 5186170000000022 | Mastercard | Credit | No | Timeout |
| 4444333322221111 | Visa | Credit | No | Declined |
| 4917610000000000 | Visa | Credit | No | Error |
| 4484070000000000 | Diners | Credit | No | Timeout |
### 3D Secure scenarios
| Card number | Scheme | Expected result |
| ---------------- | ---------- | -------------------------------------- |
| 5505772716954642 | Mastercard | Not enrolled |
| 2720290928104209 | Mastercard | Unauthorized |
| 5431885746329897 | Mastercard | DSMethod execution |
| 4844874705184109 | Visa | Challenge required |
| 4268796620674517 | Visa | Attempt followed by challenge required |
# Adobe Commerce (Magento)
Source: https://docs.paybyrd.com/integrations/ecommerce-plugins/adobe-commerce-magento
Adobe Commerce—formerly known as Magento—is an open-source e-commerce platform that provides tools to build and manage online stores. It offers extensive customization and provides marketing features for both B2B and B2C user experiences.
Paybyrd utilizes the Adobe Commerce extension ecosystem to seamlessly embed the secure Paybyrd payment gateway into your payment and checkout process.
## How to install
### Requirements
Before installing Paybyrd's payment gateway extension, make sure you meet these requirements:
* Adobe Commerce (Magento) is already installed and configured with a production or staging environment.
* You have a Paybyrd account with Test and Live API keys.
* Your store has a public domain available. Order status updates in Magento work through async webhook calls, which require a publicly exposed URL.
The Paybyrd payment gateway extension supports Magento 2.3.x and the latest 2.4.x versions. Paybyrd actively optimizes this extension for the latest updates.
### Downloading the extension
Get in touch with our support team to get direct access to the extension.
### Installing the extension
Visit the Adobe Commerce documentation on how to install the extension.
You will need the extension's name and version to enable it in your store:
```bash theme={null}
composer require paybyrd/paymentgateway:1.1.1
```
### Uninstalling the extension
Visit the Adobe Commerce documentation for details in case you need to uninstall the Paybyrd extension.
## How to configure
To configure the Paybyrd payment gateway extension for Magento:
1. Open the Adobe Commerce (Magento) console
2. Navigate to Stores → Configuration
3. Open the Sales dropdown to select Payment Methods
4. Select the Paybyrd Payment Method to see all configuration options
You can configure these aspects:
* **Title** is the displayed name of the payment method. By default, the value is set by Paybyrd.
* **Post Payment Redirect Url** is the web address where the payment gateway redirects the user after a payment is completed. By default, the value is set to show the order payment confirmation page by Paybyrd.
* **Instructions** is a brief description of the payment method.
* **API Key** and **Test API Key** are the API keys required to make transactions. The Test API Key identifies you in Paybyrd's sandbox and enables testing. The API Key enables production transactions.
* **Webhook ID** and **Webhook Key** are automatically generated after saving your API keys. Magento uses these to receive async updates when Paybyrd processes a transaction.
* **Post Checkout Redirect** defines whether you want to redirect the user after checkout to complete a payment. Paybyrd recommends setting the redirect to Yes for a secure and smooth payment experience.
* When set to Yes, the gateway redirects the user to a payment page hosted by Paybyrd.
* When set to No, the gateway renders the payment page in an iframe in your store's website.
* **Test Mode** enables the use of Paybyrd's test environment. When enabled, all payments use your Test API Key.
* **Color settings** enable you to set up the Paybyrd extension to fit your store's branding through configuring background and font colors.
## Understand the payment flow
When using Paybyrd's payment gateway extension, the end user goes through this payment flow:
1. User selects the Paybyrd payment method during checkout.
2. Paybyrd creates an order through the extension, using the API keys added during configuration.
# nopCommerce
Source: https://docs.paybyrd.com/integrations/ecommerce-plugins/nopcommerce
nopCommerce is an open-source e‑commerce platform built on the .NET Core framework.
It provides a complete foundation for online stores, offering catalog management, order processing, and payment integration. Its plugin‑based ecosystem enables merchants to extend functionality and scale the platform to their specific needs.
Paybyrd provides a dedicated nopCommerce plugin that embeds its payment methods directly into the checkout experience. After a simple installation and configuration process, merchants can enable secure payment flows driven by Paybyrd.
## How to install
### Requirements
Before installing Paybyrd's nopCommerce plugin, make sure you meet these requirements:
* nopCommerce is already installed and configured with a production or staging environment.
* You have a Paybyrd account with Test and Live API keys.
* Your store has a public domain available. Order status updates in nopCommerce work through async webhook calls, which require a publicly exposed URL.
### Downloading the plugin
You have 2 ways to download the plugin:
**via the nopCommerce marketplace:**
* Visit the plugin's marketplace page
* Select Get Extension.
**via your store's Configuration page:**
* Open the nopCommerce Admin Dashboard
* Navigate to Configuration → Local Plugins
* Search for Paybyrd, and click on Download
Both methods enable you to download the Paybyrd plugin as a ZIP archive.
### Installing the plugin
To install the plugin you downloaded:
1. Open the nopCommerce Admin Dashboard
2. Navigate to Configuration → Local Plugins
3. Select Upload plugin or theme, then upload the ZIP archive
4. Select Reload list of plugins, then find the Paybyrd plugin on the page
5. Click Install, then activate the plugin to make it available as a payment method
Visit the [nopCommerce documentation](https://docs.nopcommerce.com/en/getting-started/advanced-configuration/plugins-in-nopcommerce.html) for more details about installing plugins.
## How to configure
To configure the nopCommerce plugin:
1. open the Admin Dashboard and navigate to Configuration → Payment methods
2. Select Paybyrd and click on Configure
You can configure these aspects:
* **Live Private Key** is required for production transactions.
* **Test Private Key** identifies you in Paybyrd's sandbox and enables testing.
- **Test Mode** toggles the use of Paybyrd’s testing environment. When enabled, all payments are executed with the Test Private Key.
- **Webhook ID** is automatically generated after saving your API keys. nopCommerce uses these IDs to receive asynchronous updates when Paybyrd finalizes a transaction.
- **Order status setting** lets you define how the order status is set after the order is paid via the gateway. The available options are:
* **Processing**
* **Completed**
Select Processing if you have more steps in your workflow before finishing the order fulfillment process, for example shipping.
* **Color settings** enable you to set up the Paybyrd plugin to fit your store’s branding through configuring background and font colors.
To edit the name or the displayed order of the Paybyrd payment method, navigate to **Configuration → Payment methods**, select **Paybyrd** and click on **Edit**.
* **Title**: controls how the payment option appears at checkout
* **Display order**: defines the order of payment methods displayed to the user. `-1` forces an item to take the first place. `1` to `n` then controls the order of the remaining payment methods.
***
## Understand the payment flow
When using Paybyrd’s plugin, the end user goes through this payment flow:
1. User selects the Paybyrd payment method during checkout.
1. Paybyrd creates an order through the plugin, using the API keys added during plugin configuration.
2. nopCommerce loads the Paybyrd payment gateway for the user.
3. User selects a payment method, fills all required fields, and submits the payment request
1. Paybyrd processes the payment request using the selected payment method, for example card. In this case, a payment request is made with the card token, card holder name, expiration date, and any other custom or required field.
2. This payment request generates a transaction for the order.
3. Once this transaction is fulfilled, Paybyrd triggers asynchronous webhooks to the merchant’s domain.
4. nopCommerce updates the order state to **Processing** or **Completed**, according to the configuration.
Order synchronization depends on implementing webhooks correctly. Make sure that your store has a publicly exposed URL to properly receive the webhook notifications from Paybyrd.
***
### Refunds
You can initiate refunds from the nopCommerce order management page once the plugin is active.
Navigate to the **Orders** page in the Admin Dashboard and select the order you need to refund.
* Full refunds return the entire captured amount.
* Partial refunds submit an adjusted value to Paybyrd.
Order status changes only when webhook callbacks confirm that a refund is complete. Without webhook access, nopCommerce does not reflect the updated state.
***
## Going live
Follow these steps when going live with your store:
1. Open the nopCommerce Admin Dashboard and navigate to **Configuration → Payment methods.**
2. Select **Paybyrd** and click on **Configure**
3. Add your **Live Private Key** to enable production API calls
4. Disable the **Enable Test Mode** checkbox
5. Save changes and confirm that Live Webhook IDs are generated
6. Execute a real payment to verify production readiness
***
## Limitations
The Paybyrd plugin in nopCommerce currently contains these limitations:
* Custom checkout themes used in nopCommerce may block the payment gateway from rendering for the user.
* Paybyrd requires a publicly exposed URL to send webhook notifications to. Order synchronization in nopCommerce depends on implementing webhooks correctly: payments done in offline or local instances cannot update the order state.
# WooCommerce
Source: https://docs.paybyrd.com/integrations/ecommerce-plugins/woocommerce
WooCommerce enables you to turn your WordPress website into a fully functional online store. It provides essential features for e-commerce like product listing, inventory management, shopping cart functionality, order management, and secure payments.
Paybyrd's WooCommerce plugin seamlessly integrates the secure Paybyrd payment gateway into your checkout process through a simple and quick installation.
## How to install
Follow the steps to install Paybyrd's payment methods into your WooCommerce store:
### Requirements
Before installing Paybyrd's WooCommerce plugin, make sure you meet these requirements:
* WooCommerce is already installed and configured in your WordPress website.
* You have a Paybyrd account with Test and Live API keys.
When using Paybyrd's plugin in a self-hosted or local environment, make sure that your WordPress server has a publicly exposed URL.\*\* This enables your store to properly receive the webhook notifications from Paybyrd. Order status updates in WooCommerce uses async webhook calls for order status updates, which require a publicly exposed URL.
### Installing the plugin
1. Open the admin page of your WordPress website
2. Navigate to Plugins
3. Select Add New Plugin and search for Paybyrd
4. Select Install Now
5. Once the installation is finished, select Activate
## How to configure
1. Open the admin page of your WordPress website and navigate to the WooCommerce menu
2. Select Settings → Payments
The Paybyrd plugin is only listed as an available payment method when it is correctly installed and activated.\*\* Check the activation status in case you do not see it in this list.
3. Select Manage
You can configure these aspects of the Paybyrd payment gateway:
* **Title** and **Description** define what end users see when they select this payment method
* **Paid order status** lets you define how the order status is set after the order is paid via the gateway. The available options are Processing and Completed.
Select Processing if you have more steps in your workflow before finishing the order fulfillment process, for example shipping.
* **Test Mode** enables the use of Paybyrd's test environment. When enabled, all payments use your Test Private Key.
* **Test Private Key** and **Live Private Key** are the API keys required for transactions. The Test Private Key identifies you in Paybyrd's sandbox and enables testing. The Live Private Key enables production transactions.
* **Webhook ID** and **Webhook Test ID** are automatically generated after saving your API keys. WooCommerce uses these IDs to receive asynchronous updates when Paybyrd processes a transaction.
* **Color settings** are optional and enable you to set up the plugin to fit your store’s branding by configuring background and font colors.
* **Generate Webhook** helps you create new webhook IDs. This option forces the Paybyrd payment gateway to generate new webhooks.
Only check this option when you experience problems with your test or live webhooks, or if the webhook IDs are not generated by default.
After finishing the configuration, select Save. You can now use Paybyrd’s WooCommerce plugin.
In this form, there are some key fields to be filled.
***
## Limitations
### Checkout page layout
Paybyrd’s WooCommerce plugin extension does not support block checkout layout. When using this layout style, Paybyrd does not appear as an available payment method in the checkout page. To solve this issue, switch to the classic checkout mode in the Checkout Page:
1. Open the admin page of your WordPress website and navigate to the **Pages** menu
2. Select **Edit** under **Checkout**
3. When using block style checkout together with the Paybyrd plugin, a warning appears on the **Edit** page. Select **Switch to classic checkout** and select **Update** to save your changes.
Paybyrd should now appear as an available payment option during checkout.
# PAX peripherals Kit
Source: https://docs.paybyrd.com/integrations/point-of-sale/pax-peripherals-kit
To develop an app that communicates with PAX terminal peripherals (such as the printer or camera), use the Neptune Service and PAX's NeptuneLiteAPI.
## Neptune Service
This application manages the devices in PAX PayDroid-based terminals. The peripherals/devices include the printer, the card reader, the contactless card reader, etc.
If you are developing an app that runs inside the PAX POS, Neptune Service must be installed on the terminal before you call the NeptuneLiteApi.
## Neptune Lite API
Once Neptune Service is installed, you can use the NeptuneLiteApi to access the GPS, speaker, cameras, and other peripherals.
The NeptuneLiteApi provides the APIs of the NeptuneService. This currently contains only the Device Adapter Layer module (DAL).
The DAL provides uniform APIs for device operations, abstracting the differences between terminal models.
# Payment SDK (Android)
Source: https://docs.paybyrd.com/integrations/point-of-sale/payment-sdk-android
The Paybyrd Payment SDK allows Android applications to perform payment operations. The Partner App communicates with the Paybyrd Payment App via Android Intents — both apps must be installed on the same POS device. The architecture uses the `startActivityForResult` model.
The SDK is distributed as a `.aar` Android Library file, written in Kotlin.
**SDK version:** `0.0.10`
## Supported operations
* Payment
* Pre-authorisation
* Refund (full and partial)
## Creating a payment
Provide the amount, currency, and type `CHARGE`:
```kotlin theme={null}
val transactionRequest = TransactionRequest(
amount = inputAmount.toLong(),
currency = TransactionCurrencyEnum.EUR,
transactionType = TransactionTypeEnum.CHARGE
)
val transactionData = PaybyrdPaymentSDK.createTransactionData(
context,
transactionRequest
)
startActivityForResult(transactionData.transactionIntent, PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE)
```
**Handling the response:**
```kotlin theme={null}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE) {
val transactionResponseData = PaybyrdPaymentSDK.unpackTransactionResponseData(data?.extras!!)
if (resultCode == PaybyrdPaymentSDK.RESULT_CODE_APPROVED) {
toast("Success")
} else {
val resultCodeMessage = when (transactionResponseData.transactionResponse.code) {
PaybyrdPaymentSDK.CODE_FAILED -> "operation failed not specific reason"
PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_NOT_INITIALIZED -> "operation failed because the terminal is not initialized"
PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_INITIALIZATION_FAILED -> "operation failed because something went wrong in the payment app initialization process"
PaybyrdPaymentSDK.CODE_FAILED_TRANSACTION_NOT_FOUND -> "operation failed because there is no transaction found that matches with the requested operation"
PaybyrdPaymentSDK.CODE_FAILED_SHIFT_NOT_OPENED -> "operation failed because there is no opened shift"
PaybyrdPaymentSDK.CODE_ABORTED -> "operation aborted"
else -> "unknown result code"
}
val transactionStatus = when (transactionResponseData.transactionResponse.status) {
TransactionStatusEnum.UNKNOWN -> "unknown/inconclusive status"
TransactionStatusEnum.APPROVED -> "the performed transaction was approved"
TransactionStatusEnum.DECLINED -> "the performed transaction was declined"
TransactionStatusEnum.ABORTED -> "the performed transaction was aborted by the user"
TransactionStatusEnum.ERROR -> "the performed transaction result in error"
TransactionStatusEnum.FAILED -> "the performed operation failed"
}
toast("$resultCodeMessage - $transactionStatus")
}
showTransactionResponseAlert(transactionResponseData)
}
}
```
## Pre-authorisation
To create a pre-authorisation, use `TransactionTypeEnum.PREAUTHORIZE`. This reserves the funds in the card's credit limit.
```kotlin theme={null}
val transactionRequest = TransactionRequest(
amount = inputAmount.toLong(),
currency = TransactionCurrencyEnum.EUR,
transactionType = TransactionTypeEnum.PREAUTHORIZE
)
val transactionData = PaybyrdPaymentSDK.createTransactionData(
context,
transactionRequest
)
startActivityForResult(transactionData.transactionIntent, PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE)
```
To capture a pre-authorisation, use `TransactionTypeEnum.CHARGE` with the original pre-authorisation identifier. You can capture the full amount or any amount less than the original:
```kotlin theme={null}
val transactionRequest = TransactionRequest(
amount = inputAmount.toLong(),
currency = TransactionCurrencyEnum.EUR,
transactionType = TransactionTypeEnum.CHARGE,
referencedTransactionIdentifier = ${ID_ORIGINAL_PREAUTHORIZATION}
)
val transactionData = PaybyrdPaymentSDK.createTransactionData(
context,
transactionRequest
)
startActivityForResult(transactionData.transactionIntent, PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE)
```
**Handling the response:**
```kotlin theme={null}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE) {
val transactionResponseData = PaybyrdPaymentSDK.unpackTransactionResponseData(data?.extras!!)
if (resultCode == PaybyrdPaymentSDK.RESULT_CODE_APPROVED) {
toast("Success")
} else {
val resultCodeMessage = when (transactionResponseData.transactionResponse.code) {
PaybyrdPaymentSDK.CODE_FAILED -> "operation failed not specific reason"
PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_NOT_INITIALIZED -> "operation failed because the terminal is not initialized"
PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_INITIALIZATION_FAILED -> "operation failed because something went wrong in the payment app initialization process"
PaybyrdPaymentSDK.CODE_FAILED_TRANSACTION_NOT_FOUND -> "operation failed because there is no transaction found that matches with the requested operation"
PaybyrdPaymentSDK.CODE_FAILED_SHIFT_NOT_OPENED -> "operation failed because there is no opened shift"
PaybyrdPaymentSDK.CODE_ABORTED -> "operation aborted"
else -> "unknown result code"
}
val transactionStatus = when (transactionResponseData.transactionResponse.status) {
TransactionStatusEnum.UNKNOWN -> "unknown/inconclusive status"
TransactionStatusEnum.APPROVED -> "the performed transaction was approved"
TransactionStatusEnum.DECLINED -> "the performed transaction was declined"
TransactionStatusEnum.ABORTED -> "the performed transaction was aborted by the user"
TransactionStatusEnum.ERROR -> "the performed transaction result in error"
TransactionStatusEnum.FAILED -> "the performed operation failed"
}
toast("$resultCodeMessage - $transactionStatus")
}
showTransactionResponseAlert(transactionResponseData)
}
}
```
## Refund
Provide the amount, currency, type `REFUND`, and the identifier of the original payment. For a partial refund, provide an amount less than the original.
```kotlin theme={null}
val transactionRequest = TransactionRequest(
amount = refundAmount.toLong(),
currency = TransactionCurrencyEnum.EUR,
transactionType = TransactionTypeEnum.REFUND,
referencedTransactionIdentifier = ${ORIGINAL_CHARGE_IDENTIFIER}
)
val transactionData = PaybyrdPaymentSDK.createTransactionData(
context,
transactionRequest
)
startActivityForResult(transactionData.transactionIntent, PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE)
```
**Handling the response:**
```kotlin theme={null}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == PaybyrdPaymentSDK.PAYMENT_REQUEST_CODE) {
val transactionResponseData = PaybyrdPaymentSDK.unpackTransactionResponseData(data?.extras!!)
if (resultCode == PaybyrdPaymentSDK.RESULT_CODE_APPROVED) {
toast("Success")
} else {
val resultCodeMessage = when (transactionResponseData.transactionResponse.code) {
PaybyrdPaymentSDK.CODE_FAILED -> "operation failed not specific reason"
PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_NOT_INITIALIZED -> "operation failed because the terminal is not initialized"
PaybyrdPaymentSDK.CODE_FAILED_TERMINAL_INITIALIZATION_FAILED -> "operation failed because something went wrong in the payment app initialization process"
PaybyrdPaymentSDK.CODE_FAILED_TRANSACTION_NOT_FOUND -> "operation failed because there is no transaction found that matches with the requested operation"
PaybyrdPaymentSDK.CODE_FAILED_SHIFT_NOT_OPENED -> "operation failed because there is no opened shift"
PaybyrdPaymentSDK.CODE_ABORTED -> "operation aborted"
else -> "unknown result code"
}
val transactionStatus = when (transactionResponseData.transactionResponse.status) {
TransactionStatusEnum.UNKNOWN -> "unknown/inconclusive status"
TransactionStatusEnum.APPROVED -> "the performed transaction was approved"
TransactionStatusEnum.DECLINED -> "the performed transaction was declined"
TransactionStatusEnum.ABORTED -> "the performed transaction was aborted by the user"
TransactionStatusEnum.ERROR -> "the performed transaction result in error"
TransactionStatusEnum.FAILED -> "the performed operation failed"
}
toast("$resultCodeMessage - $transactionStatus")
}
showTransactionResponseAlert(transactionResponseData)
}
}
```
## Querying a transaction
Use the query operation to check transaction status at any point in your application lifecycle. Recommended when the response returns `UNKNOWN` status or when no response is received.
`PaybyrdPaymentSDK.queryTransaction` is synchronous.
```kotlin theme={null}
val queryResult = PaybyrdPaymentSDK.queryTransaction(
requireContext(),
QueryTransactionRequest(
transactionAmount = transactionRequest.amount,
transactionReference = transactionReference,
transactionType = transactionRequest.transactionType,
useReceiptDetails = useReceipt
)
)
```
```kotlin theme={null}
if (queryResult.code == PaybyrdPaymentSDK.CODE_SUCCESS) {
when (queryResult.transactionStatus) {
TransactionStatusEnum.APPROVED -> {
if (queryResult.transactionStatus == TransactionStatusEnum.APPROVED) {
requireActivity().runOnUiThread {
showTransactionResponseAlert(queryResult.transactionResponseData!!)
}
}
}
TransactionStatusEnum.DECLINED,
TransactionStatusEnum.ABORTED,
TransactionStatusEnum.ERROR -> {
requireActivity().runOnUiThread {
Toast.makeText(requireContext(), "queried transaction is declined", Toast.LENGTH_LONG).show()
}
}
TransactionStatusEnum.UNKNOWN, TransactionStatusEnum.FAILED -> {
requireActivity().runOnUiThread {
Toast.makeText(requireContext(), "queried transaction is unknown, try query again after", Toast.LENGTH_LONG).show()
}
}
}
}
```
## Tips
Save the transaction identifier after a successful payment — you will need it for future refunds.
Save the transaction reference created by `PaybyrdPaymentSDK.createTransactionData` so you can query the transaction result if needed. Query the transaction status whenever `UNKNOWN` is returned.
Store transaction details before initiating every transaction so you can query the data if the response is not received.
## Initialisation and provisioning
Your application can provision the Paybyrd Payment App using a service credential and a merchant identifier.
```kotlin theme={null}
val initRequest = InitiateRequest(
serviceCredentialEmail,
serviceCredencialPassword,
merchantIdentifier,
forceInit
)
val initData = PaybyrdSettingsSDK.createInitializationData(
requireContext(),
initRequest
)
startActivityForResult(initData.intent, PaybyrdSettingsSDK.INITIALIZATION_REQUEST_CODE)
```
```kotlin theme={null}
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == PaybyrdSettingsSDK.INITIALIZATION_REQUEST_CODE) {
val initResponseData = PaybyrdSettingsSDK.unpackInitializationResponseData(data?.extras!!)
if (resultCode == PaybyrdSettingsSDK.CODE_INIT_SUCCESS) {
if (initResponseData.code == PaybyrdSettingsSDK.CODE_INIT_ALREADY_INITIATED) {
val errorMessage = "Already init!!"
showSnackBarMessage(errorMessage)
} else {
val errorMessage = getString(R.string.login_success, initResponseData.name, initResponseData.email)
showSnackBarMessage(errorMessage)
}
} else {
when (initResponseData.code) {
PaybyrdSettingsSDK.CODE_INIT_FAILED -> {
val errorMessage = initResponseData.description
showSnackBarMessage(errorMessage)
}
PaybyrdSettingsSDK.CODE_INIT_ERROR_NO_MERCHANT_WITH_PERSON_ID -> {
val errorMessage = "No Person ID!!"
showSnackBarMessage(errorMessage)
}
PaybyrdSettingsSDK.CODE_INIT_LOGGED_WITH_ANOTHER_PERSON_ID -> {
val errorMessage = "Init with another personId!!"
showSnackBarMessage(errorMessage)
}
}
}
}
}
```
The Partner App and Paybyrd Payment App must be installed and running on the same POS device.
## Native SDK version history
| Version | Date | Changes | Notes |
| ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| 0.0.10 | 15/02/2023 | Add Order Reference field | Requires Paybyrd Payment App 3.1.0 or later |
| 0.0.9 | 21/10/2022 | Add Pre-authorisation; Add Initialisation Provisioning; Add Paybyrd App SDK Version to App Details response | Requires Paybyrd Payment App 2.8.0 |
| 0.0.8 | 12/09/2022 | Add more transaction data on payment response (authorization code; terminal id; terminal serial number) | Requires Paybyrd Payment App 2.7.0 |
| 0.0.7 | 01/09/2022 | Support Receipt Details | Requires Paybyrd Payment App 2.7.0 or later |
| 0.0.6 | 21/06/2022 | Support Query Transactions | Requires Paybyrd Payment App 2.3.0 or later |
| 0.0.5 | 16/05/2022 | Support currencies other than EUR; Validate Requested Currency with Merchant Currency | Requires Paybyrd Payment App 2.2.0 or later for non-EUR currencies |
| 0.0.4 | 14/04/2022 | Add card brand and card masked number to payment response | |
| 0.0.3 | 06/04/2022 | Add settings operations: Enable/Disable Automatic Printing; Configure Transaction Result Screen Behaviour (CLOSE\_ON\_TIMEOUT, NEVER\_SHOW, ALWAYS\_SHOW) | |
| 0.0.2 | 30/03/2022 | Support Partial Refunds; Add settings operations: Enable/Disable Receipt Printing; Enable/Disable Kiosk Mode; Set Kiosk App; Get Terminal Data; Get Payment App Data; Configure APN; Install App from SD card path; Enable/Disable Data Roaming; Reboot Terminal | |
| 0.0.1 | 16/08/2021 | Initial version: Payment and Refunds | |
## Full documentation
For the full Kotlin SDK reference, visit the [SDK documentation](https://lykuhoczzinkhzk6cpofpw.on.drv.tw/www.paybyrddocssdk0010.com/).
## JavaScript SDK
A JavaScript SDK is available for progressive web apps running inside an Android WebView. It matches the functionality of native SDK version `0.0.10`.
### Version history
| Version | Date | Changes | Native SDK version | Notes |
| ------- | ---------- | ----------------------------------------------------------------------- | ------------------ | ------------------------------------------- |
| 0.0.2 | 05/07/2023 | Support all features of SDK 0.0.10 | 0.0.10 | Requires Paybyrd Payment App 3.1.0 or later |
| 0.0.1 | 23/09/2021 | Initial version: Payment and Refunds; Support all features of SDK 0.0.8 | 0.0.8 | Requires Paybyrd Payment App 2.7.0 or later |
Contact us to get access to all resources including a complete demonstration project.
# Payment Terminals
Source: https://docs.paybyrd.com/integrations/point-of-sale/payment-terminals
Paybyrd offers a selection of PAX payment terminals.
## PAX A920
The A920 combines the full features of an Android tablet with a powerful POS payment terminal, all in a sleek and compact design. Behind the A920's large HD screen lies a high capacity 5250mAh rechargeable Li-on battery for continuous operations throughout the day.
A920 supports NFC communication which allows Contactless Payments and operations NFC/RFIC cards, like MIFARE and customisable tags.
Read the [A920 specification and datasheet](https://www.pax.us/wp-content/uploads/2023/12/A920-Datasheet.pdf).
## PAX A920Pro
Powered by the fastest processor to simultaneously run the most complex applications under the highest levels of inbuilt payment security. The ultimate viewing experience is delivered on the A920 PRO 5.5-inch touchscreen, enabling you to better showcase logos, adverts, and video clips, creating multiple customer engagement opportunities.
Read the [A920 Pro specification and datasheet](https://www.paxtechnology.com/a920pro).
## PAX A77
The combination of imagination and exploration in a masterpiece of design and performance. The A77 fits in the palm of your hand and your business, offering you an experience never seen before in the market. This payment smartphone integrates seamlessly with the needs of your business with an all-day battery life.
Read the [A77 specification and datasheet](https://www.paxtechnology.com/a77).
## PAX IM30
A premium, interactive interface that can be integrated into all kiosks and vending machines. PAX IM30 is designed to increase sales, implement security, and be impervious to environmental damage. It combines all the cool benefits of Android with the robustness of unattended product, so you can generate new revene streams in any self-service enviroment.
Read the [IM30 specification and datasheet](https://www.paxtechnology.com/im30).
# POS Application Manual
Source: https://docs.paybyrd.com/integrations/point-of-sale/pos-application-manual
## 1. Log-In
Log in using the same credentials as for the Paybyrd dashboard (e-mail and password).
Click on the right ''eye'' to show your password.
If you enter an incorrect email or password, a notification appears at the bottom of the screen.
## 2. Initialization
When you log in, the app will look for the Merchant Data associated with the user.
Select the merchant to use (there can be several merchants associated with a user).
The app then retrieves payment data and saves the merchant data.
* Initializing Payment Module.
* Processing Transactions.
If an initialization error occurs, tap Try Again.
## 3. Menu
The menu contains all main features. Tap any item to open it.
## 4. Payment
In the payment section, enter the amount.
* Processing payment.
* Payment is approved.
After approved payment, you can send a receipt, print a customer receipt, print a merchant receipt, or close.
## 5. PreAuthorization
Select partial or complete payment after reservation.
To capture the full amount, tap Capture.
To capture a partial amount, tap Partial Capture.
* Processing payment.
* Insert or swipe card.
* Payment approved.
After approved payment, you can send a receipt, print a customer receipt, print a merchant receipt, or close.
## 6. Refund
You can choose a partial or complete refund.
Partial refund is only allowed for payments and not for reservation without payment (capture).
If you click on ''complete'' the total amount will be refunded.
Tap OK to enter the operational password and proceed.
The operational password is optional and depends on your merchant configuration.
If you are sure you want to refund the transaction, click ''Refund''.
Type the refund amount.
* Processing payment.
* Payment approved.
## Reports
You can select reports for today, yesterday, and the day before yesterday.
* Payment
* Payment of Reservation (Capture of Preauthorization)
* Refund of Payment
* Refund of Payment of Reservation (capture of Preauthorization)
* Pay by Link Payment
* Transaction Reports Receipt
## Reprint
Select ''Print''.
## Pay by Link
Create a new Pay by Link.
Type the amount.
Enter your client's details.
Enter an order reference.
Select the Pay by link expiration period.
# Remote transaction
Source: https://docs.paybyrd.com/integrations/point-of-sale/remote-transaction
Remote Transaction lets you integrate your software with Paybyrd terminals without a direct cable connection. You can communicate with a specific terminal to initiate a payment remotely from your POS software.
## Initiating a payment
Send a request from your system to the API. The terminal then prompts the shopper to present their card and complete the payment.
This uses the same endpoint as the Create Payment request.
In the Create Payment request, set the "type" field to "POS".
```bash theme={null}
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":"POS",
"amount": "5.00",
"currency": "EUR",
"orderRef": "Order12345",
"terminalSerialNumber": "1234567890",
"isPreAuth":false
}'
```
```json theme={null}
{
"terminalSerialNumber": "1234567890",
"isPreAuth": false,
"type": "POS",
"currency": "EUR",
"orderRef": "Order12345",
"code": "BYRD201",
"description": "Payment being processed. Waiting for shopper",
"transactionId": "b01e1cea-b212-42a2-a825-400784efd158",
"amount": "5.00"
}
```
See the [full API reference](/api-reference/payments/create-payment) for the Create Payment endpoint.
To select which terminal processes the transaction, provide its serial number in the `terminalSerialNumber` field. You can find the serial number on the device under the settings menu.
The response code expected for this call is `BYRD201` and the object includes a `transactionId` value you need in subsequent calls to query the transaction.
## Receiving payment result
The result of the transaction is obtained in asynchronous communication between Paybyrd and the merchant/partner software.
To receive the asynchronous response, set up an HTTPS webhook server to receive notifications. Paybyrd will send the transaction result to that endpoint once the terminal completes the operation.
# Welcome to Paybyrd!
Source: https://docs.paybyrd.com/introduction
Accept card, digital wallet, bank transfer, and in-store payments through a single REST API. PCI-compliant and built for both e-commerce and POS transactions.
Paybyrd is an omnichannel payments platform that gives merchants and developers a unified REST API to process payments across digital and physical channels. Whether you're building an online checkout, embedding a payment form, or integrating with a POS terminal, Paybyrd provides consistent APIs, pre-built UI components, and ready-made e-commerce plugins to get you accepting payments quickly.
This documentation is available as an MCP server. Select **Copy MCP Server** from the sidebar to add it to your AI assistant or IDE.
Get your API keys and make your first payment request in minutes.
Explore all supported payment methods: cards, wallets, bank transfers, and BNPL.
Add an embedded Checkout, card collect widget, or pay-by-link to your app.
Connect Paybyrd to WooCommerce, Magento, NopCommerce, or POS hardware.
## How it works
Sign up and log in to your merchant dashboard, then register your company. You can then retrieve your sandbox API keys. Use the sandbox to build and test without affecting real transactions.
Send a `POST` request to `/api/v2/payment` with your API key in the `x-api-key` header. Pass the payment type, amount, currency, and your order reference.
Send your customer a link to pay online for anything, and customize their payment experience according to your brand and business needs.
Register a webhook endpoint to receive real-time notifications when payment status changes, so you never need to poll for updates.
## Key capabilities
Cards, Apple Pay, PayPal, iDEAL, SEPA, Multibanco, Klarna, and more — all through the same API.
Query, capture, refund, adjust, and release payments.
Save cards securely for one-click and recurring payments without storing raw card data.
Built-in 3DS v2 support — Paybyrd handles authentication and redirection automatically.
Get notified instantly when payment status changes with Paybyrd's webhook system.
Accept in-person payments on PAX terminals using the Paybyrd Android Payment SDK.
# Adjust
Source: https://docs.paybyrd.com/manage-payments/payment-lifecycle/adjust
Adjust increases the reserved amount of a pre-authorisation. Use it when the final order amount grows after the initial pre-auth — for example, when a customer adds items or extends a rental period.
You can only adjust an uncaptured pre-authorisation.
## API request
```bash theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/adjust/{transactionId} \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '{"amount": "5.00"}'
```
| Parameter | Location | Description |
| --------------- | ------------ | ------------------------------------------------------ |
| `transactionId` | URL path | ID of the pre-authorised transaction to adjust |
| `amount` | Request body | The **additional** amount to add to the reserved total |
## Response
```json theme={null}
{
"code": "BYRD200",
"description": "Operation successfully completed",
"transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
"amount": "15.00",
"previousAmount": "10.00"
}
```
| Field | Description |
| ---------------- | -------------------------------------------------- |
| `code` | `BYRD200` = success |
| `transactionId` | ID of the adjusted transaction |
| `amount` | Updated total reserved amount after the adjustment |
| `previousAmount` | Reserved amount before the adjustment |
# Capture
Source: https://docs.paybyrd.com/manage-payments/payment-lifecycle/capture
For some payment methods, a second step is required to complete the payment.
In the first step an authorization is made. The shopper's payment details are verified and the funds are reserved.
In the second step the reserved funds are transferred from the shopper to your account.
Payments are captured immediately after authorization by default. For payment methods that support separate authorization and capture, you can also capture the payment later. The reserved amount can be partially or fully captured, depending on the payment method used.
## Capture a payment
The following example captures a transaction and shows the response:
```bash theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/capture/4faa13cd-f6ff-414e-b5bd-b61d1e72e418 \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '{"amount":"10.00"}'
```
```json theme={null}
{
"sourceTransaction": {
"capturedAmount": "10.00",
"remainingAmount": "0.00",
"transactionId": "4faa13cd-f6ff-414e-b5bd-b61d1e72e418",
"amount": "10.00"
},
"code": "BYRD200",
"description": "Operation successfully completed",
"transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
"amount": "10.00"
}
```
See the [full API reference](/api-reference/transactions/capture) for all request parameters and response fields.
# Query Transactions
Source: https://docs.paybyrd.com/manage-payments/payment-lifecycle/query-transactions
You can query a specific transaction to retrieve detailed information about it. This is useful when a Paybyrd webhook is not received or a technical issue prevents your software from receiving a payment response. Without this response, your staff may be unable to verify whether the transaction was processed or what its result was. They may also attempt to cancel or refund the transaction, or inadvertently create a duplicate.
## Query a transaction
Example request and response for the Query transactions endpoint:
```bash Query Transaction Request theme={null}
curl --request GET \
--url https://gateway.paybyrd.com/api/v2/transactions/{transactionId} \
--header 'Accept: application/json' \
--header 'x-api-key: {your_api_key}'
```
```json Query Transaction Response (Success) theme={null}
{
"referencedTransactions":[],
"code":"BYRD200",
"description":"Operation successfully completed",
"currency":"EUR",
"orderRef":"ORDER#3570",
"brand":"VISA",
"operationType":"Payment",
"status":"Success",
"fingerPrint":"fb1714e5-f2a4-40c8-b3e6-7487187bdaab",
"createdDate":"2021-06-08T22:07:37Z",
"transactionDate":"2021-06-08T22:07:37Z",
"capturedDate":"2021-06-08T22:08:06Z",
"maskedCardNumber":"420000******0000",
"initiatedFrom":"HostedForm",
"subscriptionGuid":"476f8d2c-22ee-42a0-b986-0d01b9292c49",
"personId":78,
"index":2,
"externalSessionIdentifier":"f31a836d-42c6-41c7-b0d0-109d64efb133",
"externalTransactionIdentifier":"b1b2cf19-e9fe-4b7c-be1a-a12f0f8899f2",
"externalCustomIdentifier":"8cb922ee-01cd-453d-90b9-b377e4f1d38b",
"transactionId":"8cb922ee-01cd-453d-90b9-b377e4f1c3cb",
"amount":"5.00",
"acquirerEntity": "11854",
"acquirerReference": "999999935"
}
```
***
## Query a transaction by acquirer custom identifier
Example request and response for querying a transaction by acquirer custom identifier:
```bash Query Transaction Request theme={null}
curl --request GET \
--url https://gateway.paybyrd.com/api/v2/transactions?acquirerCustomId=${customIdentifier} \
--header 'Accept: application/json' \
--header 'x-api-key: {your_api_key}'
```
```json Query Transaction Response (Success) theme={null}
[
{
"currency": "EUR",
"acquirer": "SIMULATED",
"brand": "MASTER",
"paymentMethod": "Card",
"operationType": "Payment",
"status": "Success",
"fingerPrint": "f7f76173-f357-4863-bbc3-f5b6204a2769",
"createdDate": "2025-05-12T18:04:38Z",
"transactionDate": "2025-05-12T18:04:38Z",
"capturedDate": "2025-05-12T18:04:41Z",
"maskedCardNumber": "555534******1115",
"authorizationCode": "327161",
"initiatedFrom": "Server",
"subscriptionGuid": "b9852997-0e6a-4542-a9fd-e9ae76967653",
"personId": 10,
"expiresAt": "2025-05-12T18:19:39Z",
"attempt": 0,
"index": 0,
"externalSessionIdentifier": "b7fc1639-6dda-4c20-b618-097ef1e4e842",
"externalTransactionIdentifier": "b15dc08a-277e-4c24-95e4-0ceb10540efd",
"externalCustomIdentifier": "bc0a8270d48b4a3d9f1bf0a4eab365dc",
"acquirerResponseCode": "00",
"acquirerResponseMessage": "Success",
"card": {
"holder": "Jane Jones",
"number": "555534******1115",
"expiresAt": "12/25",
"installments": 1,
"installmentAmount": 2634,
"isPayerTraveling": false,
"countryCode": "QAT"
},
"acceptTokenization": true,
"cardInfoComposition": {
"cardServiceType": "Credit",
"sourceEnvironment": "Online",
"cardCommercialType": "Corporate",
"cardIssueLocation": "NonEea"
},
"transactionId": "bc0a8270-d48b-4a3d-9f1b-f0a4eab365dc",
"amount": "26.34",
"isoAmount": 2634
}
]
```
***
See the [Query transactions API endpoint](/api-reference/transactions/query) for more details.
The **status** field indicates whether the transaction was processed successfully.
See the full list of the possible status at [Transaction Status page](ref:appendix-transaction-status).
# Refund
Source: https://docs.paybyrd.com/manage-payments/payment-lifecycle/refund
To return funds to your shopper, refund the payment.
You can refund either the full captured amount or a part of the captured amount. You can also perform multiple partial refunds, as long as their sum doesn't exceed the captured amount.
Some payment methods do not support partial refunds. To learn if a payment method supports partial refunds, refer to the payment method page such as cards, iDEAL, or Klarna.
You can only refund a payment after it has already been captured.
## Refund a payment
In order to refund a payment, you will need the transaction id from the transaction you want to refund. You can retrieve this identifier in several ways:
* In a server-to-server integration, the `transactionId` field is returned at the root of the create payment response.
* For a Checkout integration, query the order by its `orderId`. The associated transactions are listed under the `Transactions` node, which includes the `transactionId` field.
* If you have notifications configured, Paybyrd sends a notification for each processed payment. Every notification includes the `transactionId` for that event.
* You can also find the `transactionId` in the Paybyrd dashboard for every transaction in the Transacion Detail view.
## API Call
You can find below an example of how to refund a transaction and the generated response:
```bash theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/refund/4faa13cd-f6ff-414e-b5bd-b61d1e72e418 \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '{"amount":"10.00"}'
```
```json theme={null}
{
"sourceTransaction": {
"refundedAmount": "10.00",
"remainingAmount": "0.00",
"transactionId": "4faa13cd-f6ff-414e-b5bd-b61d1e72e418",
"amount": "10.00"
},
"code": "BYRD200",
"description": "Operation successfully completed",
"transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
"amount": "10.00"
}
```
## Handling rejections
Refunds can be declined, and you must handle these cases in your integration. When a refund cannot be processed, Paybyrd responds with code `BYRD205`. For example:
```bash theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/refund/4faa13cd-f6ff-414e-b5bd-b61d1e72e418 \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your_api_key}' \
--data '{"amount":"5.00"}'
```
```json theme={null}
{
"sourceTransaction": {
"refundedAmount": "0.00",
"remainingAmount": "5.00",
"transactionId": "4faa13cd-f6ff-414e-b5bd-b61d1e72e418",
"amount": "5.00"
},
"code": "BYRD205",
"description": "Operation rejected",
"transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
"amount": "5.00"
}
```
When you receive `BYRD205`, the refund was declined by the bank. Declines can be temporary, so you can retry the request later. For more information about a declined refund, contact support.
## Handling errors
When the Paybyrd API encounters an error, you receive this response structure:
```json Payment already refunded theme={null}
{
"isError": true,
"code": "BYRD230",
"description": "The refund amount exceeds the remaining balance of the original payment"
}
```
```json Generic error theme={null}
{
"isError": true,
"code": "BYRD999",
"description": "Operation failed. This code is related to unhandled errors."
}
```
You can find the full list of response codes and their descriptions in the [Response code reference](/api-reference/api-code-reference).
# Release
Source: https://docs.paybyrd.com/manage-payments/payment-lifecycle/release
The release operation releases an amount reserved through a pre-authorization.
By default, pre-authorizations that are not captured or released expire after 30 days.
You can only release an authorization or pre authorization that was not captured.
## Release a payment
The following example releases a transaction and shows the response:
```bash theme={null}
curl --request POST \
--url https://gateway.paybyrd.com/api/v2/release/transactionId/4faa13cd-f6ff-414e-b5bd-b61d1e72e418 \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"amount":"10.00"}'
```
```json theme={null}
{
"sourceTransaction": {
"releasedAmount": "10.00",
"remainingAmount": "0.00",
"transactionId": "4faa13cd-f6ff-414e-b5bd-b61d1e72e418",
"amount": "10.00"
},
"code": "BYRD200",
"description": "Operation successfully completed",
"transactionId": "c16ce479-319d-4e7b-a966-7735c34b2cc5",
"amount": "10.00"
}
```
See the [full API reference](/api-reference/transactions/release) for all request parameters and response fields.
# Settlement files (legacy)
Source: https://docs.paybyrd.com/manage-payments/settlements/legacy-settlement-files
This endpoint is deprecated. Paybyrd continues to support implementations using this endpoint for an indefinite period. However, we recommend using the [FinanceHub Settlement files](/manage-payments/settlements/settlement-files) endpoint instead.
Settlement files are CSV reports generated by Paybyrd that summarize the financial transactions included in a given settlement period. Each file records the amounts, fees, and references needed to reconcile payouts.
Settlement files serve as official records of financial transactions for a given period. They support reconciliation, compliance monitoring, and financial accountability.
You access settlement files through the Settlement API, which returns a list of files for a given time period.
## Authentication
The API authentication needs to be done with a `x-api-key` header, and it will be provided by Paybyrd.
## Retrieving the settlement file
To retrieve the list of files for a period, send a `GET` request to:
`https://settlements.paybyrd.com/api/v1/files?createdFrom={startDateTime}&createdTo={endDateTime}`
## Response content structure
Each item in the response list has the following structure:
| Field | Type | Description |
| --------- | ----------------- | ------------------------------------------------------------------- |
| groupId | String (UUID) | Customer-defined group or organization hierarchy. |
| id | String (UUID) | Unique identifier of the settlement file. |
| checksum | String | MD5 hash of the file contents, represented as a hexadecimal string. |
| createdAt | String (ISO 8601) | UTC timestamp when the file was generated. |
| url | String (URL) | URL to download the settlement file. |
## Usage recommendations
Paybyrd normally generates one file per day. However, there may be situations where more than one file is generated for the same day, in which case these files are complementary and must be fully processed to obtain all settlement information.
To receive settlements consistently on a daily basis, make requests with sequential date periods. For example, an automated system could make one request per day, using the `createdTo` value from the previous request as the `createdFrom` value for the next.
## Retrieving a list of settlement files for a specific day
To retrieve files for a specific day, set the period to cover the full day: from `00:00:00` to `23:59:59`, as shown in the example below.
```bash theme={null}
curl --location --request GET 'https://settlements.paybyrd.com/api/v1/files?createdFrom=2022-11-18T00:00:00&createdTo=2022-11-18T23:59:59' \
--header 'x-api-key: '
```
```json theme={null}
// Success (HTTP Status Code: 200)
{
"data": [
{
"checksum": "8a5d4f748b9795d4e5b562ef9ed9f12dc5c2444cb7852ce9f29b8c7a97dfa18c",
"createdAt": "2022-12-28T17:04:46Z",
"groupId": "07b52763-6268-4ad5-82de-2b6db4bc0aad",
"id": "e8be2832-83fe-46a6-88ce-eb7069305209",
"url": "https://paybyrd-settlements.blob.core.windows.net/files/07b52763-6268-4ad5-82de-2b6db4bc0aad/2022-11-18T16_49_58Z_PaybyrdSettlement.csv?..."
}
]
}
```
```json theme={null}
// Not Found (HTTP Status Code: 404)
{
"error": {
"code": "BYRD901",
"message": "Settlement file not found."
}
}
```
## Retrieving a list of settlement files (period filtering)
When filtering by period, days with no settlement file are omitted from the results. Use `from` and `to` as query parameters for period filtering.
```bash theme={null}
curl --location --request GET 'https://settlements.paybyrd.com/api/v1/files?from=2022-12-13T00:00:00&to=2022-12-16T23:59:59' \
--header 'x-api-key: '
```
```json theme={null}
// Success (HTTP Status Code: 200)
{
"data": [
{
"groupId": "07b52763-6268-4ad5-82de-2b6db4bc0aad",
"id": "059dc3a0-b8cb-40b3-8bbf-e76b7328e634",
"checksum": "302c4ad6e635ef0c6a289be55ba86662734c7e6fe04e48fceb4042bc1b8b702e",
"createdAt": "2022-12-13T11:23:58Z",
"url": "https://paybyrd-settlements.blob.core.windows.net/files/07b52763-6268-4ad5-82de-2b6db4bc0aad/2022-12-13T11_29_58Z_PaybyrdSettlement.csv?..."
},
{
"groupId": "07b52763-6268-4ad5-82de-2b6db4bc0aad",
"id": "8d620102-0ff0-4f5c-aff4-44905072da2b",
"checksum": "8a5d4f748b9795d4e5b562ef9ed9f12dc5c2444cb7852ce9f29b8c7a97dfa18c",
"createdAt": "2022-12-14T17:55:10Z",
"url": "https://paybyrd-settlements.blob.core.windows.net/files/07b52763-6268-4ad5-82de-2b6db4bc0aad/2022-12-14T17_55_10Z_PaybyrdSettlement.csv?..."
},
{
"groupId": "07b52763-6268-4ad5-82de-2b6db4bc0aad",
"id": "71c2088c-ad9b-4cea-abe7-1f2396f935ed",
"checksum": "604b0f937855d941df7b19ef51c42575572ead9ca2ee399eb17d2e3c1fc80bf9",
"createdAt": "2022-12-16T19:12:55Z",
"url": "https://paybyrd-settlements.blob.core.windows.net/files/07b52763-6268-4ad5-82de-2b6db4bc0aad/2022-12-16T19_12_16Z_PaybyrdSettlement.csv?..."
}
]
}
```
```json theme={null}
// Not Found (HTTP Status Code: 404)
{
"error": {
"code": "BYRD901",
"message": "Settlement files not found."
}
}
```
```json theme={null}
// Bad Request (HTTP Status Code: 400)
{
"error": {
"code": "BYRD900",
"message": "Invalid settlement filter date (createdAt)."
}
}
```
```json theme={null}
// Unexpected errors (HTTP Status Code: 500)
{
"error": {
"code": "BYRD999",
"message": "Internal server error."
}
}
```
## File specification
The file is created in CSV format using `|` (pipe) as a separator. The filename follows this pattern: `yyyy-MM-ddThh-mm-ssZ-PaybyrdSettlement.csv`
Example: `2022-11-18T16-49-58Z-PaybyrdSettlement.csv`
## Billing events
Depending on the contractual agreement, acquirers can charge billing events at the settlement. In those cases, a special line is sent in the settlement file to inform the merchant about charges made at the payout. These rows have `SETTLEMENT_TYPE` set to `"B"` and only the following fields are populated:
`PAYMENT_REFERENCE`, `GROUP_ID`, `IBAN`, `SWIFT`, `SETTLEMENT_AMOUNT`, `SETTLEMENT_TOTAL_FEE_AMOUNT` (always zero), `SETTLEMENT_CURRENCY`, `ACQUIRER_PERCENTAGE_FEE` (always zero), `ACQUIRER_FEE` (always zero), `SETTLEMENT_TYPE`, `BILLING_DESCRIPTION`
## Field specifications
| Field name | Type | Format | Description |
| ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PAYMENT\_REFERENCE | String(12) | Alphanumeric | Unique number assigned to every "Fund Event" (ACH Payment/Withdrawal, Wire Transfer, Invoice) |
| ACQUIRER\_TRANSACTION\_REFERENCE | String(72) | \*\*\* | The identifier of the transaction in the Acquirer. |
| ACQUIRER\_UNIQUE\_TRANSACTION\_REFERENCE | String(72) | \*\*\* | The identifier of the transaction lifetime in the Acquirer. If a transaction has an event fund, this ID will always be the same as the ID of the transaction that was processed. This can be translated by the Acquirer common ID, like ARN. |
| PAYBYRD\_TRANSACTION\_REFERENCE | String(36) | \*\*\* | The identifier of the transaction at Paybyrd. |
| STORE\_LEGAL\_NAME | String(200) | \*\*\* | Doing Business As (DBA) Name |
| GROUP\_ID | Long | Numeric | Customer-defined group or organization hierarchy assigned with DBA/MID locations |
| MERCHANT\_ID | Long | Numeric | Customer-defined subgroup or organization hierarchy assigned with DBA/MID locations |
| STORE\_ID | Long | Numeric | Customer Facing Merchant Identification Number |
| ORDER\_ID | String(36) | GUID | A unique reference number generated by Paybyrd to initiate transactions by HPP |
| IBAN | String(34) | \*\*\* | International Bank Account Number of the Customer to which the Fund Event is directed |
| SWIFT | String(11) | \*\*\* | SWIFT (Society for Worldwide Interbank Financial Telecommunications) code of the bank of the Customer to which the Fund Event is directed |
| SETTLEMENT\_AMOUNT | Long | ISO amount | Transaction amount in the settlement currency |
| SETTLEMENT\_TOTAL\_FEE\_AMOUNT | Long | Precision 6 digits | Total Commission amount |
| TRANSACTION\_TYPE | Char(2) | "P" = Payment, "PA" = Pre-Auth, "R" = Refund, "A" = Adjustment, "C" = Chargeback, "CR" = Chargeback reversal | Detailed record tag identifying |
| SETTLEMENT\_CURRENCY | Char(3) | \*\*\* | The ISO currency assigned to the Fund Event |
| SETTLEMENT\_DATE | Date | yyyy-MM-dd | The calendar day the transaction was batched and electronically deposited |
| SETTLEMENT\_EXCHANGE\_RATE | Long | Precision 2 digits | Exchange Rate |
| SETTLEMENT\_PAYMENT\_DATE | Date | yyyy-MM-dd | Date the Acquirer system created and transmitted the Fund Event |
| INTERCHANGE\_AMOUNT | Long | Precision 6 digits | Interchange amount |
| TRANSACTION\_CARD\_BRAND | String(15) | Visa, Maestro, Mastercard, DinersClub, UnionPay | High-level scheme tag |
| TRANSACTION\_AUTHORIZATION\_CODE | Int | \*\*\* | The six-digit "APPROVED" reference associated with the purchase transaction |
| TRANSACTION\_CURRENCY | String(3) | \*\*\* | Cardholder Currency Code |
| TRANSACTION\_AMOUNT | Long | ISO amount | The transaction amount |
| TRANSACTION\_DATE | DateTime | yyyy-MM-dd hh:mm:ss | The calendar date time the transaction was processed in UTC |
| TRANSACTION\_CARD\_TYPE | String(20) | Consumer, Commercial | Card scheme defined type of card used in the transaction payment record |
| TRANSACTION\_MASKED\_CARD\_NUMBER | String(19) | 679128\*\*\*\*\*4259 | The masked number of the cardholder account. This field length can vary by 16 to 19 (for Amex cards). |
| TRANSACTION\_CARD\_USAGE | String(25) | Credit, Debit | The payment method of the transaction |
| ACQUIRER\_PERCENTAGE\_FEE | Long | Precision 3 digits | Acquirer fee (in %) |
| ACQUIRER\_FEE | Long | Precision 6 digits | Acquirer fee (in amount) |
| CHARGEBACK\_CONTROL\_NUMBER | String(50) | \*\*\* | The "Case ID" of the cardholder's chargeback action transaction |
| ORDER\_REF | String(100) | \*\*\* | The Order Reference |
| TICKET\_NUMBER | String(100) | \*\*\* | Flight Ticket Number |
| SCHEME\_FEES | Long | Precision 6 digits | Card scheme fees |
| TRANSACTION\_MARKET\_ID | String(36) | \*\*\* | An identification of the Market sent by the client when the Transaction is processed |
| TRANSACTION\_APPLICATION\_ID | String(36) | Alphanumeric | The application Id that generated the transaction |
| TRANSACTION\_INITIATED\_FROM | String(4) | Alphanumeric | The source font of the transaction (ECOM / POS) |
| AIRPORT\_CODE | String(3) | Alphanumeric | The Airport Code where the POS is installed |
| TRANSACTION\_POS\_SERIAL\_NUMBER | String(20) | Alphanumeric | The Serial Number of POS that processes the Transaction |
| SETTLEMENT\_TYPE | Char(1) | "T" = Transaction, "B" = Billing | Specifies the type of the settlement |
| BILLING\_DESCRIPTION | String(100) | \*\*\* | A value containing a description of the charge of the billing made at the Payout moment. This field is filled only when SETTLEMENT\_TYPE is set as "B". |
# Refunds before clearing files
Source: https://docs.paybyrd.com/manage-payments/settlements/refunds-before-clearing
This endpoint is deprecated. Paybyrd continues to support implementations using this endpoint for an indefinite period. However, we recommend using the [FinanceHub Settlement files](/manage-payments/settlements/settlement-files) endpoint instead.
The Refunds Before Clearing file supplements the settlement file. It records transactions refunded before the acquirer's clearing process — transactions that did not incur fees or other charges.
## Authentication
Authenticate requests using an `x-api-key` header. You can find your API key in the [API Keys](https://backoffice.paybyrd.com/#/apikeys) page of the dashboard.
## Retrieving the refunds before clearing file
To retrieve the list of files for a period, send a `GET` request to:
`https://settlements.paybyrd.com/api/v1/authorization-files?createdFrom={startDateTime}&createdTo={endDateTime}`
## Response content structure
| Field | Type | Description |
| --------- | ----------------- | ------------------------------------------------------------------- |
| groupId | String (UUID) | Customer-defined group or organization hierarchy. |
| id | String (UUID) | Unique identifier of the file. |
| checksum | String | MD5 hash of the file contents, represented as a hexadecimal string. |
| createdAt | String (ISO 8601) | UTC timestamp when the file was generated. |
| url | String (URL) | URL to download the file. |
## Usage recommendations
Paybyrd normally generates one file per day. However, there may be situations where more than one file is generated for the same day, in which case these files are complementary and must be fully processed to obtain all refunds before clearing information.
To receive all settlements consistently each day, make requests with sequential date periods. For example, an automated system could make one request per day, using the `createdTo` value from the previous request as the `createdFrom` value for the next.
## Retrieving a list of refunds before clearing files for a specific day
To retrieve files for a specific day, set the period from 00:00 to 23:59, as in the example below.
```bash theme={null}
curl --location --request GET 'https://settlements.paybyrd.com/api/v1/authorization-files?createdFrom=2023-11-27T00:00:00&createdTo=2023-11-27T23:59:59' \
--header 'x-api-key: '
```
```json theme={null}
// Success (HTTP Status Code: 200)
{
"data": [
{
"checksum": "d41d8cd98f00b204e9800998ecf8427e",
"createdAt": "2023-11-27T01:00:00Z",
"groupId": "07b52763-6268-4ad5-82de-2b6db4bc0aad",
"id": "34a815e7-40b3-4936-b689-70984ec7ad4e",
"url": "https://paybyrd-settlements.blob.core.windows.net/authorizations-paybyrd/2678/2023-11-27T01-00-00-8192727%2B0-PaybyrdAuthorizations.csv?..."
}
]
}
```
```json theme={null}
// Not Found (HTTP Status Code: 404)
{
"error": {
"code": "BYRD901",
"message": "Settlement file not found."
}
}
```
## Retrieving a list of refunds before clearing files (period filtering)
When filtering by period, days with no file are omitted from the results. Use `from` and `to` as query parameters and the `authorizations-paybyrd` endpoint for period filtering.
```bash theme={null}
curl --location --request GET 'https://settlements.paybyrd.com/api/v1/authorizations-paybyrd?from=2023-11-01T00:00:00&to=2023-11-27T23:59:59' \
--header 'x-api-key: '
```
```json theme={null}
// Not Found (HTTP Status Code: 404)
{
"error": {
"code": "BYRD901",
"message": "Settlement file not found."
}
}
```
```json theme={null}
// Bad Request (HTTP Status Code: 400)
{
"error": {
"code": "BYRD900",
"message": "Invalid settlement filter date (createdAt)."
}
}
```
```json theme={null}
// Unexpected errors (HTTP Status Code: 500)
{
"error": {
"code": "BYRD999",
"message": "Internal server error."
}
}
```
## File specification
The file is created in CSV format using `|` (pipe) as a separator. The filename follows this pattern: `yyyy-MM-ddThh-mm-ssZ-PaybyrdSettlement.csv`
Example: `2022-11-18T16-49-58Z-PaybyrdSettlement.csv`
## Field specifications
| Field name | Type | Format | Description |
| --------------------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| ACQUIRER\_TRANSACTION\_REFERENCE | String(72) | \*\*\* | The identifier of the transaction in the Acquirer |
| PAYBYRD\_TRANSACTION\_REFERENCE | String(36) | \*\*\* | The identifier of the transaction at Paybyrd |
| STORE\_LEGAL\_NAME | String(200) | \*\*\* | Doing Business As (DBA) Name |
| GROUP\_ID | Long | Numeric | Customer-defined group or organization hierarchy assigned with DBA/MID locations |
| MERCHANT\_ID | Long | Numeric | Customer-defined subgroup or organization hierarchy assigned with DBA/MID locations |
| STORE\_ID | Long | Numeric | Customer Facing Merchant Identification Number |
| ORDER\_ID | String(36) | GUID | A unique reference number generated by Paybyrd to initiate transactions by HPP |
| TRANSACTION\_TYPE | Char(1) | "P" = Payment, "PA" = PreAuth, "R" = Refund | Detailed record tag identifying |
| TRANSACTION\_CARD\_BRAND | String(15) | Visa, Maestro, Mastercard, DinersClub, UnionPay | High-level scheme tag |
| TRANSACTION\_AUTHORIZATION\_CODE | Int | \*\*\* | The six-digit "APPROVED" reference associated with the purchase transaction |
| TRANSACTION\_CURRENCY | String(3) | \*\*\* | Cardholder Currency Code |
| TRANSACTION\_AMOUNT | Long | ISO amount | The transaction amount |
| TRANSACTION\_DATE | DateTime | yyyy-MM-dd hh:mm:ss | The calendar date time the transaction was processed in UTC |
| TRANSACTION\_CARD\_TYPE | String(20) | Consumer, Commercial | Card scheme defined type of card used in the transaction payment record |
| TRANSACTION\_MASKED\_CARD\_NUMBER | String(19) | 679128\*\*\*\*\*4259 | The masked number of the cardholder account. Field length can vary from 16 to 19 digits (Amex cards). |
| TRANSACTION\_CARD\_USAGE | String(25) | Credit, Debit | The payment method of the transaction |
| ORDER\_REF | String(100) | \*\*\* | The Order Reference |
| TICKET\_NUMBER | String(100) | \*\*\* | Flight Ticket Number |
| TRANSACTION\_MARKET\_ID | String(36) | \*\*\* | An identification of the Market sent by the client when the Transaction is processed |
| TRANSACTION\_APPLICATION\_ID | String(36) | Alphanumeric | The application Id that generated the transaction |
| TRANSACTION\_INITIATED\_FROM | String(4) | Alphanumeric | The source font of the transaction (ECOM / POS) |
| AIRPORT\_CODE | String(3) | Alphanumeric | The Airport Code where the POS is installed |
| TRANSACTION\_POS\_SERIAL\_NUMBER | String(20) | Alphanumeric | The Serial Number of POS that process the Transaction |
# Settlement files
Source: https://docs.paybyrd.com/manage-payments/settlements/settlement-files
Settlement files are CSV reports generated by Paybyrd that summarize the financial transactions included in a given settlement period. Each file records the amounts, fees, and references needed to reconcile payouts.
Settlement files serve as official records of financial transactions for a given period. They support reconciliation, compliance monitoring, and financial accountability.
You access settlement files through the Settlement API, which returns a list of files for a given time period.
## Authentication
The API authentication needs to be done with a `x-api-key` header, and it will be provided by Paybyrd.
## Retrieving the settlement file
To retrieve the list of files for a period, send a `GET` request to:
`https://financehub.paybyrd.com/api/v1/SettlementFiles?createdFrom={startDateTime}&createdTo={endDateTime}`
Optional query parameters: `merchantId` and `storeId` to filter results by merchant or store.
## Response content structure
Each item in the response list has the following structure:
| Field | Type | Description |
| ---------- | ----------------- | ------------------------------------------------------------------- |
| checksum | String | MD5 hash of the file contents, represented as a hexadecimal string. |
| createdAt | String (ISO 8601) | Timestamp when the file was generated. |
| groupId | Long | Customer-defined group or organization hierarchy. |
| merchantId | Long | Customer-defined merchant identifier. Optional. |
| storeId | Long | Customer-facing merchant identification number. Optional. |
| id | String (UUID) | Unique identifier of the settlement file. |
| url | String (URL) | URL to download the settlement file. |
## Usage recommendations
Paybyrd normally generates one file per day. However, there may be situations where more than one file is generated for the same day, in which case these files are complementary and must be fully processed to obtain all settlement information.
To receive settlements consistently on a daily basis, make requests with sequential date periods. For example, an automated system could make one request per day, using the `createdTo` value from the previous request as the `createdFrom` value for the next.
## Retrieving a list of settlement files for a specific day
To retrieve files for a specific day, set the period to cover the full day: from `00:00:00` to `23:59:59`, as shown in the example below.
```bash theme={null}
curl --location --request GET 'https://financehub.paybyrd.com/api/v1/SettlementFiles?createdFrom=2022-11-18T00:00:00&createdTo=2022-11-18T23:59:59' \
--header 'x-api-key: {your_api_key}'
```
```json theme={null}
// Success (HTTP Status Code: 200)
{
"data": [
{
"checksum": "ba421754061547e5d80153d3d2923be4",
"createdAt": "2026-05-26T13:11:02.390069-03:00",
"groupId": 1,
"merchantId": 1,
"id": "59188227-0811-4e30-8c57-b8dff2ab07e9",
"url": "https://financehubstoragestg.blob.core.windows.net/settlements-paybyrd/57/87/2026-05-26T16-11-00-4990180%2B0-PaybyrdSettlement.csv?sv=2025-07-05&se=2026-06-17T09%3A53%3A19Z&sr=b&sp=r&sig=MGQ7rFFMvIskJtcsefdvCh6lYnp6lqIrTbzN2n3rB48%3D"
}
]
}
```
```json theme={null}
// Not Found (HTTP Status Code: 404)
{
"data": {
"problemDetails": {
"type": "ApplicationNotFoundFail",
"title": "Settlement file not found with the specified period.",
"status": 404,
"instance": "not_found",
"extensions": {}
},
"contentType": "application/problem+json",
"statusCode": 404
}
}
```
## Retrieving a list of settlement files (period filtering)
When filtering by period, days with no settlement file are omitted from the results.
```bash theme={null}
curl --location --request GET 'https://financehub.paybyrd.com/api/v1/SettlementFiles?createdFrom=2022-11-18T00:00:00&createdTo=2022-11-25T23:59:59' \
--header 'x-api-key: {your_api_key}'
```
```json theme={null}
// Success (HTTP Status Code: 200)
{
"data": [
{
"checksum": "ba421754061547e5d80153d3d2923be4",
"createdAt": "2026-05-26T13:11:02.390069-03:00",
"groupId": 1,
"merchantId": 1,
"id": "59188227-0811-4e30-8c57-b8dff2ab07e9",
"url": "https://financehubstoragestg.blob.core.windows.net/settlements-paybyrd/57/87/2026-05-26T16-11-00-4990180%2B0-PaybyrdSettlement.csv?sv=2025-07-05&se=2026-06-17T09%3A53%3A19Z&sr=b&sp=r&sig=MGQ7rFFMvIskJtcsefdvCh6lYnp6lqIrTbzN2n3rB48%3D"
},
{
"checksum": "ba421754061547e5d80153d3d2923be4",
"createdAt": "2026-05-26T13:11:02.390069-03:00",
"groupId": 1,
"merchantId": 1,
"id": "59188227-0811-4e30-8c57-b8dff2ab07e9",
"url": "https://financehubstoragestg.blob.core.windows.net/settlements-paybyrd/57/87/2026-05-26T16-11-00-4990180%2B0-PaybyrdSettlement.csv?sv=2025-07-05&se=2026-06-17T09%3A53%3A19Z&sr=b&sp=r&sig=MGQ7rFFMvIskJtcsefdvCh6lYnp6lqIrTbzN2n3rB48%3D"
}
]
}
```
```json theme={null}
// Not Found (HTTP Status Code: 404)
{
"data": {
"problemDetails": {
"type": "ApplicationNotFoundFail",
"title": "Settlement file not found with the specified period.",
"status": 404,
"instance": "not_found",
"extensions": {}
},
"contentType": "application/problem+json",
"statusCode": 404
}
}
```
```json theme={null}
// Bad Request (HTTP Status Code: 400)
{
"data": {
"problemDetails": {
"type": "ApplicationBadRequestFail",
"title": "Bad request",
"status": 400,
"instance": "bad_request",
"extensions": {}
},
"contentType": "application/problem+json",
"statusCode": 400
}
}
```
```json theme={null}
// Unexpected errors (HTTP Status Code: 500)
{
"data": {
"problemDetails": {
"type": "ApplicationServerErrorFail",
"title": "Internal server error",
"status": 500,
"instance": "server_error",
"extensions": {}
},
"contentType": "application/problem+json",
"statusCode": 500
}
}
```
## File specification
The file is created in CSV format using `|` (pipe) as a separator. The filename follows this pattern: `yyyy-MM-ddThh-mm-ssZ-PaybyrdSettlement.csv`
Example: `2022-11-18T16-49-58Z-PaybyrdSettlement.csv`
## Field specifications
| Field name | Type | Format | Description |
| ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PAYMENT\_REFERENCE | String(12) | Alphanumeric | Unique number assigned to every "Fund Event" (ACH Payment/Withdrawal, Wire Transfer, Invoice) |
| ACQUIRER\_TRANSACTION\_REFERENCE | String(72) | \*\*\* | The identifier of the transaction in the Acquirer |
| ACQUIRER\_UNIQUE\_TRANSACTION\_REFERENCE | String(72) | \*\*\* | The identifier of the transaction lifetime in the Acquirer. If a transaction has an event fund, this ID will always be the same as the ID of the transaction that was processed. This can be translated by the Acquirer common ID, like ARN. |
| PAYBYRD\_TRANSACTION\_REFERENCE | String(36) | \*\*\* | The identifier of the transaction at Paybyrd |
| STORE\_LEGAL\_NAME | String(200) | \*\*\* | Doing Business As (DBA) Name |
| GROUP\_ID | Long | Numeric | Customer-defined group or organization hierarchy assigned with DBA/MID locations |
| MERCHANT\_ID | Long | Numeric | Customer-defined subgroup or organization hierarchy assigned with DBA/MID locations |
| STORE\_ID | Long | Numeric | Customer Facing Merchant Identification Number |
| ORDER\_ID | String(36) | GUID | A unique reference number generated by Paybyrd to initiate transactions by HPP |
| IBAN | String(34) | \*\*\* | International Bank Account Number of the Customer to which the Fund Event is directed |
| SWIFT | String(11) | \*\*\* | SWIFT (Society for Worldwide Interbank Financial Telecommunications) code of the bank of the Customer to which the Fund Event is directed |
| SETTLEMENT\_AMOUNT | Long | ISO amount | Transaction amount in the settlement currency |
| TRANSACTION\_TYPE | Char(2) | "P" = Payment; "PA" = Pre-Auth; "R" = Refund; "A" = Adjustment; "C" = Chargeback; "CR" = Chargeback reversal | Detailed record tag identifying |
| SETTLEMENT\_CURRENCY | Char(3) | \*\*\* | The ISO currency assigned to the Fund Event |
| SETTLEMENT\_DATE | Date | yyyy-MM-dd | The calendar day the transaction was batched and electronically deposited |
| SETTLEMENT\_EXCHANGE\_RATE | Long | Precision 2 digits | Exchange Rate |
| SETTLEMENT\_PAYMENT\_DATE | Date | yyyy-MM-dd | Date the Acquirer system created and transmitted the Fund Event |
| TRANSACTION\_CARD\_BRAND | String(15) | Visa, Maestro, Mastercard, DinersClub, UnionPay | High-level scheme tag |
| TRANSACTION\_AUTHORIZATION\_CODE | Int | \*\*\* | The six-digit "APPROVED" reference associated with the purchase transaction |
| TRANSACTION\_CURRENCY | String(3) | \*\*\* | Cardholder Currency Code |
| TRANSACTION\_AMOUNT | Long | ISO amount | The transaction amount |
| TRANSACTION\_DATE | DateTime | yyyy-MM-dd hh:mm:ss | The calendar date time the transaction was processed in UTC |
| TRANSACTION\_CARD\_TYPE | String(20) | Consumer, Commercial | Card scheme defined type of card used in the transaction payment record |
| TRANSACTION\_MASKED\_CARD\_NUMBER | String(19) | 679128\*\*\*\*\*4259 | The masked number of the cardholder account. Field length can vary from 16 to 19 digits (Amex cards). |
| TRANSACTION\_CARD\_USAGE | String(25) | Credit, Debit | The payment method of the transaction |
| CHARGEBACK\_CONTROL\_NUMBER | String(50) | \*\*\* | The "Case ID" of the cardholder's chargeback action transaction |
| ORDER\_REF | String(100) | \*\*\* | The Order Reference |
| TICKET\_NUMBER | String(100) | \*\*\* | Flight Ticket Number |
| TRANSACTION\_MARKET\_ID | String(36) | \*\*\* | An identification of the Market sent by the client when the Transaction is processed |
| TRANSACTION\_APPLICATION\_ID | String(36) | Alphanumeric | The application ID that generated the transaction |
| TRANSACTION\_INITIATED\_FROM | String(4) | Alphanumeric | The source of the transaction (ECOM / POS) |
| AIRPORT\_CODE | String(3) | Alphanumeric | The Airport Code where the POS is installed |
| TRANSACTION\_POS\_SERIAL\_NUMBER | String(20) | Alphanumeric | The Serial Number of the POS that processed the Transaction |