Wallet Service

Wallet Service

Wallets hold your balances, one currency at a time. The Wallet Service lets you create wallets, generate the account details your senders use to pay in, and look up balances and statements. Wallets work the same way on a parent account and on a sub-account. For a sub-account, authenticate as the sub-account first.

📘

Each Verto service has its own host. Sandbox hosts end in -sandbox.vertofx.com, and the matching production host replaces sandbox with beta. Sending a request to the wrong environment returns a 403.


How it fits together

  1. Create a wallet in the currency you want to receive
  2. Get account details for that wallet: a unique virtual account where available, or pooled account details if not
  3. Share the details with whoever is sending you money
  4. Funds arrive, a webhook fires, and the payment goes through compliance checks (requested status)
  5. Funds are credited to the wallet once the checks clear, with another webhook sent (completed status)

1. Create a wallet

Call Create a Wallet with your companyId in the path. You get the companyId from your login response.

{
  "currency": "KES",
  "type": "standard",
  "customReferenceLabel": "Customer collections"
}
FieldDescriptionMandatory
currency3-character ISO 4217 currency codeYes
typestandard for everyday transactionsYes
customReferenceLabelYour own name for the wallet (up to 75 characters). If you leave it out, Verto generates one from the currency (NGN Wallet 2, 3 ext)No

The response returns the new wallet's ID. Store it, because you'll use it for receiving funds, FX, transfers and payouts. You can look up wallet IDs again at any time with Get all Wallets.

💡

We recommend always creating wallets explicitly through the API, so your integration works the same way regardless of which currencies have default wallets. The first wallet you create in a currency becomes the default wallet for that currency, which is used for billing and post-funded FX deals.

Not every currency can be held in a wallet. See Wallets and Currency coverage for details.


2. Get account details for a wallet

A wallet can receive funds once it has account details. Call Get all funding methods with the companyId and walletId in the path.

GET /{companyId}/wallets/{walletId}/fundingMethods?autoCreate=true
ParameterDescription
autoCreateMust be true to generate new account details. Leave it out to view the details a wallet already has
partnerProductOptional. For NGN wallets, selects the bank partner for the account (FCMB-NGN-1 or PAGA-NGN-2)

Unique virtual account first, pooled account if not

  1. Request a unique virtual account. Call the endpoint with autoCreate=true. Where a unique virtual account is available for the wallet's currency, Verto generates it and returns the details. These are dedicated to your wallet, so funds credit automatically and the sender doesn't need a payment reference.
  2. If unique details aren't available, the request returns an error. This means the currency is served by a pooled account instead.
  3. Use the pooled account details. Call the same endpoint without autoCreate to retrieve them. Pooled accounts are shared Verto accounts, so the details include a SmartWallet ID.
⚠️

For pooled accounts, the sender must include the SmartWallet ID in the payment reference on every transfer. Verto uses it to match the payment to your wallet. Without it, the funds can't be allocated automatically and are returned to the sender after a period of non-claiming. If you think funds have arrived but not been credited, contact [email protected]

A single wallet can have several sets of details at once. For example, local, SWIFT and pooled details can all be active on the same wallet.

See Virtual accounts vs pooled accounts and Funding wallets for the full picture, including SWIFT, mobile money and stablecoin funding.


3. When funds arrive

When a payment lands in one of your wallets, Verto sends a webhook so you know straight away. Subscribe to webhooks instead of polling for balances.

EventWhat it means
requestedThe payment has arrived and is under compliance review. It has not been credited to the wallet yet
completedThe payment cleared compliance review and has been credited to the wallet
disputedThe payment has been flagged for investigation and is on hold
archivedThe payment was rejected, and the funds are returned to the sender

Each payload includes the walletId and companyId, so you can tell exactly which wallet and which client was credited. Where the sending bank provides sender details, they're included too, which makes it easier to reconcile against what you expected.

💡

Treat completed as the point the money is yours to use. requested only tells you the payment has arrived.

See Bank Account to Wallet webhooks and the Webhooks guide for payloads and setup.


4. Compliance checks on inbound funds

All inbound payments are screened before they're credited. This is why a payment shows as requested first and only moves to completed once the checks clear. Most payments clear quickly, but some need further review and take longer. If Verto needs more information, you'll be contacted with a request for information (RFI).

Two other things can stop an inbound payment from being credited:

  • Funding rules. Each account has rules about who can send it funds, covering first-party versus third-party senders and individual versus corporate senders. These are set automatically from your risk review and apply to parent accounts and sub-accounts alike. A payment from a sender outside your rules may be rejected and returned.
  • Missing SmartWallet ID. Payments to a pooled account without the SmartWallet ID in the reference can't be allocated automatically.

In this section

EndpointDescription
POST Create a Wallet (New)Create a wallet in a given currency
GET Get all Wallets (New)List the wallets on an account and their IDs
GET Get specific Wallet DetailsFetch a single wallet, including its balance
GET Get all funding methods (New)View or generate the account details used to fund a wallet
POST Request Wallet StatementRequest a statement for a wallet
GET Fetch wallet statementsRetrieve