Single-step flow: Exchange & Payout API

This guide covers the single-step payout flow — where FX conversion and disbursement are executed in a single API call. If you prefer to manage the FX and payout steps separately, see the Two-step flow: FX + Payout API guide

Step 1 — Validate the beneficiary account (optional, NGN only)

Before creating a beneficiary, you can validate the destination account details using the Get Account Name endpoint. This returns the account holder name linked to the account number, which can be displayed to the sender for confirmation.

This step is optional and currently supported for NGN local payouts only.

Step 2 — Create a beneficiary

Create a beneficiary record using the Create Beneficiary endpoint. The beneficiaryId returned will be used when submitting the payout.

Beneficiary requirements vary by market — some corridors require specific bank codes, branch identifiers, or intermediary information.

See the Bank codes & market requirements guide for a full breakdown by country.

Once created, a beneficiary can be reused across multiple payments. Note that only beneficiaries with a status of approved can receive payments.

Step 3 — Get an FX rate

Request a live FX rate using the Get FX Rate endpoint. You must specify either the amount you are selling or the amount you want your recipient to receive, along with the respective currencies.

A successful response will return a quoteId which locks the rate for your transaction.

⚠️

Quote expiry

FX quotes are valid for 30 seconds by default. You must submit your payout request within this window or the quote will expire and you will need to request a new rate. If your use case requires a longer quote window, this may be possible — contact your account manager, noting that an extended window may come at an increased margin.

Step 4 — Execute the payout

Using the quoteId from Step 3, submit your payout request using the Create FX transaction endpoint. The quoteId is the only value required to tie the rate to the payment. Before submitting, call the purpose of payment endpoint to retrieve the correct purposeId for your transaction.

Document uploads

For high-value payouts or payments to higher-risk corridors, attaching supporting documentation is strongly recommended. For clients using downstream payment services, document upload may be mandatory depending on the compliance conditions set during your approval. Use the Generate Upload Link endpoint to obtain a pre-signed upload URL, then include the document reference in your payout request.

See the Document upload guide for full details.

⚠️

Fintech & FI use cases — sender object required

If you are making a payout on behalf of an underlying customer, you must include the sender object in your request. This applies to all downstream payment flows, including the return of funds back to the original sender. Omitting this will cause the payment to be flagged. If you are unsure whether this applies to your integration, contact your account manager before going live.

See the Sender object guide for full details.

Step 5 — Track payment status

API response states

Webhook transaction states

💡

Note on funding method

If your funding method is instant, your payment will move directly to inward_remittance_confirmed without passing through inward_remittance_pending. Where funding is non-instant, the rate is still binding once booked — Verto will hold the rate while awaiting your funds.

⚠️

Archived payments

Archived covers both cancellations and outward payment failures. Contact your account manager if you are unsure of the cause or whether a new payment needs to be initiated.

📘

Compliance holds

On rare occasions, payments may be held for compliance review. Verto will reach out with an RFI if this occurs. You can check payment status at any time using the paymentId via the Get Payment endpoint.