Build Cross-Border Remittance Flows

Use this flow when you need to fund a remittance payout, create or validate a beneficiary, convert currency if required, and dispatch funds with the right sender and reconciliation controls in place.

✅ Before you start

Complete these steps before you implement the remittance flow:

Confirm whether your programme fits Atlas for Fintech or Atlas for Platforms based on your licence status and compliance ownership.
Authenticate with the merged Login service and store the returned token and companyId.
Decide whether payouts will be sent from your own wallet context or on behalf of downstream customers.
Collect the sender and beneficiary data required for the target payout corridor.
Make sure the source wallet exists and can be funded for the payout flow.
Register webhook endpoints so you can track payout state changes without polling.
Generate a unique paymentId or idempotency key for every payout or FX trade request.

Use Environments to configure the merged service hosts for Login, Wallet, Beneficiary, Exchange, and Onboarding.

📚 Use this page with the recipe

This guide explains when to use the remittance flow and the minimum sequence. For the implementation walkthrough, use the recipe:

Build Cross-Border Remittance Flows Recipe →

🧭 Which model usually fits?

Model	Use it when	Operational pattern
Atlas for Fintech	You are a licensed financial institution and you own the customer relationship and compliance process.	Run the flow from your own wallet context, then convert and send the payout directly.
Atlas for Platforms	You are operating a customer-facing flow for downstream users and need customer-level segregation.	Create and scope actions to sub-accounts before you collect, convert, or pay out.

If you have not confirmed the right model yet, start with Choose the right APIs and KYC & Compliance Requirements.

The remittance workflow

This use case follows a simple sequence:

Choose the account context for the payout: your master wallet for direct flows, or a downstream customer context for platform flows.
Confirm the source wallet with Get all Wallets or create one with Create wallet.
Create and validate the beneficiary with Create beneficiary and Fetch beneficiary by ID.
Check beneficiary readiness before payout selection.
Fetch an FX quote and execute the conversion with Get FX rate and Create FX trade if the source wallet currency differs from the payout currency.
Store the paymentId and FX trade reference for support and reconciliation.
Reconcile final state through webhooks before you mark the transfer as complete in your application.

Check these fields before moving funds:

Object	Fields to check
Wallet	`availableBalance`, `currency`, `isDisabled`
Beneficiary	`verificationState`, `isAccountActive`, `isArchived`, `isUpdateRequired`, `paymentMode`
FX trade	`paymentId`, `reference`, `state`, `inwardSettlementTime`, `outwardSettlementTime`

What makes this use case different?

Unlike a generic payout flow, remittance programmes usually need to:

capture sender information alongside the payout
validate corridor-specific beneficiary routing data up front
support beneficiary remediation when isUpdateRequired is true
use the short-lived vfx_token before it expires when FX is required
treat webhook-confirmed payout states as the operational source of truth

Optional: Add downstream customer segregation

If your remittance product needs customer-specific balances or onboarding, create a sub-account first and keep beneficiary creation, FX, and payouts linked to that downstream customer context in your own system.

Use this pattern only when your approved model supports downstream customer segregation.

Where to go deeper

Use the product guides when you need implementation detail for a specific step:

Troubleshooting

Issue	What to check
Payout is rejected immediately	Confirm the beneficiary routing data, sender details, payout currency, and beneficiary readiness fields match the target corridor requirements.
Conversion cannot be booked	Check whether the `vfx_token` is still valid and whether the source wallet has enough `availableBalance`.
Request times out	Reconcile using the same `paymentId` or idempotency key before retrying with a new identifier.
Wrong customer context is debited	Verify whether the wallet, beneficiary, FX trade, and payout were linked to the correct master or downstream customer context.
Transfer remains under review	Move the item into your RFI workflow and wait for the next status update before retrying.

Next steps


End-to-End Payment Flow → Follow the direct own-funds payout pattern.	Sub-Accounts → Use the customer-scoped pattern when you need downstream isolation.

Talk to Verto

Get help with authentication, receive flows, wallets, FX conversion, payouts, or Atlas platform setup.

Plan your go-live

Review the requirements you need before moving your integration into production.