Skip to main content
POST
/
v1
/
payout-api
/
payouts
/
quote
Get quote
curl --request POST \
  --url https://gateway.useyala.com/v1/payout-api/payouts/quote \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "sourceAmount": 1000,
  "sourceCurrency": "USD",
  "destinationCurrency": "NGN",
  "destinationCountryCode": "NGA"
}
'

​
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

FieldTypeRequiredDescription
sourceAmountnumberYesAmount to send from source wallet
sourceCurrencystringYesSource currency (e.g. USD, NGN)
destinationCurrencystringYesDestination currency (e.g. NGN, CNY)
destinationCountryCodestringYesISO country code (3-letter, e.g. NGA, CHN, USA)
methodstringYesPayout 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

FieldTypeDescription
sourceAmountnumberAmount entered by user (source currency)
sourceCurrencystringSource currency
destinationAmountnumberAmount beneficiary receives (destination currency)
destinationCurrencystringDestination currency
totalDeductiblenumberTotal debited from wallet (always in source currency). Equals sourceAmount + fee.amount.
exchangeRatenumberExchange rate used for the conversion
methodstringPayout method
feeobjectFee (always borne by the tenant)
fee.amountnumberFee amount
fee.currencystringFee 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.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
sourceAmount
number<float>
required
Example:

1000

​
sourceCurrency
string
required
Example:

"USD"

​
destinationCurrency
string
required
Example:

"NGN"

​
method
enum<string>
required
Available options:
swift,
nip,
hk_fps,
china_wire,
faster_payments,
wire,
ach,
sepa
​
destinationCountryCode
string
required
Example:

"NGA"

Response

Quote calculated successfully