Skip to main content

​
Base URLs

EnvironmentURLDescription
Productionhttps://gateway.useyala.com/v1/payout-api/payoutsActive customer traffic
Sandboxhttps://gateway.staging.useyala.com/v1/payout-api/payoutsTesting and certification
Sandbox testing: Use gateway.staging.useyala.com—put “staging” in front of “gateway.useyala.com” when integrating against the sandbox app.
Sandbox credentials are isolated from production. Never mix API keys or base URLs between environments.

​
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.
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 for client setup patterns.

​
Postman collection

Download the Payout API Postman collection to run requests from Postman: 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 five statuses everywhere (API responses and webhooks): PENDING, PROCESSING, SUCCESSFUL, FAILED, REJECTED. See the Webhooks guide 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 to show available balances before initiating.

​
Available endpoints

​
Currency Pairs

  • Get Enabled Pairs: List currency pairs enabled for your business with current exchange rates.

​
Wallets

  • Get Wallet Balances: 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: 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

  • Initiate Payout: Create a new payout transaction. Requires Idempotency-Key header (client-generated). Returns payout id for tracking.
  • Get Payout by ID: Fetch detailed information about a specific payout, including status, conversion details, and timestamps.

​
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. Call POST /initiate with Idempotency-Key header to create payout
  6. Save payout.id from response to your database
  7. Track status via GET /:id or webhook notifications
See the End-to-End Integration 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 currencyDestination currenciesSupported methods
NGNNGN, USD, EUR, GBP, CNY, and moreNIP, SWIFT, ALIPAY, WECHAT, and more
USDUSD, NGN, GHS, XOF, XAF, ZAR, CAD, EUR, GBP, CNY, INRWIRE, ACH, SWIFT, NIP, CHINA_WIRE, HK_FPS, FASTER_PAYMENTS, SEPA
EUREUR, GBP, NGN, CNYSEPA, SWIFT
GBPGBP, EUR, NGN, CNYFASTER_PAYMENTS, BACS, SWIFT
CNYCNYSWIFT, CHINA_WIRE
INRINRSWIFT
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:
CurrencyCodeCountryCode
Nigerian NairaNGNNigeriaNGA
US DollarUSDUnited StatesUSA
Chinese YuanCNYChinaCHN
EuroEURGermanyDEU
EuroEURFranceFRA
British PoundGBPUnited KingdomGBR
Indian RupeeINRIndiaIND
Ghanaian CediGHSGhanaGHA
South African RandZARSouth AfricaZAF
Canadian DollarCADCanadaCAN
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 guide for a quick reference table and best practices
  4. Reference ISO standards:
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.
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.

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