Skip to main content

​
Prerequisites

  • An active Yala sandbox account. Request access by emailing [email protected].
  • A sandbox API key (x-api-key) with payouts permissions.
  • A registered business and at least one approved beneficiary in the sandbox dashboard.
  • Funded wallets in the Yala app for the currencies you plan to send. Yala does not issue standalone virtual account numbers; wallet balances are managed in-app.

​
1. Configure environments

EnvironmentBase URL
Productionhttps://gateway.useyala.com/api/public/
Sandboxhttps://gateway.staging.useyala.com/api/public/
Always send HTTPS requests and include the trailing slash to avoid redirect latency.
Save the x-api-key in your secret manager and inject it at runtime. Avoid hardcoding keys in source control.

​
2. Quote a payout

Call the calculator endpoint to surface total cost, exchange rates, and settlement timing before initiating a payout. 
curl https://gateway.staging.useyala.com/api/public/payouts/calculate/exchange-rate \
  -H "Content-Type: application/json" \
  -H "x-api-key: <SANDBOX_API_KEY>" \
  -d '{
    "sourceAmount": 1000,
    "sourceCurrency": "USD",
    "destinationCurrency": "NGN",
    "feeBearer": "tenant",
    "method": "nip",
    "destinationCountryCode": "NGA"
  }'
Use the includedFees array in the response to itemize costs in your UI.

​
3. Initiate the payout

Use the quote data to build a payout request. The businessId and beneficiary details must already exist in Yala. 
curl https://gateway.staging.useyala.com/api/public/payouts/initiate \
  -H "Content-Type: application/json" \
  -H "x-api-key: <SANDBOX_API_KEY>" \
  -d '{
    "businessId": "6fd2b69f-c529-4fe4-b680-29256f860553",
    "sourceAmount": 1000,
    "sourceCurrency": "USD",
    "destinationCurrency": "NGN",
    "feeBearer": "TENANT",
    "method": "NIP",
    "destinationCountryCode": "NGA",
    "narration": "Andromeda Galaxy",
    "supportingDocument": "https://sample.com/doc",
    "beneficiary": {
      "countryCode": "NGA",
      "bankCountryCode": "NGA",
      "accountNumber": "8068487823",
      "accountName": "Will Wonker",
      "bankName": "OPay",
      "accountCurrency": "NGN",
      "payoutMethod": "NIP",
      "isIndividual": true
    }
  }'
Persist the payoutRef from the response to reconcile downstream status updates.

​
4. Track payout status

  • Poll the status field in PayoutData to drive user-facing updates (e.g., PENDING_APPROVAL, PROCESSING, COMPLETED).
  • Record the meta.statusChange timeline for audit logs.
  • Contact support to enable real-time webhooks for automated status notifications.

​
Next steps

Authentication guide

Learn how to manage API keys and rotate credentials.

Error handling

Handle validation failures and rate limiting gracefully.

Exchange rate endpoint

Review schema definitions and sample responses.

Payout initiation endpoint

Understand required fields and response structure.