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

# API Overview

> Understand the core concepts behind Yala payout APIs.

## Base URLs

| Environment | URL                                                         | Description               |
| ----------- | ----------------------------------------------------------- | ------------------------- |
| Production  | `https://gateway.useyala.com/v1/payout-api/payouts`         | Active customer traffic   |
| Sandbox     | `https://gateway.staging.useyala.com/v1/payout-api/payouts` | Testing and certification |

<Note>
  **Sandbox testing:** Use `gateway.staging.useyala.com`—put "staging" in front of "gateway.useyala.com" when integrating against the sandbox app.
</Note>

<Note>
  Sandbox credentials are isolated from production. Never mix API keys or base URLs between environments.
</Note>

## Authentication

* All endpoints require the `x-api-key` header.
* Keys are scoped to your Yala tenant—treat them as secrets.
* Rotate keys regularly and store them using a secrets manager.

```http theme={null}
POST /v1/payout-api/payouts/initiate HTTP/1.1
Host: gateway.staging.useyala.com
Content-Type: application/json
x-api-key: <SANDBOX_API_KEY>
Idempotency-Key: <CLIENT_GENERATED_KEY>
```

Refer to the [authentication guide](/guides/authentication) for client setup patterns.

## Postman collection

Download the Payout API Postman collection to run requests from Postman:

