Settlement requests

Introduction

A settlement request asks HUB2 to pay you out of the balance of your collection account. Settlement requests are created in the HUB2 Dashboard: there is no API endpoint to create or list them. To follow a request from your own system, subscribe to the settlement request webhooks. The Settlements page appears in the Dashboard menu for users who have the permission to view settlement requests. Submitting a request requires the permission to create one.

Create a settlement request

Open the Settlements page

The page shows your collection balance and the Available balance per currency. The available balance is your collection balance minus the amounts already committed to your other settlement requests that are not completed yet.

Submit a settlement request

Click Submit a settlement request, then fill in the form:

Amount: a whole number, in the currency selected below.
Currency: the currency of the balance to withdraw from.
Description (optional).

HUB2 assigns a unique reference to the request. It is displayed in the Reference column of the list.

HUB2 refuses the request when:

the amount is below the minimum settlement amount;
your merchant account is not active;
the amount exceeds the available balance of the selected currency.

The request is then not created.

What HUB2 does with a request

Submission: the request is recorded with the status Submitted.
Review: HUB2 reviews the request.
- If it is approved, the status becomes Processing.
- If it is rejected, the status becomes Rejected. HUB2 always gives a reason, which is displayed under the status in the list and sent to you by e-mail. The request ends here and no funds are moved.
Funds sent: once approved, the amount is debited from your collection balance and HUB2 sends the funds. The status becomes Funds sent.
Confirmation: when HUB2 has recorded the proof of transfer, the status becomes Confirmed and you receive a confirmation e-mail.

If HUB2 cannot execute the request after approving it, the Dashboard displays the status Failed. Contact HUB2 support with the reference of the request.

Follow a request

The list on the Settlements page shows the reference, the amount, the date of submission and the status of each request, with the most recent first. It refreshes automatically. Use the status filter to display only the requests in a given status:

Status in the Dashboard	Meaning
Submitted	The request is recorded and waiting for review.
Processing	The request is approved and HUB2 is processing it.
Funds sent	The amount is debited from your collection balance and the funds are sent.
Confirmed	The proof of transfer is available.
Rejected	HUB2 rejected the request. The reason is displayed with the status.
Failed	The approved request could not be executed.

Download the proof of transfer

For a Confirmed request, click the download button at the end of its row (Download proof of transfer). The proof is an image file (JPG or PNG) named after the reference of the request.

Webhooks

HUB2 sends a webhook each time a settlement request changes status. Subscribe to these events in the Dashboard as for any other event (see Webhooks overview and the list of available events). Settlement request webhooks are sent for the live environment.

Event	Sent when	Dashboard status
`settlement_request.submitted`	The request is created.	Submitted
`settlement_request.processing`	HUB2 approves the request.	Processing
`settlement_request.funds_sent`	The amount is debited from your collection balance and the funds are sent.	Funds sent
`settlement_request.confirmed`	The proof of transfer is recorded.	Confirmed
`settlement_request.rejected`	HUB2 rejects the request.	Rejected

A request that fails after approval does not trigger a webhook: for webhook consumers it stays at processing. The data object of each webhook contains:

Field	Description
`id`	Identifier of the settlement request.
`reference`	Reference of the request, as displayed in the Dashboard.
`amount`	Amount of the request.
`currency`	Currency of the request.
`previousStatus`	The event that preceded this one for the request (for example `settlement_request.processing` in a `settlement_request.funds_sent` webhook). Absent from `settlement_request.submitted`.
`reason`	Reason for the rejection. Only present in `settlement_request.rejected`.

Example of a settlement_request.rejected webhook:

{
  "owner": "1234",
  "type": "settlement_request.rejected",
  "data": {
    "id": 42,
    "reference": "SR-3f6c0a52-8a39-4d7c-9a0e-5f1f0a7c1b2d",
    "amount": 500000,
    "currency": "XOF",
    "previousStatus": "settlement_request.submitted",
    "reason": "Incomplete request. Please contact your account manager."
  },
  "test": false,
  "id": "evt_Doc7a41c2e9f0b5d38e6c1",
  "createdAt": "2024-06-06T10:49:36.212Z"
}

Getting started

Transfers

Payments

Instant Payment

Webhooks

Processing Only

Payment Links

Subscriptions

Submerchants

Other

Introduction

Create a settlement request

What HUB2 does with a request

Follow a request

Download the proof of transfer

Webhooks

​Introduction

​Create a settlement request

​What HUB2 does with a request

​Follow a request

​Download the proof of transfer

​Webhooks

Introduction

Create a settlement request

What HUB2 does with a request

Follow a request

Download the proof of transfer

Webhooks