Sub-Accounts & Atlas Deep Dive

Create sub-accounts to isolate balances, compliance records, and transaction activity for each downstream customer in your Atlas platform integration.

[!IMPORTANT] Sub-Account Context Every operation performed within a sub-account (Wallets, Exchange, Payout) must be scoped using the X-Sub-Account-Id header to ensure total data isolation.

✅ Before you create a sub-account

Complete these steps before you start the sub-account lifecycle:

1. Authenticate with your master platform credentials.
2. Confirm your integration is using the Atlas platform model, not a direct own-funds flow.
3. Decide what customer data and KYB or KYC information you will collect before onboarding.
4. Prepare to store the returned sub-account ID because you will use it to scope wallets, receive flows, exchange actions, and payouts.
5. If your create-sub-account request includes subCategory, validate it against Verto's supported industry classifications before sending the request.

[!NOTE] Before you begin development work, confirm with your sales contact or account manager which compliance level your integration is approved for.

[!IMPORTANT] Industry classification validation If your integration sends subCategory during sub-account creation, the value must exactly match one of Verto's supported industry classifications. Otherwise, the API can return an invalid-input error.

Use this list when building your payload: Supported Industry Classifications

🔄 The Sub-Account Lifecycle

Moving a user from "Registered" to "Transacting" follows a strict pipeline managed by Verto Compliance.

1️⃣ Create the sub-account

Start by creating the customer container that will own the downstream ledger context.

curl -X POST https://api.sandbox.vertofx.com/v2/sub-accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TechStartup LLC",
    "country": "United Kingdom",
    "subCategory": "Advertising & marketing company",
    "identificationNumber": "UK12345678",
    "accountType": "sub_client"
  }'

Store the returned sub-account ID and use it in the X-Sub-Account-Id header for all later actions that belong to that customer. subCategory must exactly match a value from Supported Industry Classifications.

If you need the field-by-field schema for the creation request, use Create a Sub-Account alongside the API reference.

💳 Phase 2: Wallet & Liquidity Setup

Once the sub-account is ACTIVE, you can begin moving value.

1. Issue Multi-Currency Wallets: Create wallets (e.g., USD, NGN) for the sub-account. These serve as the ledger for that specific user.
2. Funding: Fund these wallets via Direct Collection (assigning dedicated IBANs) or through Master-to-Sub Account Transfers from your platform's master wallet.

Do not attempt wallet creation, account issuance, or payout execution until the sub-account has reached an operationally approved state.

💸 Phase 3: The Payout Lifecycle

To enable users to pay suppliers globally:

1. Create a Beneficiary: Ensure bank code routing logic relies on Sort Code for GBP local, Routing Number for USD local, or SWIFT/BIC for international transfers.
2. Fetch Live FX Rates: Get a vfx_token which locks the rate for 30 seconds before conversion.
3. Execute Payout: Debits the sub-account wallet.

{  
  "beneficiaryId": 3772,  
  "purposeId": 12,  
  "amount": 10000,  
  "walletId": 3064,  
  "clientReference": "TX-9982"
}

When you execute the payout or create the beneficiary for that customer, keep the same sub-account context so the correct ledger is debited and the correct audit trail is preserved.

🔔 Phase 4: Webhook Orchestration

Platforms should never poll for status. Implement the following webhook listeners:

• transaction_state_change: Track Payouts from requested to completed.
• sub_account_approved: Trigger your internal UI to unlock the dashboard.
• inbound_payment: Notify your user when funds arrive in their collection account.

Use these events to unlock product access, update balances, and reconcile downstream user activity without manual polling.

⚡ Operational Scoping (Master-Sub Model)

Verto Atlas uses a Master-Sub relationship model. To perform an action on behalf of a sub-account, you must use their unique ID in the request header via X-Sub-Account-Id.

# Example: Creating a wallet for a specific Sub-Account
curl -X POST https://api.sandbox.vertofx.com/wallets \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Sub-Account-Id: sa_789_xyz" \
  -H "Content-Type: application/json" \
  -d '{"currency": "USD"}'

This same header pattern applies when you issue accounts, fetch statements, create beneficiaries, or send payouts for that sub-account.

⚖️ Compliance States

A sub-account's ability to move funds is strictly tied to its compliance status.

Troubleshooting

🎯 Next Steps