Create Payment

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

The following example shows the same request using the iDeal payment method:

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

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.

Accept Payments

Manage Payments

Starting with the payments API

Understanding the API

​Starting with the payments API

​Understanding the API

Starting with the payments API

Understanding the API