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

# Overview

# Orbt V2 - B2B Digital Value Distribution

The Orbt V2 API enables businesses to distribute digital value at scale: gift cards, PIN-less top-ups, bill payments, and direct account credits; across 1,000+ brands in 150+ countries.

<Note>
  This API is available to enterprise partners only. To request access contact [support@orbt.com](mailto:support@orbt.com).
</Note>

## Base URL

[https://partner.orbt.com/v2](https://partner.orbt.com/v2)

## How it works

<Steps>
  <Step title="Check your balance">
    `GET /v2/accounts/balances` verify you have sufficient funds in the wallet currency you plan to use.
  </Step>

  <Step title="Browse the catalog">
    `GET /v2/products?currency=USD`  discover available products, denominations, and FX rates.
  </Step>

  <Step title="Place an order">
    `POST /v2/orders`  single or bulk, one call, no cart. Returns an order ID and status `PENDING`.
  </Step>

  <Step title="Poll for completion">
    `GET /v2/orders/{orderId}`  poll until status is `COMPLETED`.
  </Step>

  <Step title="Retrieve codes">
    `GET /v2/orders/{orderId}/items` for individual codes, or `/fulfillments/export` for a bulk CSV.
  </Step>
</Steps>

## Authentication

Every request must be signed using HMAC-SHA256. Include these five headers on all requests:

| Header        | Description                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| `x-api-key`   | Your API key                                                                                           |
| `x-client-id` | Your client ID (UUID)                                                                                  |
| `x-timestamp` | Current UTC timestamp in ISO 8601 format                                                               |
| `x-body-hash` | SHA-256 hash of the raw request body, Base64-encoded. Hash an empty string for GET requests.           |
| `x-signature` | HMAC-SHA256 of `METHOD\nTIMESTAMP\nCLIENT_ID\nBODY_HASH`, signed with your HMAC secret, Base64-encoded |

See the [Authentication](/integrations/authentication) page for full signing instructions and code examples.

## Idempotency

All write operations support the `Idempotency-Key` header. Same key + same payload returns the original response without creating a duplicate. Same key + different payload returns an error.

Idempotency-Key: 5f4d4f3a-b4ec-4ef5-a0ef-c26f71d2f5d8

## Pagination

All list endpoints use offset-based pagination:

Default `pageSize` is `100`, maximum is `2000`.

## Order Status Reference

| Status         | Description                                  |
| -------------- | -------------------------------------------- |
| `PENDING`      | Order received, queued for processing        |
| `PROCESSING`   | Order is being fulfilled                     |
| `COMPLETED`    | All items fulfilled successfully             |
| `CANCELLED`    | Order was cancelled                          |
| `ON_HOLD`      | Insufficient account funds                   |
| `OUT_OF_STOCK` | One or more products temporarily unavailable |

## Error Model

All errors follow a consistent structure:

```json theme={null}
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Order not found"
  }
}
```

| Code                      | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| `VALIDATION_ERROR`        | Invalid request body or parameters                         |
| `AUTHENTICATION_ERROR`    | Missing or invalid auth headers                            |
| `AUTHORIZATION_ERROR`     | Valid credentials but insufficient permissions             |
| `RESOURCE_NOT_FOUND`      | The requested resource does not exist                      |
| `BUSINESS_RULE_VIOLATION` | Request violates a business rule (e.g. insufficient funds) |
| `RATE_LIMIT_EXCEEDED`     | Too many requests                                          |
| `INTERNAL_SERVER_ERROR`   | Unexpected server error                                    |