* [https://docs.useyala.com/resources/postman.json](https://docs.useyala.com/resources/postman.json)

In Postman: **Import**, **Link**, then paste the URL. Set the collection variables `baseUrl` (gateway base URL) and `apiKey` (your API key).

## Common resources

* **Business**: Represents the entity that owns Yala wallets and authorizes payouts.
* **Beneficiary**: The endpoint account receiving funds. Include payout rail-specific fields (e.g., `alipayId`, `swiftNumber`, `routingNumber`) as required by the selected payment method.
* **Payout**: An instruction to send funds from a Yala wallet to a beneficiary. Each payout has a lifecycle captured in `status`. We use six statuses everywhere (API responses and webhooks): **PENDING**, **ADDITIONAL\_INFO\_REQUIRED**, **PROCESSING**, **SUCCESSFUL**, **FAILED**, **REJECTED**. See the [Webhooks guide](/guides/webhooks) for meanings and payload shape.
* **Exchange rate**: Real-time rates returned by `GET /methods`. Rates may change between calls—always fetch fresh rates before displaying to users.
* **Wallets**: Manage wallet balances, top ups, and currency holdings from the Yala dashboard. APIs debit these balances; we do not issue virtual account numbers per currency. **Debit is always from the source currency wallet**—when you initiate a payout with `sourceCurrency: "NGN"`, the NGN wallet is debited by the total (amount + fees). Use [Get Wallet Balances](/api-reference/endpoint/get-wallets) to show available balances before initiating.

## Available endpoints

### Currency Pairs

* **[Get Enabled Pairs](/api-reference/endpoint/get-pairs)**: List currency pairs enabled for your business with current exchange rates.

### Wallets

* **[Get Wallet Balances](/api-reference/endpoint/get-wallets)**: List all business wallet balances (per currency). Use to show available funds before initiating payouts. **Debit is always from the source currency wallet**—the wallet in the currency you send as `sourceCurrency` is debited.

### Payment Methods & Rates

* **[Get Payment Methods](/api-reference/endpoint/get-methods)**: Get available payment methods, current exchange rates, fees, and required beneficiary fields for a specific corridor. **Use this endpoint to build your payout form dynamically.**

### Payouts

* **[Get Document Upload URL](/api-reference/endpoint/upload-document-url)**: Get a presigned URL to upload supporting documents **directly to S3** (file bytes do not go to Yala).
* **[Initiate Payout](/api-reference/endpoint/initiate)**: Create a new payout transaction. **Requires Idempotency-Key header** (client-generated). Returns payout id for tracking. Supporting documents are required for most payouts to be processed (see initiate docs).
* **[Get Payout by ID](/api-reference/endpoint/get-payout)**: Fetch detailed information about a specific payout, including status, conversion details, and timestamps.
* **[Add Supporting Documents](/api-reference/endpoint/add-documents)**: Attach documents to an existing payout (after initiate).

## Typical Integration Flow

1. **Enable currency pairs** in your Yala dashboard
2. **Call `GET /methods`** to get rates, payment methods, and required fields for your corridor
3. **Display options to your user** (rates, methods, settlement times)
4. **Collect beneficiary information** from your user (using required fields from step 2)
5. **Upload supporting documents** when required: `POST /documents/upload-url`, PUT the file to S3, then use `documentUrl` on initiate or PATCH ([guide](/guides/uploading-supporting-documents)). Not required for withdrawals to your business or a UBO.
6. **Call `POST /initiate`** with `Idempotency-Key` header to create payout
7. **Save `payout.id`** from response to your database (UUID — not `payoutRef`)
8. **Track status** via `GET /:id` or webhook notifications

See the [End-to-End Integration Flow](/guides/end-to-end-flow) guide for detailed implementation steps.

## Supported currencies & payout rails

Yala supports payouts across a wide range of currencies—including **CNY (RMB)**, **INR**, and additional African, European, and North American corridors.

| Source currency | Destination currencies                                | Supported methods                                                   |
| --------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
| NGN             | NGN, USD, EUR, GBP, CNY, and more                     | NIP, SWIFT, ALIPAY, WECHAT, and more                                |
| USD             | USD, NGN, GHS, XOF, XAF, ZAR, CAD, EUR, GBP, CNY, INR | WIRE, ACH, SWIFT, NIP, CHINA\_WIRE, HK\_FPS, FASTER\_PAYMENTS, SEPA |
| EUR             | EUR, GBP, NGN, CNY                                    | SEPA, SWIFT                                                         |
| GBP             | GBP, EUR, NGN, CNY                                    | FASTER\_PAYMENTS, BACS, SWIFT                                       |
| CNY             | CNY                                                   | SWIFT, CHINA\_WIRE                                                  |
| INR             | INR                                                   | SWIFT                                                               |

**Note:** Available methods vary by corridor. Use GET /methods to get the exact methods available for your specific source/destination currency pair.

### Currency and Country Codes

* **Currency codes:** Use ISO 4217 3-letter codes (e.g., `NGN`, `USD`, `CNY`, `EUR`, `GBP`)
* **Country codes:** Use ISO 3166-1 alpha-3 3-letter codes (e.g., `NGA` for Nigeria, `CHN` for China, `USA` for United States)

**Common codes reference:**

| Currency           | Code  | Country        | Code  |
| ------------------ | ----- | -------------- | ----- |
| Nigerian Naira     | `NGN` | Nigeria        | `NGA` |
| US Dollar          | `USD` | United States  | `USA` |
| Chinese Yuan       | `CNY` | China          | `CHN` |
| Euro               | `EUR` | Germany        | `DEU` |
| Euro               | `EUR` | France         | `FRA` |
| British Pound      | `GBP` | United Kingdom | `GBR` |
| Indian Rupee       | `INR` | India          | `IND` |
| Ghanaian Cedi      | `GHS` | Ghana          | `GHA` |
| South African Rand | `ZAR` | South Africa   | `ZAF` |
| Canadian Dollar    | `CAD` | Canada         | `CAN` |

**Discovering valid codes:**

1. **Use GET /pairs endpoint** to see enabled currency pairs for your business
2. **Use GET /methods endpoint** with a corridor to see supported currencies and countries
3. **See the [Currency and Country Codes Reference](/guides/currency-country-codes) guide** for a quick reference table and best practices
4. **Reference ISO standards:**
   * [ISO 4217 Currency Codes](https://www.iso.org/iso-4217-currency-codes.html) - Official currency code list
   * [ISO 3166-1 Country Codes](https://www.iso.org/iso-3166-country-codes.html) - Official country code list

<Tip>
  The GET /methods endpoint will only return corridors that are enabled for your business. If a currency pair doesn't appear, enable it in your dashboard first.
</Tip>

<Note>
  Yala currently does not provide virtual IBANs or account numbers in these currencies. Fund and reconcile your wallets directly within the Yala app, then invoke the payout APIs to move balances to external beneficiaries.
</Note>

## Webhooks

Subscribe to **payout status change** notifications by registering an HTTPS URL via the API or in the Yala app. We POST a JSON payload to your URL whenever a payout’s status changes (e.g. to `PROCESSING`, `SUCCESSFUL`, or `FAILED`).

**Payload includes:** `eventType`, `deliveryId` (for idempotency), `occurredAt`, and `data` with `payoutId`, `businessId`, `oldStatus`, `newStatus`, `changedAt`, and optional `reason`. You can optionally set a **secret** when registering; we then send `X-Yala-Signature: sha256=<hex>` (HMAC-SHA256 of the raw body) so you can verify requests.

See the [Webhooks guide](/guides/webhooks) for subscription API, payload shape, signature verification, and best practices.

## Rate limits

* Default rate limit: **5 requests per second** per API key.
* Monthly quota: **10,000 requests per month** per API key.
* Requests above limits return HTTP `429` and should be retried with backoff.