Skip to main content

​
Base URLs

EnvironmentURLDescription
Productionhttps://gateway.useyala.com/api/public/Active customer traffic
Sandboxhttps://gateway.staging.useyala.com/api/public/Testing and certification
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 /payouts/initiate HTTP/1.1
Host: gateway.staging.useyala.com
Content-Type: application/json
x-api-key: <SANDBOX_API_KEY>
Refer to the authentication guide for client setup patterns.

​
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., swiftNumber, routingNumber) as required.
  • Payout: An instruction to send funds from a Yala wallet to a beneficiary. Each payout has a lifecycle captured in PayoutData.status.
  • Exchange rate: Quotes generated through the calculator endpoint. Rates expire quickly—always re-quote if the customer delays confirmation.
  • 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.

​
Available endpoints

​
Countries

  • Fetch Countries: Discover supported countries and their currency information. Filter by currency code to find destinations that accept specific currencies.

​
Payouts

  • Calculate Exchange Rate: Get real-time FX rates, fees, and settlement times before initiating a payout.
  • Initiate Payout: Create a new payout transaction to send funds to a beneficiary.
  • List Payouts: Retrieve a paginated list of payouts with optional filtering by payout reference.
  • Get Payout by ID: Fetch detailed information about a specific payout, including source wallet, beneficiary details, and transaction metadata.

​
Transactions

  • List Transactions: View transaction history across all wallets, with filtering by payout reference to track related debits and credits.

​
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
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
NGNNGN, USD, EUR, GBPnip, swift
CNYCNYswift, china_wire
INRINRswift
Use the calculator endpoint to confirm availability, FX rates, fees, and settlement times for the desired corridor before creating payouts. Rails are selected via the method field in both calculator and payout initiation requests.
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

Contact Yala support to enable webhooks. When active, Yala sends event notifications (e.g., payout.approved, payout.completed) to your configured URL. Validate incoming requests by checking the source IP and verifying the shared secret provided during onboarding.

​
Rate limits

  • Default rate limit: 60 requests per minute per tenant.
  • Bursts above the limit return HTTP 429 with a retry-after header.
  • For higher throughput, contact support with projected request volumes.

​
SDKs

Official SDKs are under development. In the meantime, use your preferred HTTP client with the JSON payloads defined in this reference. Sample code snippets are provided throughout the guides.