Skip to main content
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.
EnvironmentBase URL
Sandbox (testing)https://gatewaysandbox.paybyrd.com
Productionhttps://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:
HeaderValue
Content-Typeapplication/json
Acceptapplication/json
x-api-keyYour 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
   }
}
FieldDescription
pageNumberCurrent page (1-based)
pageSizeNumber of items on this page
totalTotal number of items in the collection
totalAvailableTotal number of items accessible to your account