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 section of the Paybyrd dashboard.

Authentication

All requests must include your API key in the x-api-key request header.

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.

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.

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

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

API introduction

API reference

Environments

Authentication

Request format

Idempotency

Request tracking

Responses

​Environments

​Authentication

​Request format

​Idempotency

​Request tracking

​Responses

​Pagination

Environments

Authentication

Request format

Idempotency

Request tracking

Responses

Pagination