A conversion debits one of your wallets and credits another in a different currency. Nothing leaves Payve. Use it to hold the currency you will pay out in. Before you start: a funded source wallet, and a key with the conversions:write scope.

Quote, then convert

1

Get a quote for a conversion

Create a quote with transactionType set to conversion.
Set transactionType to conversion. A quote created for a payout can be priced differently from the rate a conversion settles at.
2

Create the conversion

Send the same currencies and amount with the quoteId.
3

Wait for the event

Payve sends conversion.successful or conversion.failed.

Create a conversion

POST /v1/conversions
string
required
A unique key for this conversion. Reuse it on every retry.
string
required
The wallet to debit.
string
required
The wallet to credit.
integer
required
The amount in sourceCurrency, in minor units.
string
required
Your own reference, up to 255 characters.
string
A quote for the same currencies and amount.
object
Your own key-value data.
Response · 202
integer
Use this in URLs: GET /v1/conversions/{id}.
string
The cnv_ id.
string
pending, processing, successful or failed.
string
What leaves the source wallet, in minor units.
string
What reaches the destination wallet, in minor units.
string | null
The exchange rate applied.
string
Payve’s fee, in minor units.
202 means accepted. The destination wallet is credited only when the conversion is successful. Do not start a payout from the destination wallet until then.

Wallets

Payve creates the source and destination wallets if you do not have them. The source wallet must hold the amount.

Convert, or pay out across currencies?

Get and list conversions

When it fails

A conversion can also be accepted and fail afterwards. You then receive conversion.failed. Check both wallet balances before you try again.

Cautions

Do not retry a conversion with a new idempotency key after a timeout. Retry with the same key. A second conversion under a new key converts the money twice.
Use a merchantReference that names the purpose and date, such as treasury-2026-11-18. It appears on your statement.