📥 Receive Infrastructure

Issue account details for a wallet, receive inbound funds through supported rails, and reconcile the resulting credit into your application.

✅

Optimized for Atlas Platforms

Create thousands of unique collection accounts for your sub-accounts, with automated notifications and ledger settlement.

✅ Before you start

Complete these steps before you build your receive flow:

1. Create the wallet that will receive inbound funds.
2. Issue the local or global account details for that wallet.
3. If you are collecting for a downstream customer, create and approve the sub-account first.
4. Register a public HTTPS webhook endpoint so you can process inbound settlement events.

🏦 Local vs. Global Rails

A single Verto wallet can be linked to multiple account details. Understanding which rail to use is key to ensuring fast settlement and low fees.

1. Local Account Details

These enable transfers via domestic payment rails.

• GBP: Faster Payments, BACS, CHAPS.
• EUR: SEPA and SEPA Instant.
• NGN: NIBSS and eTranzact. Settlement is typically near-instant to 2 hours.

2. Global Account Details

These utilize the SWIFT network. They are best for international business-to-business (B2B) payments where a local rail is not available. Settlement typically takes 1-5 working days.

🧬 Dedicated vs. Pooled Accounts

When you generate account details for a wallet, they will fall into one of two categories:

[!WARNING] Allocation Failure: For Pooled accounts, if the payer omits the SmartWallet ID in the transfer narration, the payment will be automatically returned to the sender by our compliance systems.

🚀 Integration Workflow

1. Wallet Creation: Provision a ledger container.
2. Account Issuance: Generate domestic bank details. To auto-create details, pass autoCreate=true when calling the fetch endpoint.
3. Webhook Listening: Respond to iban_to_wallet events for incoming settlements.
4. Auto-Reconciliation: Update your user's balance in real-time.

# Example: Generate a GBP Local Account for a Sub-Account
curl -X POST https://api.sandbox.vertofx.com/v2/accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Sub-Account-Id: sub_acc_990" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "GBP",
    "type": "local"
  }'

After issuance, store the returned account identifiers with the wallet that owns them and display the exact sender instructions in your UI.

Handle the inbound settlement event

Use the webhook event to update your balance only after the settlement reaches the completed state.

{
  "eventType": "iban_to_wallet",
  "payload": {
    "walletId": "wal_gbp_778",
    "amount": "5000.00",
    "currency": "GBP",
    "status": "completed",
    "reference": "INV-20260401"
  }
}

🧹 Automated Funds Sweeping

In a sub-account architecture, it is best practice to "Sweep" funds once they arrive.

The Sweep Flow:

1. Listen: Monitor the inbound_payment webhook.
2. Verify: Wait for the status to reach completed.
3. Transfer: Immediately initiate a Wallet-to-Wallet Transfer to move funds from the Sub-Account wallet to the Master wallet.

Only sweep after your receive webhook confirms the funds have been applied to the wallet you expect.

⏱️ Settlement & Fees

• Real-Time: KES (M-Pesa), GBP (FPS), AUD (NPP).
• Standard (T+1): EUR, USD, NGN.
• Reporting: Access full transactional audit logs via the GET /v2/statements endpoint.

Troubleshooting

🎯 Next Steps