> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paybyrd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://beta.paybyrd.com/developer-keys) section of the Paybyrd dashboard.

## Authentication

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

```bash theme={null}
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.

<Warning>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.</Warning>

## 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.

```bash theme={null}
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`.

```json theme={null}
{
"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:

```json theme={null}
{
   "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 |