Get Payout Quote - Yala Payout APIs

Overview

Returns a quote for a prospective payout without creating one. Use this endpoint to:

Show the fee to the user before they confirm
Display total amount debited from the wallet (totalDeductible, always in source currency)
Display amount the beneficiary receives (destinationAmount)

Fees are always borne by the tenant (your business). The fee is added on top of the source amount; the wallet is debited sourceAmount + fee, and the beneficiary receives the full converted amount. Read-only — call as many times as needed (e.g. when the user changes the amount). When the user confirms, call POST /initiate to create the payout.

Recommended flow: 1) GET /pairs, 2) GET /methods, 3) POST /quote (user enters amount; show fee and totals), 4) User confirms, 5) POST /initiate

Request

POST /v1/payout-api/payouts/quote HTTP/1.1
Host: gateway.staging.useyala.com
Content-Type: application/json
x-api-key: <YOUR_API_KEY>

Request Body

{
  "sourceAmount": 100000,
  "sourceCurrency": "NGN",
  "destinationCurrency": "CNY",
  "destinationCountryCode": "CHN",
  "method": "ALIPAY"
}

Request Fields

Field	Type	Required	Description
`sourceAmount`	number	Yes	Amount to send from source wallet
`sourceCurrency`	string	Yes	Source currency (e.g. `USD`, `NGN`)
`destinationCurrency`	string	Yes	Destination currency (e.g. `NGN`, `CNY`)
`destinationCountryCode`	string	Yes	ISO country code (3-letter, e.g. `NGA`, `CHN`, `USA`)
`method`	string	Yes	Payout method (e.g. `NIP`, `SWIFT`, `ALIPAY`)

Response

{
  "sourceAmount": 100000,
  "sourceCurrency": "NGN",
  "destinationAmount": 463.48,
  "destinationCurrency": "CNY",
  "totalDeductible": 100060.07,
  "exchangeRate": 214.0404,
  "method": "ALIPAY",
  "fee": {
    "amount": 60.07,
    "currency": "NGN"
  }
}

Response Fields

Field	Type	Description
`sourceAmount`	number	Amount entered by user (source currency)
`sourceCurrency`	string	Source currency
`destinationAmount`	number	Amount beneficiary receives (destination currency)
`destinationCurrency`	string	Destination currency
`totalDeductible`	number	Total debited from wallet (always in source currency). Equals `sourceAmount + fee.amount`.
`exchangeRate`	number	Exchange rate used for the conversion
`method`	string	Payout method
`fee`	object	Fee (always borne by the tenant)
`fee.amount`	number	Fee amount
`fee.currency`	string	Fee currency (always source currency)

Showing Fees to the User

“You will pay (includes fee). Recipient gets .”

Error Responses

400 Bad Request – Validation or unsupported pair

{
  "statusCode": 400,
  "message": "Currency pair is not enabled for this business.",
  "error": "CORRIDOR_NOT_ENABLED"
}

401 Unauthorized

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

Usage Example

// User has entered amount and selected method; show quote before "Confirm"
const quoteResponse = await fetch(
  'https://gateway.staging.useyala.com/v1/payout-api/payouts/quote',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({
      sourceAmount: 100000,
      sourceCurrency: 'NGN',
      destinationCurrency: 'CNY',
      destinationCountryCode: 'CHN',
      method: 'ALIPAY',
    }),
  }
);

const quote = await quoteResponse.json();

// Display to user
console.log(`You pay: ${quote.totalDeductible} ${quote.sourceCurrency}`);
console.log(`Recipient gets: ${quote.destinationAmount} ${quote.destinationCurrency}`);
console.log(`Fee: ${quote.fee.amount} ${quote.fee.currency}`);
console.log(`Rate: ${quote.exchangeRate}`);

// When user clicks "Confirm", call POST /initiate with same parameters + beneficiary + narration

Notes

No side effects — calling this endpoint does not create a payout or debit any wallet.
totalDeductible is always in source currency — the amount that will be debited from the wallet if the user confirms.
Fees are always borne by the tenant — the fee is in source currency and added on top of the source amount.
Rate at quote time — the rate used when you call POST /initiate may differ slightly; the initiate response contains the actual rate applied.

​Overview

​Request

​Request Body

​Request Fields

​Response

​Response Fields

​Showing Fees to the User

​Error Responses

​400 Bad Request – Validation or unsupported pair

​401 Unauthorized

​Usage Example

​Notes

Overview

Request

Request Body

Request Fields

Response

Response Fields

Showing Fees to the User

Error Responses

400 Bad Request – Validation or unsupported pair

401 Unauthorized

Usage Example

Notes