Initiate Payout

​

Overview

• No pre-funding required - source currency can differ from destination currency
• FX conversion happens automatically
• Payouts start in PENDING status

​

Required Headers

​

Request

POST /v1/payout-api/payouts/initiate HTTP/1.1
Host: gateway.staging.useyala.com
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
x-api-key: <YOUR_API_KEY>

​

Request Body

{
  "sourceAmount": 10000,
  "sourceCurrency": "NGN",
  "destinationCurrency": "CNY",
  "destinationCountryCode": "CHN",
  "method": "ALIPAY",
      "beneficiary": {
        "accountName": "Li Wei",
        "accountCurrency": "CNY",
        "alipayId": "user@alipay.com"
      },
      "narration": "Payment for services",
      "supportingDocument": "https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png"
    }

​

Request Fields

• ✅ Same structure for all methods - The beneficiary object always has the same fields available
• ✅ Method-specific requirements - Use GET /methods endpoint to discover which fields are required for your payment method
• ✅ Automatic country derivation - If beneficiary.countryCode is not provided, it will be automatically derived from destinationCountryCode in the request body
• ✅ Service-level validation - The API validates that all required fields for your selected method are present

​

Response

{
  "id": "payout-id-uuid",
  "payoutRef": "PAY-2024-001",
  "businessId": "business-id-uuid",
  "sourceAmount": 10000,
  "sourceCurrency": "NGN",
  "destinationAmount": 42.5,
  "destinationCurrency": "CNY",
  "exchangeRate": 235.0,
  "transactionFees": 0,
  "status": "PENDING",
  "method": "ALIPAY",
  "narration": "Payment for services",
  "createdAt": "2024-01-20T10:00:00Z",
  "updatedAt": "2024-01-20T10:00:00Z"
}

​

Response Fields

​

Idempotency

1. Generate key client-side before making the request:
   Copy

   const idempotencyKey = crypto.randomUUID();
   // OR
   const idempotencyKey = `order-${orderId}`;
   
2. Include in header:
   Copy

   headers: {
     'Idempotency-Key': idempotencyKey,
   }
   
3. Retry with same key if request fails:
   • Network error/timeout: Retry with same key + same body
   • API returns original payout (no duplicate created)

• Same key + same request body: Returns existing payout (no duplicate)
• Same key + different request body: 409 Conflict (use a new key)
• Missing key: 400 Bad Request

​

Error Responses

​

400 Bad Request - Missing Idempotency Key

{
  "statusCode": 400,
  "message": "Idempotency-Key header is required",
  "error": "MISSING_IDEMPOTENCY_KEY"
}

​

400 Bad Request - Missing Required Fields

{
  "statusCode": 400,
  "message": "Missing required fields: alipayId",
  "error": "MISSING_REQUIRED_FIELDS"
}

• ALIPAY: accountName, alipayId
• WECHAT: accountName, and one of: openId OR wechatUserId
• SEPA: accountName, iban
• SWIFT: accountName, accountNumber, swiftCode (required), bankName, beneficiaryCountry (required), iban (optional), intermediarySwift (optional), address (optional), city (optional), postCode (optional)
• ACH: accountName, routingNumber, accountNumber, accountType (enum: “checking” or “savings”)
• NIP: accountName, accountNumber, bankCode
• BACS/FASTER_PAYMENTS: accountName, sortCode, accountNumber
• HONG_KONG_FPS: accountName, and one of: fpsId OR phoneNumber OR email OR (accountNumber + bankCode)

​

400 Bad Request - Insufficient Funds

{
  "statusCode": 400,
  "message": "Insufficient balance in source wallet",
  "error": "INSUFFICIENT_FUNDS"
}

​

409 Conflict - Idempotency Key Reused

{
  "statusCode": 409,
  "message": "Idempotency key already used with a different request. Use a new key or retry with the same request body.",
  "error": "IDEMPOTENCY_KEY_CONFLICT"
}

​

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

​

Usage Example

// 1. Generate idempotency key (client-side)
const idempotencyKey = crypto.randomUUID();

// 2. Get required fields for method (optional, if you need to validate)
const methodsResponse = await fetch(
  'https://gateway.staging.useyala.com/v1/payout-api/payouts/methods?sourceCurrency=NGN&destinationCurrency=CNY&destinationCountryCode=CHN',
  {
    headers: { 'x-api-key': apiKey }
  }
);
const { methods } = await methodsResponse.json();
const alipayMethod = methods.find(m => m.code === 'ALIPAY');

// 3. Create payout
const response = await fetch(
  'https://gateway.staging.useyala.com/v1/payout-api/payouts/initiate',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,  // Client-generated
      'x-api-key': apiKey,
    },
    body: JSON.stringify({
      sourceAmount: 10000,
      sourceCurrency: 'NGN',
      destinationCurrency: 'CNY',
      destinationCountryCode: 'CHN',
      method: 'ALIPAY',
      beneficiary: {
        accountName: 'Li Wei',
        accountCurrency: 'CNY',
        alipayId: 'user@alipay.com',
      },
      narration: 'Payment for services',
      supportingDocument: 'https://example.com/invoice.pdf',
    }),
  }
);

const payout = await response.json();
console.log(`Payout created: ${payout.id}, Status: ${payout.status}`);

// 4. Store payout.id for tracking
// Use payout.id to query status via GET /:id or receive webhook notifications

// 5. If request fails, retry with SAME key + SAME body
// API will return the original payout (no duplicate)

​

Webhooks

1. Activate webhook notifications in your Yala dashboard
2. Configure your webhook endpoint URL
3. You’ll receive payout.status.changed.v1 events when status changes

• payoutId - The payout ID (use this to match with your records)
• oldStatus - Previous status
• newStatus - New status (one of PENDING, PROCESSING, SUCCESSFUL, FAILED, REJECTED)
• changedAt - Timestamp of status change
• reason - Human-readable reason for the change

​

Exchange Rate Behavior

• Rate is fetched fresh - When you call POST /initiate, the system fetches the current exchange rate from our rate database
• Rate may differ from preview - If you previously viewed rates via GET /pairs or GET /methods, those rates were for reference only. The actual rate applied may be different if rates changed between viewing and initiating
• Check the response - The exchangeRate field in this response shows the rate that was actually used for your payout
• Rate is not locked - There is no rate guarantee or locking mechanism. The rate used is whatever is current at initiation time

​

Notes

• FX Conversion: Happens automatically (no pre-funding required)
• Status: Payouts start in PENDING status
• Field Validation: Beneficiary fields are validated against method requirements
• Tracking: Save the id field from the response to track payout status
• Fees: Currently disabled
• Exchange Rate: Always check the exchangeRate field in the response to see the rate that was actually applied