# Remittance

> Coming soon, upon request — this feature is turned on for your tenant by the Aurea team. [Contact us](https://www.aureahub.com/contact)

Payouts to bank accounts and mobile money wallets for your company's own customers, for companies licensed to make them. Your administrators prepare and approve each payout; your servers follow them through events.

## Overview

- **A module of its own.** Remittance is the `remittance` module of your tenant ([Feature Availability › Modules](https://docs.aureahub.com/docs/feature-availability.md)), switched on only once a licence of your company that covers remittance is on record and verified.
- **Worked by your administrators.** Your customers, their beneficiaries and the payouts are handled by your company's administrators, with a passkey for each step. A payout is always approved by at least one administrator other than the one who prepared it — more above the amounts your company sets — and is signed only after its last approval.
- **Nothing to call.** Your servers and apps do not call Remittance: what they receive are its [events](https://docs.aureahub.com/docs/guide-events.md), one per change of a payout's status.

## The Module

- [Available Features](https://docs.aureahub.com/docs/tenant-features.md) answers `"remittance": true` in `modules` once the module is on for your tenant.
- While it is off, its routes answer your tenant's callers `403` with `details.code` `MODULE_NOT_ENABLED` and `details.module` `remittance`, and no Remittance event is sent.
- It is switched on only with a verified licence: asked before, the switch is refused with `409` `MODULE_REQUIRES_LICENCE`. A licence that ends later does not switch the module off: new payouts are refused until a licence is in force again, and what was made stays readable.

## Payout Events

Name the types on a [webhook endpoint](https://docs.aureahub.com/docs/webhook-endpoint-add.md): they reach only the endpoints that name them, never an endpoint with an empty list or the webhook of an environment. A payout made through a partner's sandbox goes to your `sandbox` endpoints, one made in production to your `production` ones.

| type | Sent when |
| --- | --- |
| remittance.payout.requested | A payout was prepared and waits for its approvers (never the administrator who prepared it). |
| remittance.payout.approved | Its last approval came in: it may now be signed. |
| remittance.payout.rejected | An approver rejected it. |
| remittance.payout.expired | Its approvals did not all come in within your company's approval window. |
| remittance.payout.cancelled | It was cancelled before it was signed. |
| remittance.payout.submitted | It was signed and its deposit sent to the partner that pays it out: `txHash` names the transfer. |
| remittance.payout.completed | The partner paid the beneficiary. |
| remittance.payout.failed | It could not be completed: `failureReason` says why. |

- Each body is published in the [OpenAPI document](https://api.aureahub.com/v1/docs/json) as `WebhookEvent.<type>.v1`, and is delivered and signed as every event ([Webhooks & Events](https://docs.aureahub.com/docs/guide-events.md)). One event per payout and status: a repeat carries the same `id`.

## Statuses

`pending_approval` → `approved` → `submitted` → `completed`. A payout ends instead as `rejected` or `expired` (before its approval), `cancelled` (before it is signed) or `failed`. `completed`, `rejected`, `expired`, `cancelled` and `failed` are final, with `finishedAt` set.

## Fields

`data` is the same in every type:

- `payoutId`, `customerId` (your company's customer it is made for), `beneficiaryId` — Aurea's ids.
- `status` — the status above; `partner` — the provider that carries the payout, as an opaque id: store it and compare it, never show or interpret it; a new provider may add a value.
- `amount` and `currency` — what the beneficiary receives: a decimal with two places, written as text, and its ISO 4217 code.
- `purpose` — the payout's purpose, such as `family_support` or `salary`.
- `cryptoCurrency`, `chain`, `chainId` — the stablecoin and the network the payout is paid from.
- `approvalsRequired` — the approvers it needs besides the one who prepared it; `approvals` — those who approved so far.
- `preparedBy` — the id of the administrator who prepared it.
- `txHash` — the deposit transfer, once sent; `failureReason` — why it failed; both `null` otherwise.
- `createdAt`, `finishedAt` (`null` until the payout ends) — ISO 8601 in UTC.
- Never sent: the beneficiary's name or account details, or your customer's personal data. Ignore fields you don't know: more may come.

---

Web version: https://docs.aureahub.com/#guide-remittance