Create Sub-Account Wallets

Once a sub-account is Active, you must provision at least one wallet before they can receive or move funds. Each wallet is a single-currency container (e.g., KES, NGN, USD).

✅ Before you create the wallet

Complete these steps first:

1. Create the sub-account and make sure it is ready for wallet provisioning.
2. Authenticate with your master credentials or a scoped sub-account session.
3. Decide which currency the customer needs for receive, exchange, transfer, or payout flows.
4. Make sure you have the correct X-Sub-Account-Id for the customer that should own the wallet.

🚀 Implementation Details

Send a POST request to the wallets endpoint with the sub-account's unique context.

curl -X POST https://api.sandbox.vertofx.com/v2/wallets \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Sub-Account-Id: sub_acc_789" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "KES",
    "type": "standard",
    "customerReferenceLabel": "Kenya Operating Wallet"
  }'

When this request succeeds, store the returned wallet ID because you will need it for account issuance, receive flows, transfers, statements, FX conversion, and payouts.

To verify the wallet later, use the migrated wallet service lookup routes:

Do not use the legacy api-v3-sandbox.vertofx.com/profile/v2.2/wallets routes for new wallet list or wallet detail integrations.

🏛️ Header Context

🛡️

Authorization Strategy You have two ways to create a wallet for a sub-account:

1. Master Auth + Header: Use your master token and include X-Sub-Account-Id.
2. Scoped Auth: Login as the sub-account first, then call the endpoint with the resulting token.

🗺️ Supported Currencies & Rails

The capabilities of a sub-account wallet depend on the underlying regional rail.

Choose the wallet currency based on the next action the customer needs to perform. For example, create a wallet before issuing account details for collections or before debiting funds for a payout.

💸 Debiting a Sub-Account Wallet

To debit funds from a sub-account wallet (e.g., to pay a supplier), execute a Payout. You must provide the X-Sub-Account-Id header to ensure the correct ledger is deducted.

curl -X POST https://api.sandbox.vertofx.com/v2/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Sub-Account-Id: sub_acc_789" \
  -d '{
    "beneficiaryId": 3772,  
    "purposeId": 12,  
    "amount": 10000,  
    "walletId": 3064,  
    "clientReference": "TX-9982"
  }'

[!TIP] Purpose Code Logic: Different regulatory corridors require specific purpose codes. Before debiting the wallet for cross-border transactions, query the migrated purpose-code route, GET https://api-payment-preview.vertofx.dev/payments/purpose-codes, to fetch the required purposeId.

What to do after wallet creation

After the wallet exists, continue with the flow that matches your product:

1. Issue account details if the customer needs to receive funds.
2. Fund the wallet through a receive flow or internal transfer.
3. Use the wallet ID in exchange, statement, transfer, or payout requests.

Troubleshooting

🎯 Next Steps