Skip to main content
POST
/
api
/
v2
/
orders
curl --request POST \
  --url https://gateway.paybyrd.com/api/v2/orders \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "isoAmount": 5000,
  "currency": "EUR",
  "orderRef": "ABC123456",
  "orderOptions": {
    "redirectUrl": "https://your-site-url/payment-finished",
    "culture": "en-US",
    "checkoutVersion": 2
  }
}
'
{
  "orderId": "63a8a157-81c9-46ea-84b4-2bef6daad3fa",
  "orderDate": "2021-08-24T17:45:27Z",
  "expiresAt": "2021-08-25T17:45:27Z",
  "checkoutUrl": "https://chk.paybyrd.com/chk_a321as123a",
  "checkoutKey": "eyJPcmRlcklkIjoiMzFhMDYzMmItODcxMy00NjIwLThiZjItMDdiN2UyZTk5MTRjIiwiT3JkZXJSZWYiOiI0MTAxMjA3MTU0IiwiUGVyc29uSWQiOjEwLCJMaXZlIjpmYWxzZSwiRW50aXR5SWQiOiIzMWEwNjMyYi04NzEzLTQ2MjAtOGJmMi0wN2I3ZTJlOTkxNGMiLCJBbW91bnQiOiI1MC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0=",
  "status": "created",
  "isoAmount": 50,
  "currency": "EUR",
  "orderRef": "ABC123456",
  "shopper": {
    "shopperId": "676b5023-9624-4d19-bdd2-c61b1be803b7",
    "firstName": "JHOSH",
    "lastName": "JONES",
    "email": "jhoshjs@dominio.com",
    "phoneCountryCode": 351,
    "phoneNumber": "123123123",
    "ip": "111.111.111.111"
  },
  "orderOptions": {
    "redirectUrl": "https://your-site-url/payment-finished",
    "culture": "en-US",
    "checkoutVersion": 2,
    "expiresIn": "00:15:00"
  },
  "paymentOptions": {
    "maxAttempts": 1,
    "sessionExpiresIn": "00:10:00",
    "allowedPaymentMethods": [
      "CARD",
      "SIBS_MULTIBANCO",
      "SEPA",
      "IDEAL",
      "MBWAY"
    ],
    "cardOptions": {
      "isPreAuth": false
    },
    "tokenOptions": {
      "customReference": "ABC123456",
      "tokenizationIsRequired": false,
      "tokenizationMethod": "cardOnFile"
    }
  },
  "code": "BYRD200",
  "description": "Operation successfully completed"
}

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
isoAmount
integer<int64>
required

Total amount for this transaction in ISO format, with the following pattern "2500" (to express 25.00)

​
currency
string
required

Valid ISO-4217 alpha code e.g EUR

Example:

"EUR"

​
orderRef
string
required

Merchant reference for this order

Example:

"ABC123456"

​
shopper
object
​
ShoppingCart
object[]
​
orderOptions
object

Defines settings for this order

​
paymentOptions
object

Defines settings for payment.

​
metadata
object

Metadata allows you to pass any data to Paybyrd which will be returned in the order query and also sent in the status changed notifications.

Example:
{ "key1": 1, "key2": "value" }

Response

201 - application/json

201

​
isoAmount
integer<int64>
required

Total amount for this transaction in ISO format, with the following pattern "2500" (to express 25.00)

​
currency
string
required

Valid ISO-4217 alpha code e.g EUR

Example:

"EUR"

​
orderRef
string
required

Merchant reference for this order

Example:

"ABC123456"

​
orderId
string<guid>
read-only

This field contains the unique identifier that represents the order.

Example:

"e901d7fa-a41a-4c93-bc53-7a08cd72aff4"

​
orderDate
string
read-only

Order creation date in UTC

Example:

"2021-05-31T22:04:31Z"

​
expiresAt
string
read-only

Order expiration date in UTC, which is the sum of 'sessionExpiresIn' with 'expiresIn' parameters.

Example:

"2021-05-31T22:04:31Z"

​
status
enum<string>
read-only

Represents the status of the order. Created - Order has no payments associated to it or all payment attempts have failed. Pending - Order has a payment associated to it which is in progress but not concluded. Paid - Order has a payment associated to it with final status 'Success'. Canceled - This status can occur by system routines, shopper action by clicking on 'cancel payment' button in the hosted page or by calling the order cancel endpoint. Expired - This status occurs by system routines that checks for payment abandonment or in case an expiration date is sent in the create order request. Refunded - In case a successful payment is refunded, its order will have the 'Refunded' status.

Available options:
created,
paid,
pending,
refunded,
canceled,
expired
Example:

"created"

​
checkoutUrl
string
read-only

The checkoutUrl is the direct link to Paybyrd Checkout. You can use it in your ecommerce to display the payment page to the shopper.

Example:

"https://chk.paybyrd.com/chk_fG3F6muPB"

​
shopper
object
​
ShoppingCart
object[]
​
orderOptions
object

Defines settings for this order

​
paymentOptions
object

Defines settings for payment.

​
metadata
object

Metadata allows you to pass any data to Paybyrd which will be returned in the order query and also sent in the status changed notifications.

Example:
{ "key1": 1, "key2": "value" }
​
code
enum<string>
read-only

Represents the Paybyrd code of the web request. To see more details check in Return Codes [blocked] page.

Available options:
BYRD010,
BYRD200,
BYRD201,
BYRD203,
BYRD205,
BYRD206,
BYRD207,
BYRD208,
BYRD230,
BYRD231,
BYRD240,
BYRD290,
BYRD291,
BYRD292,
BYRD294,
BYRD299,
BYRD401,
BYRD403,
BYRD900,
BYRD901,
BYRD999
Example:

"BYRD200"

​
description
enum<string>
read-only

Represents a textually the description of the Paybyrd code of the web request. To see more details check in Return Codes [blocked] page

Available options:
Request accepted,
Operation successfully completed,
Payment being processed. Waiting for shopper,
An error occurred while processing the payment. Please query the transaction to confirm its status,
Operation rejected,
Operation blocked by velocity,
Pending redirect,
Payment canceled by the shopper,
Payment already refunded,
The refund amount exceeds the remaining balance of the original payment,
Token is expired,
An error occurred while pre processing the transaction. Please review your request and try again,
An error occurred during while preparing transaction for acquiring. Please review your request and try again,
No payment methods available for this operation. Please contact Paybyrd's support,
Transaction could not be updated. Please review your request and try again,
Operation could not be completed. Please review your request and try again,
Resource access is forbidden,
Resource access unauthorized,
Invalid input,
Resource not found,
Operation failed
Example:

"Operation successfully completed"