Two-step flow: FX + Payout API

This guide covers the two-step payout flow — first funding your payout currency (Part A), then executing the payout to your recipient (Part B). If you want to combine both steps into a single API call, see the Exchange & Payout API guide.

Part A — Fund your payout currency

Before initiating a payout, your Verto wallet must hold a balance in the destination currency. There are three ways to achieve this:

1. Local funding (send funds directly in the payout currency)

If local funding is supported for your target currency, you can fund your Verto wallet by sending funds directly in that currency via bank transfer. This may be subject to commercial arrangements — confirm availability with your account manager before integrating.

2. Book FX via the Verto platform

If you hold a balance in another currency, you can convert to your payout currency using the Verto platform directly:

• Exchange Now — execute a live market conversion instantly.
• OTC (Over the Counter) — for larger or more bespoke conversions, work directly with the Verto trading desk.

Both options settle into your Verto wallet and are available without additional API integration.

3. Book FX via the FX API

For automated or high-volume workflows, use the FX API to programmatically book a wallet-to-wallet conversion before initiating your payout.

1. Call Get FX Rate to retrieve a live rate for your currency pair.
2. Call Book FX to lock and execute the conversion. Funds will settle into your target wallet.

See the FX Booking guide for full details on wallet-to-wallet FX.

Once your wallet holds a balance in the payout currency, proceed to Part B.

Part B — Execute the payout

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 — Check your wallet balance

Before initiating a payout, confirm your wallet has sufficient funds using the Get Wallet endpoint. You will receive an insufficient funds error if your balance is too low.

Step 4 — Request a payout

Submit a payout to your beneficiary using the Create Payment Request endpoint. Specify the walletId to debit, the beneficiaryId, amount, and a unique paymentId. Before submitting, call the purpose of payment endpoint to retrieve the correct purposeId for your transaction.

The payment will be created with a status of requested.

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 information guide for full details.

Step 5 — Track payment status

API response states

Webhook states

⚠️

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 or by waiting for webhooks to saving status in your system.