> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hub2.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://dashboard.hub2.io): there is no API endpoint to create or list them. To follow a request from your own system, subscribe to the [settlement request webhooks](#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

**1. 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.

**2. 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

1. **Submission**: the request is recorded with the status **Submitted**.
2. **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.
3. **Funds sent**: once approved, the amount is debited from your collection balance and HUB2 sends the funds. The status becomes **Funds sent**.
4. **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](https://docs.hub2.io/integration/en/webhooks/webhooks_overview.md) and the [list of available events](https://docs.hub2.io/integration/en/webhooks/webhooks_events_list.md)). 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:

```json theme={null}
{
  "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"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.