Bulk Payout Flow

Send high-volume supplier payouts safely by assigning unique request identifiers, respecting route constraints, and reconciling outcomes through webhook-driven status updates.

✅ Before you start

Complete these steps before you submit bulk payouts:

1. Make sure each supplier already has a valid beneficiary record.
2. Confirm the source wallet has enough balance for the full batch or planned batch segment.
3. Generate a unique Idempotency-Key for every payout item, not just for the batch as a whole.
4. Register a webhook endpoint so you can reconcile payout outcomes asynchronously.

graph TD
    A[Partner ERP] -->|1. Submit batch| B[Verto Queue]
    B -->|2. Process asynchronously| C{Rail Selection}
    C -->|Local| D[FPS or SEPA Instant]
    C -->|Global| E[SWIFT]
    D -->|3. Webhook| F[Payment Success]
    E -->|3. Webhook| F[Payment Success]

🛡️ Step 1: Initialize ID-Backed Transfers

For every transfer in your bulk file, assign a unique Idempotency-Key. This prevents double-funding if your server retries a request after a timeout.

# Example for a single item in a loop
curl -X POST https://api.sandbox.vertofx.com/v2/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp_payout_ref_7788" \
  -d '{
    "amount": "1200.50",
    "currency": "USD",
    "recipient_id": "ben_id_abc"
  }'

Store the returned payout or transaction identifier alongside your internal ERP reference so you can reconcile later webhook updates against the correct supplier payment.

📑 Step 2: Handle Regional Rail Constraints

🏁 Step 3: Reconcile via Webhooks

Instead of polling for every payout, use webhook-driven updates to reconcile payout progress and completion.

{
  "eventType": "wallet_to_account",
  "payload": {
    "transaction_id": "tx_99b",
    "status": "completed",
    "amount": "1200.50"
  }
}

Use webhook delivery as the source of truth for final payout state, especially when a request times out or a batch spans multiple settlement windows.

🎯 Best Practices

1. Batching: Send payments in batches of 50 for optimal API performance.
2. Retry Logic: Use exponential backoff for 5xx errors.
3. Audit Trail: Log the verto_tx_id returned in the response alongside your Idempotency-Key.
4. Failure Isolation: Retry only the failed payout items, not the full batch, and keep the original Idempotency-Key for any retried item.

Troubleshooting