Scaling Beneficiary Management

Create validated beneficiary records with the merged Beneficiary service, match the right bank-routing or stablecoin fields to each corridor, and reuse approved beneficiaries safely across payout flows.

✅ Before you create a beneficiary

Complete these steps first:

1. Confirm the payout country and currency for the transfer you want to send.
2. Collect the bank-routing fields required for that corridor.
3. Decide whether you are creating a bank beneficiary or a stablecoin beneficiary.
4. Get the currencyId and choose the correct paymentMode for the destination.
5. Use the Beneficiary sandbox host: https://api-beneficiary-sandbox.vertofx.com.

graph TD
    A[Partner App] -->|Query| B{Country Rules}
    B -->|US| C[ABA/Routing]
    B -->|UK| D[Sort Code]
    B -->|EU| E[IBAN]
    C --> F[POST /recipients]
    D --> F
    E --> F

1️⃣ Match the corridor to the correct destination data

Validate these fields before you create the beneficiary. Most payout failures start with incorrect, incomplete, or stale destination data.

🧬 Beneficiary Status Workflow

When a beneficiary is created, it enters a validation state machine. Use only approved, active beneficiaries for payout selection unless your workflow explicitly supports review handling.

• Pending: Beneficiary has been submitted and is awaiting review or verification.
• Approved: Beneficiary is available for supported payment flows, subject to isAccountActive, isArchived, and isUpdateRequired checks.
• Rejected: Beneficiary failed verification or cannot be used without correction.

Check these readiness fields before showing a beneficiary in a payment UI:

2️⃣ Create the beneficiary object

Create the beneficiary before you initiate the payout so you can validate and store the destination details once.

curl --request POST https://api-beneficiary-sandbox.vertofx.com/recipients \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currencyId": 4,
    "beneficiaryType": "company",
    "paymentMode": "LOCAL",
    "partyType": "Third_Party",
    "accountNumber": "9988001122",
    "bankCode": "112233",
    "bankName": "Beneficiary Bank",
    "companyName": "Jane Doe Consulting",
    "bankAddress": {
      "countryCode": "GB"
    },
    "beneficiaryAddress": {
      "countryCode": "GB",
      "city": "London",
      "postCode": "SW1A 1AA",
      "addressLine1": "10 Example Street",
      "email": "[email protected]"
    }
  }'

When this request succeeds, store the returned beneficiary id, reference, paymentMode, and verificationState. Reuse the beneficiary for later payouts instead of recreating the same recipient every time.

3️⃣ Verify the account where supported

For supported regions, Verto can perform account-name validation to help confirm destination details before you create or use a beneficiary.

For Nigerian bank accounts, use Get account name before beneficiary creation when you need to confirm the account name tied to an account number and bank code.

Scoped beneficiaries for platform flows

For Atlas Platform partners, keep beneficiary ownership and payment context explicit in your system. Store the beneficiary id, reference, associated customer or company context, and allowed paymentMode so downstream payment flows select the correct destination.

Manage existing beneficiaries

Use the merged Beneficiary service for the full beneficiary lifecycle:

Use Fetch beneficiary by ID before payment submission if you need the latest readiness state.

Troubleshooting