Send Infrastructure

Send funds from a Verto wallet to an external beneficiary, convert currency when needed, track the payout state, and handle retries safely when a transfer is delayed or fails.

[!WARNING] Stage 2 Approval Required Third-party payouts (paying on behalf of others, e.g., marketplace disbursement) require Advanced Flow Approval. Go-Live Requirements →

✅ Before you send funds

Complete these steps before you initiate a payout:

1. Make sure the source wallet exists and has enough availableBalance for the transfer.
2. Validate the beneficiary data for the target corridor using the merged Beneficiary service.
3. Check beneficiary readiness: verificationState, isAccountActive, isArchived, and isUpdateRequired.
4. If the payout requires FX, request a live FX rate and use the returned vfx_token before it expires.
5. Generate a unique paymentId or idempotency key for the payout or FX trade request.
6. Retrieve or store the purpose code when the payout corridor requires a declared transfer purpose.

🔀 Send vs. Payments — What's the Difference?

🏛️ Payout Modalities

Verto supports multiple payout tiers based on your business model:

1️⃣ Direct / Corporate Payouts (Own Funds)

Your company paying your own suppliers, contractors, or operational overheads using your own corporate funds. This is a first-party, direct integration use case — you are the payer and the account holder.

• Status: Standard access.
• Example: Paying your SaaS vendors, staff expense reimbursements.

2️⃣ Third-Party Payouts (Atlas Platform)

Dispatching funds on behalf of your sub-accounts (e.g., Paying a supplier for a merchant on your platform).

• Status: Requires Stage 2 Approval.

3️⃣ Bulk Payouts

Dispatching thousands of payments in a single atomic batch.

• Use Case: Payroll or platform-wide disbursements.

🗺️ Global Rail Matrix

⚡ Implementation Workflow

A standard orchestration transaction follows a strict sequence to ensure destination details are valid, funds are available, and FX is executed before payout when required.

Step 1: Account Validation (Optional but Recommended)

For markets like Nigeria, validate the recipient's bank details before initiating the payout to reduce failed destination errors. Use Get account name:

{
    "bankCountry": "NG",
    "bankCode": "000003",
    "accountNumber": "4713920010"
}

Step 2: Lock the Exchange Rate

Retrieve a live quote with Get FX rate. Verto returns a vfx_token. Use this token within approximately 30 seconds when you create the FX trade.

Step 3: Create the Beneficiary

Create the recipient with Create beneficiary, then store the returned id, reference, verificationState, and paymentMode.

[!TIP] Performance Tip: For recurring users, store the beneficiary_id in your database. You do not need to create a new beneficiary for every transfer to the same person.

Step 4: Execute FX payout with sender details

When the payout requires currency conversion, use Create FX trade with paymentType: "convertWalletPayout". Include the vfx_Token, destination beneficiary ID, unique paymentId, and sender details where required.

curl --request POST https://api-exchange-now-sandbox.vertofx.com/fx/payments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentType": "convertWalletPayout",
    "sourceWalletId": 3064,
    "sourceAmount": 10000,
    "purposeId": 45,
    "vfx_Token": "YOUR_VFX_TOKEN",
    "targetAccountId": 3772,
    "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f",
    "sender": {
      "name": "Jane Doe",
      "country": "US",
      "address_city": "New York",
      "customerIdentificationNumber": "A998273"
    }
  }'

{
  "paymentType": "convertWalletPayout",
  "sourceWalletId": 3064,
  "sourceAmount": 10000,
  "purposeId": 45,
  "vfx_Token": "YOUR_VFX_TOKEN",
  "targetAccountId": 3772,
  "paymentId": "35448e78-8180-4ce5-8671-772c29ad658f",
  "sender": {
    "name": "Jane Doe",
    "country": "US",
    "address_city": "New York",
    "customerIdentificationNumber": "A998273"
  }
}

Store the returned FX trade reference and paymentId so you can retrieve the trade later with Get FX trade details.

Planned sender detail validation

The following sender-detail validation is planned and is not enforced. Document these rules now so your implementation is ready when validation is enabled.

Sender details are mandatory for Atlas for Fintech - Global Clearing use cases. They are not required for Atlas for Platforms, Atlas for Fintech sub-account flows, direct corporate non-Atlas flows, or first-party activity by financial institutions unless Verto tells you otherwise.

Across sender fields, use Latin characters in free-text values. Avoid special characters outside the supported Latin character set unless Verto confirms support for your route.

Treat sender detail requirements as corridor- and compliance-dependent. If a request enters review or requires additional information, follow Handle RFIs and Compliance Exceptions.

⚖️ Managing Payout States

Your application logic should respond to the following state transitions:

Use webhook-driven updates where possible so your UI and internal ledger stay in sync with the payout lifecycle.

For FX-backed payouts, use List FX trades for operational reporting and Get FX trade details for one trade. Keep webhook events as the source of truth for final payout state where asynchronous state changes are available.

[!CAUTION] Handling RFIs: If a payment stays in Requested longer than your approved review threshold, check your internal compliance workflow and Verto support channel for any pending Request for Information (RFI) regarding the sender or recipient. See Handle RFIs and Compliance Exceptions for the recommended exception state machine and safe-retry rules.

🛡️ Idempotency & Safety

🛡️

Avoid duplicate payouts Always use a unique paymentId or idempotency key for write requests. If a network timeout occurs, check the original request state before retrying with a new identifier.

Troubleshooting

🎯 Next Steps