Atlas for Platform — Receiving Funds

This guide covers generating collection account details for your sub-account wallets and monitoring incoming payments via webhook.

📘

Authenticate as the sub-account using the

Sub-Account Login endpoint before proceeding. Use the returned JWT token in all requests.

Step 1 — Create a wallet

Before generating collection account details, create a wallet for the sub-account using the Create Wallet endpoint.

The response returns a unique walletId used in the next step.

💡

We recommend always creating wallets explicitly via API to ensure a consistent

implementation regardless of which currencies have default wallets.

Step 2 — Generate collection account details

Call the Get Funding Methods endpoint with autoCreate=true to generate collection account details for the wallet.

GET /:companyId/wallets/:walletId/fundingMethods?autoCreate=true

⚠️

autoCreate must be set to true to generate new account details. Without

it the endpoint will only return existing details.

Verto supports two types of collection account details depending on the market:

Unique virtual accounts

Dedicated account details tied exclusively to the sub-account wallet. Any funds sent to these details are automatically credited — no payment reference required.

{
  "id": 4563,
  "accountType": "local",
  "fundsType": "segregated",
  "accountName": "Acme Logistics Ltd",
  "accountNumber": "96566547",
  "bankCode": "608382",
  "bankName": "BankingCircle",
  "smartWalletRef": null
}

Pooled accounts with SmartWallet ID

For markets where unique virtual accounts are not available. The sender must include the smartWalletRef in the payment reference of every inbound transfer. Verto handles reconciliation automatically.

{
  "id": 4562,
  "accountType": "local",
  "fundsType": "pooled",
  "accountName": "Verto Pooled Account",
  "accountNumber": "12345678",
  "bankCode": "608382",
  "smartWalletRef": "SW-00123456"
}

⚠️

For pooled accounts, your client's sender must include the smartWalletRef

in the payment reference on every transfer. Missing references will prevent automatic allocation and require manual reconciliation. Communicate this requirement clearly to your clients.

Account types

Step 3 — Monitor incoming payments

We recommend subscribing to webhooks to receive real-time notifications for incoming payments rather than polling. See the Webhooks guide for setup instructions.

You can then send email or app notifications or to your customers using these when recieved, for real time payment information.

Inbound payments pass through two statuses:

Requested webhook

{
  "payload": {
    "id": 38313,
    "amount": "1234.00",
    "reference": "TO-07112024-050",
    "state": "requested",
    "currency": "GBP",
    "type": "iban_to_wallet",
    "walletId": 25832,
    "createdDate": "2024-11-07T11:26:55.000Z",
    "completedDate": null,
    "companyId": "4109"
  }
}

Completed webhook

{
  "payload": {
    "id": 38313,
    "amount": "1234.00",
    "reference": "TO-07112024-050",
    "state": "completed",
    "currency": "GBP",
    "type": "iban_to_wallet",
    "account": {
      "accountNumber": "123456789",
      "beneficiaryCompanyName": "Acme Logistics Ltd",
      "beneficiaryEntityType": "company",
      "currency": "GBP",
      "status": "approved"
    },
    "walletId": 25832,
    "createdDate": "2024-11-07T11:26:55.000Z",
    "completedDate": "2024-11-07T11:27:01.820Z",
    "companyId": "4109"
  }
}

💡

Use companyId and walletId in the webhook payload to identify which

sub-account and wallet received the funds.

Wallet-to-wallet transfers

Funds can be transferred between wallets within the same sub-account using the Transfer to Another Wallet endpoint. This is useful for internal fund allocation or currency segregation within the sub-account.

⚠️

PARTNER_REFERRED accounts cannot sweep funds to the parent account.

All funds must remain within the sub-account and be managed at that level.