A quote fixes the exchange rate and fee for one amount in one currency pair. Create a quote, show it to your user, then pass its id to a payout or conversion to get exactly those numbers.

Create a quote

POST /v1/quotes
string
required
The currency you pay from: NGN, GHS or KES.
string
required
The currency the recipient gets.
integer
required
The amount in sourceCurrency, in minor units. A positive whole number.
string
default:"payout"
What the quote is for: payout or conversion. Set conversion when you will use the quote for a wallet-to-wallet conversion.
Response · 201
string
The quote id. Pass it as quoteId.
string
The amount you asked to send, in minor units.
string
What the recipient gets, in minor units of destinationCurrency.
string
The exchange rate applied, as a decimal string.
object
Payve’s fee. fee.amount is in minor units of fee.currency. It can also carry a structure object describing how the fee is worked out.
string
When the quote stops being usable.

What you pay

The fee is charged on top of the amount, in the source currency. Your wallet is debited sourceAmount + fee.amount. In the sample: ₦50,000.00 is sent, the fee is ₦250.00, your wallet is debited ₦50,250.00, and the recipient gets GH₵465.00.

Use the quote

Pass quoteId to POST /v1/payouts or POST /v1/conversions, with the same currencies and amount.
A quote is for one pair and one amount. Sending a quoteId with a different amount or currency pair fails. If the amount changes, create a new quote.
A quote can be used once. After a payout or conversion consumes it, a second use returns 409 quote_already_consumed.

How long a quote holds

Five minutes by default. expiresAt is the authority. Read it instead of assuming. After expiresAt, using the quote returns 422 quote_expired. Create a new quote and show the new numbers to your user before you send.
Create the quote when your user is ready to confirm, not when they open the page. Show a countdown to expiresAt.

Sending without a quote

You can omit quoteId on a payout or conversion. Payve then prices it at the rate in force at that moment. Use a quote whenever a person needs to see the numbers first.

Look up quotes

When it fails

GET /v1/rates returns indicative rates without a key. See Coverage.