Create Payment

The payments API offers you a set of different payment methods to facilitate the checkout experience. All the complexity is abstracted by our services, which allows you to easy integrate and start to accept any kind of payments.

Starting with the payments API

All the payment requests should be addressed to the endpoint /api/v2/payment. No matter which payment method you are using, they all follow the same standards. See below an example of how to make a simple card payment request to our API:

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_HERE}}' \
  --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"
  }
}'

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

Now compare with a request to make a new payment with the iDeal payment method:

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_HERE}}' \
  --data '
{      
  "type":"OnlineTransfer",
  "amount": "8.15",
  "currency": "EUR",
  "orderRef": "ABC12345",
  "brand": "ideal",      
  "bankIdentifierCode": "INGBNL2A",
  "redirectUrl": "https://your-shop-url?orderRef=ABC12345"
}'

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

Even that these payment methods are completely different from each other, the requests and responses are very similar. This allows you to connect with all payment methods in a very simple way.

Understanding the API

The key to have a successful integration is to comprehend the base structure of our API. Next you will find the description of the most important fields that are common to almost all requests you will make to create a payment.

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	It represents the merchant reference for the payment. You can use this information to identify the transaction on Paybyrd's dashboard ou even do the reconciliation on your side.
RedirectUrl	Most of the payments are executed in two steps: 1 - Payment initialisation 2 - Payment completion RedirectUrl indicates where the shopper will be redirected after the second step. Here is an example: 1st step: Creation of a card payment. 2nd step: 3D Secure V2 authentication Once the shopper authenticates on the second step, the payment will be completed and he will be redirected to the Url defined in this field. Paybyrd will concat the transactionId as a query string. This allows you to query the transaction status in the end of the process.

📘
Info
The RedirectUrl can be also configured directly into your subscription. In that case it wouldn't be necessary to send us in every request.

Starting with the payments API

Understanding the API

📘Info

📘
Info