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:
# Card Request
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"
}
}'
// Card Response
{
"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"
}
# iDeal Request
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"
}'
// iDeal Response
{
"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"
}
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.
