⚙️ Receive Integration Guide

Set up wallet-based collections, issue account details, receive inbound funds, and reconcile the resulting wallet credit in your application.

✅ Before you start

Complete these steps before you implement the receive flow:

1. Authenticate successfully with your Verto credentials.
2. Create the wallet that will receive inbound funds.
3. If you are collecting for a downstream customer, create and approve the sub-account first.
4. Decide whether the flow will use local account details, global account details, or pooled collection instructions.
5. Register a public HTTPS webhook endpoint that can accept inbound settlement events.

🔀 Accounts vs. Receive — What's the Difference?

These are two distinct but complementary concepts:

💡

Think of Accounts as the address and Receive as the delivered parcel.

1️⃣ Provision a Receiving Wallet

Every collection must flow into a currency-specific ledger.

• Header: Use X-Sub-Account-Id if creating for a user.
• Tip: One wallet can handle thousands of virtual accounts.

Store the wallet ID from the creation response because you will use it for account issuance, reconciliation, statements, and any later transfer or payout flow.

2️⃣ Generate Virtual Bank Details

Call the accounts gateway to "issue" the bank details (IBAN/Account Number).

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"
  }'

Store the returned account details with the wallet record that owns them and display the exact collection instructions to the payer.

3️⃣ Present Instructions to Customer

Display the returned metadata (Account Holder, IBAN, Sort Code) in your UI.

⚠️

Critical: Always remind the user to include the specific Payment Reference if using a pooled account.

Show only the fields returned for that corridor. Depending on the rail, this can include IBAN, account number, sort code, routing number, SWIFT details, or a required payment reference.

4️⃣ Configure Webhook Listeners

Listen for the payment_received (or iban_to_wallet) event.

// Node.js Express Example
app.post('/webhooks/verto', (req, res) => {
  const { eventType, payload } = req.body;
  if (eventType === 'iban_to_wallet' && payload.status === 'completed') {
    // 🏦 Crediting the user...
    console.log(`Received ${payload.amount} ${payload.currency}`);
  }
  res.sendStatus(200);
});

Return 200 OK quickly, then continue processing asynchronously so retries do not create duplicate internal updates.

5️⃣ Real-Time Reconciliation

Update your internal ledger the moment the webhook hits. Verto's webhooks provide the sub_acc_id and wallet_id for automated mapping.

Only mark the funds as available when the webhook status reaches completed. Deduplicate deliveries by event ID before you update balances.

6️⃣ Sweep & Consolidate (Optional)

For Platform models, most partners "Sweep" user funds from the Sub-Account wallet to a Parent Master wallet for centralized FX conversion or treasury management.

Sweep only after the inbound collection has been fully reconciled to the expected wallet and customer context.

Troubleshooting

🎯 Next Steps