# API Overview

The ZevPay Checkout REST API lets you create and manage payments, virtual PayIDs, virtual accounts, invoices, and transfers programmatically.

## Base URL

```
https://api.zevpaycheckout.com
```

## Authentication

All endpoints require an API key via the `x-api-key` header or `Authorization: Bearer <key>` header. See [Authentication](/guide/authentication).

## Permissions

Each API key has a `permissions` array that controls which product APIs it can access. See [API Key Permissions](/guide/authentication#api-key-permissions) for details.

| Permission | Products | Description |
|------------|----------|-------------|
| `checkout` | Checkout Sessions | Initialize and manage checkout payment sessions |
| `virtual_payid` | Static PayID, Dynamic PayID | Create and manage virtual PayIDs |
| `virtual_account` | Virtual Accounts | Create temporary bank accounts for collecting payments |
| `invoices` | Invoices | Create and manage programmable invoices |
| `transfers` | Transfers | Programmatically send money from a linked wallet |

::: info Legacy keys
API keys created before the permissions system have an empty permissions array. These keys retain access to all non-transfer products automatically. Only the `transfers` permission must be explicitly granted.
:::

## Response format

All successful responses follow this format:

```json
{
  "success": true,
  "data": {
    // Response payload
  }
}
```

Error responses return the appropriate HTTP status code. See [Errors](/api/errors) for details:

```json
{
  "success": false,
  "error": {
    "code": "HTTP_ERROR",
    "message": "A human-readable error description"
  },
  "correlationId": "-"
}
```

## Endpoints

### Checkout Sessions

| Method | Path | Permission | Auth | Description |
|--------|------|------------|------|-------------|
| `POST` | [`/v1/checkout/session/initialize`](/api/initialize-session) | `checkout` | Secret or Public key | Create a checkout session |
| `POST` | [`/v1/checkout/session/:id/payment-method`](/api/select-payment-method) | `checkout` | Public key | Select payment method |
| `GET` | [`/v1/checkout/session/:id/verify`](/api/verify-session) | `checkout` | Secret or Public key | Check payment status |
| `GET` | [`/v1/checkout/session/:id`](/api/get-session) | `checkout` | Public key | Get full session details |

### Virtual PayID

| Method | Path | Permission | Auth | Description |
|--------|------|------------|------|-------------|
| `POST` | [`/v1/checkout/static-payid`](/api/static-payid#create-static-payid) | `virtual_payid` | Secret key | Create a static PayID |
| `GET` | [`/v1/checkout/static-payid`](/api/static-payid#list-static-payids) | `virtual_payid` | Secret key | List static PayIDs |
| `GET` | [`/v1/checkout/static-payid/:id`](/api/static-payid#get-static-payid) | `virtual_payid` | Secret key | Get a static PayID |
| `PUT` | [`/v1/checkout/static-payid/:id`](/api/static-payid#update-static-payid) | `virtual_payid` | Secret key | Update a static PayID |
| `DELETE` | [`/v1/checkout/static-payid/:id`](/api/static-payid#deactivate-static-payid) | `virtual_payid` | Secret key | Deactivate a static PayID |
| `POST` | [`/v1/checkout/static-payid/:id/reactivate`](/api/static-payid#reactivate-static-payid) | `virtual_payid` | Secret key | Reactivate a static PayID |
| `POST` | [`/v1/checkout/dynamic-payid`](/api/dynamic-payid#create-dynamic-payid) | `virtual_payid` | Secret key | Create a dynamic PayID |
| `GET` | [`/v1/checkout/dynamic-payid`](/api/dynamic-payid#list-dynamic-payids) | `virtual_payid` | Secret key | List dynamic PayIDs |
| `GET` | [`/v1/checkout/dynamic-payid/:id`](/api/dynamic-payid#get-dynamic-payid) | `virtual_payid` | Secret key | Get a dynamic PayID |

### Virtual Accounts

| Method | Path | Permission | Auth | Description |
|--------|------|------------|------|-------------|
| `POST` | [`/v1/checkout/virtual-account`](/api/virtual-account#create-virtual-account) | `virtual_account` | Secret key | Create a virtual account |
| `GET` | [`/v1/checkout/virtual-account`](/api/virtual-account#list-virtual-accounts) | `virtual_account` | Secret key | List virtual accounts |
| `GET` | [`/v1/checkout/virtual-account/:id`](/api/virtual-account#get-virtual-account) | `virtual_account` | Secret key | Get a virtual account |

### Invoices

| Method | Path | Permission | Auth | Description |
|--------|------|------------|------|-------------|
| `POST` | [`/v1/checkout/invoice`](/api/invoice#create-invoice) | `invoices` | Secret key | Create an invoice |
| `GET` | [`/v1/checkout/invoice`](/api/invoice#list-invoices) | `invoices` | Secret key | List invoices |
| `GET` | [`/v1/checkout/invoice/:id`](/api/invoice#get-invoice) | `invoices` | Secret key | Get an invoice |
| `PATCH` | [`/v1/checkout/invoice/:id`](/api/invoice#update-invoice) | `invoices` | Secret key | Update a draft invoice |
| `POST` | [`/v1/checkout/invoice/:id/send`](/api/invoice#send-invoice) | `invoices` | Secret key | Send an invoice |
| `POST` | [`/v1/checkout/invoice/:id/void`](/api/invoice#void-invoice) | `invoices` | Secret key | Void an invoice |

### Transfers

| Method | Path | Permission | Auth | Description |
|--------|------|------------|------|-------------|
| `GET` | [`/v1/checkout/transfer/banks`](/api/transfer#list-banks) | — | Secret key | List supported banks |
| `POST` | [`/v1/checkout/transfer/banks/resolve`](/api/transfer#resolve-bank-account) | — | Secret key | Verify a bank account |
| `POST` | [`/v1/checkout/transfer/charges`](/api/transfer#calculate-charges) | `transfers` | Secret key | Calculate transfer fees |
| `GET` | [`/v1/checkout/transfer/balance`](/api/transfer#get-balance) | `transfers` | Secret key | Get wallet balance |
| `POST` | [`/v1/checkout/transfer`](/api/transfer#initiate-transfer) | `transfers` | Secret key | Send money |
| `GET` | [`/v1/checkout/transfer`](/api/transfer#list-transfers) | `transfers` | Secret key | List transfers |
| `GET` | [`/v1/checkout/transfer/:reference`](/api/transfer#get-transfer) | `transfers` | Secret key | Get a transfer |
| `GET` | [`/v1/checkout/transfer/:reference/verify`](/api/transfer#verify-transfer) | `transfers` | Secret key | Verify transfer status |

### Wallet Management

| Method | Path | Permission | Auth | Description |
|--------|------|------------|------|-------------|
| `GET` | [`/v1/checkout/wallet`](/api/wallet#get-wallet) | `transfers` | Secret key (admin) | Get wallet details |
| `PATCH` | [`/v1/checkout/wallet`](/api/wallet#update-wallet-settings) | `transfers` | Secret key (admin) | Update wallet settings |
| `GET` | [`/v1/checkout/wallet/members`](/api/wallet#list-members) | `transfers` | Secret key (admin) | List wallet members |
| `POST` | [`/v1/checkout/wallet/members`](/api/wallet#add-member) | `transfers` | Secret key (admin) | Add a member |
| `DELETE` | [`/v1/checkout/wallet/members/:payId`](/api/wallet#remove-member) | `transfers` | Secret key (admin) | Remove a member |
| `PATCH` | [`/v1/checkout/wallet/members/:payId`](/api/wallet#update-member-settings) | `transfers` | Secret key (admin) | Update member settings |

## Rate limits

All endpoints are rate-limited to **100 requests per minute** per API key. The session initialization endpoint has a stricter limit of **30 requests per minute**.

If you exceed the limit, you'll receive a `429 Too Many Requests` response. See [Rate Limiting](/guide/rate-limiting) for details and best practices.

## Request size limits

Request bodies are limited to **1 MB**. This is more than sufficient for all API operations.

## Versioning

The API is versioned via the URL path (`/v1/`). Breaking changes will result in a new version.