Sub-accounts — 3. Receiving funds & sweeping to parent

This guide covers how to monitor incoming payments via webhook and sweep received funds from the sub-account wallet to your parent account.

📘

Authenticate as the sub-account using the

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

Webhook notifications

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

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",
    "clientReference": "null::sdfghjkl:123456789:2345",
    "account": {
      "accountNumber": "123456789",
      "beneficiaryCompanyName": "sdfghjkl",
      "beneficiaryEntityType": "company",
      "nationalId": "2345",
      "currency": "GBP",
      "status": "approved"
    },
    "walletId": 25832,
    "createdDate": "2024-11-07T11:26:55.000Z",
    "completedDate": "2024-11-07T11:27:01.820Z",
    "companyId": "4109"
  }
}

💡

Use the companyId and walletId fields in the webhook payload to identify which sub-account and wallet received the funds.

You will recieve these fields the same for both global and local use cases, as well as unique vs pooled accounts.

Sweeping funds to the parent account

Once you receive a completed webhook with type: iban_to_wallet, you can sweep the funds from the sub-account wallet to your parent account wallet using the Transfer to Another Wallet endpoint.

This is the recommended approach for centralising funds before performing FX or onward disbursements at the parent level

📘

Alternatively, FX can be performed directly within the sub-account without sweeping to the parent first. See the FX guide for both approaches as well as payouts performed from the sub-accounts directly Sending funds from sub-account

Inbound payment statuses