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

# Payouts overview

> Pay a Beneficiary's bank account in fiat, funded with USDT from your Mansa payout vault.

## Flow

An integration has seven steps. Steps 2 and 3 involve a manual review on our side, so they are asynchronous: poll the `refresh` endpoints until `status` is `ready`.

**1. Register a Sender**

A Sender is the payer named on the bank transfer: an enterprise or an individual. One organization can have many Senders.
[Register Senders](https://docs.mansa.xyz/api-reference/v2/payouts/register-senders.md)

**2. Submit the Sender's payer details**

Upload KYC documents, then submit the payer details. Wait for `status: ready`, using [Refresh a Sender](https://docs.mansa.xyz/api-reference/v2/payouts/refresh-sender.md) to re-check.
[Upload a Sender file](https://docs.mansa.xyz/api-reference/v2/payouts/upload-sender-file.md), [enterprise](https://docs.mansa.xyz/api-reference/v2/payouts/submit-enterprise-kyb.md) or [personal](https://docs.mansa.xyz/api-reference/v2/payouts/submit-personal-kyc.md) payer details.

**3. Register a Beneficiary**

Who gets paid. Wait for `status: ready`, using [Refresh a Beneficiary](https://docs.mansa.xyz/api-reference/v2/payouts/refresh-beneficiary.md) to re-check.
[Register Beneficiaries](https://docs.mansa.xyz/api-reference/v2/payouts/register-beneficiaries.md)

**4. Fetch the purpose codes**

Every order needs a `purpose_code` that is valid for its Sender and Beneficiary.
[Get purpose codes](https://docs.mansa.xyz/api-reference/v2/payouts/get-sender-purposes.md)

**5. Create a batch**

A batch holds one or more orders. Each order comes back quoted in USDT.
[Create a draft batch](https://docs.mansa.xyz/api-reference/v2/payouts/create-batch.md)

**6. Fund and confirm**

Make sure your payout vault holds enough USDT, then confirm the batch.
[Get the funding address](https://docs.mansa.xyz/api-reference/v2/payouts/get-funding-address.md), [Confirm a batch](https://docs.mansa.xyz/api-reference/v2/payouts/confirm-batch.md)

**7. Track the batch**

Follow the batch until every order is `COMPLETED` or `FAILED`.
[Get a batch](https://docs.mansa.xyz/api-reference/v2/payouts/get-batch.md), [Refresh a batch](https://docs.mansa.xyz/api-reference/v2/payouts/refresh-batch.md)

## Conventions

* **Base path:** `/api/v2/payouts`. Your organization must have the Payout product enabled. [Check product entitlements](https://docs.mansa.xyz/api-reference/v2/payouts/get-product-entitlements.md) shows `payout` as enabled.
* **Authentication:** the same signed-request scheme as the rest of the Mansa API (API key plus a signed JWT per request). Multipart uploads are signed as if the body were `{}`.
* **Naming:** all request and response fields are `snake_case`. Two exceptions: the `fileType` multipart form field and the `beneficiaryId` query parameter on [Get purpose codes](https://docs.mansa.xyz/api-reference/v2/payouts/get-sender-purposes.md).
* **Amounts** are decimal strings (for example `"100.00"`), never numbers.
* **Timestamps** are ISO-8601 UTC strings.
* **Partner details are never exposed.** Statuses and error messages are Mansa's own.

## Senders

A Sender needs three calls before it can be used on an order: register it, upload its documents, then submit its payer details.

1. [Register Senders](https://docs.mansa.xyz/api-reference/v2/payouts/register-senders.md). Each Sender starts `pending`.
2. [Upload a Sender file](https://docs.mansa.xyz/api-reference/v2/payouts/upload-sender-file.md) for each document. A Sender needs 1 to 10 files, and each upload returns a `file_id`.
3. Submit payer details with the `file_id` values in `kyc_file_ids`: [enterprise](https://docs.mansa.xyz/api-reference/v2/payouts/submit-enterprise-kyb.md) for an `enterprise` Sender, [personal](https://docs.mansa.xyz/api-reference/v2/payouts/submit-personal-kyc.md) for an `individual` one. For an individual, use a value from [Get ID types](https://docs.mansa.xyz/api-reference/v2/payouts/get-sender-id-types.md) as `id_type`.

The same payer-details calls resubmit a Sender whose review was rejected with "may resubmit".

| `status` | Meaning |
| - | - |
| `pending` | Payer details not submitted yet, or under review |
| `ready` | Usable on an order |
| `rejected` | Declined. `status_reason` says why and whether you may resubmit |

> [!NOTE]
>
> Review is manual and there is no callback. Call [Refresh a Sender](https://docs.mansa.xyz/api-reference/v2/payouts/refresh-sender.md) to re-check; it returns the Sender.

## Beneficiaries

A Beneficiary is not tied to a Sender: any Beneficiary can be paid from any of your Senders. The Sender is chosen per order.

* A bank Beneficiary needs its own address (`beneficiary_country_code`, `beneficiary_province`, `beneficiary_city`, `beneficiary_address`, `beneficiary_postcode`), separate from the bank's.
* `subject_type` is `corporate` or `individual`. Individuals also need `first_name` and `last_name`.
* `intermediary_bank_name` and `intermediary_bank_swift` are optional.
* `beneficiary_type` can also be `crypto` (with `chain_type` `TRC20` or `ERC20`, and the address in `account_number`) or `platform`.

Beneficiaries start `pending` and use the same statuses as Senders. Use [Refresh a Beneficiary](https://docs.mansa.xyz/api-reference/v2/payouts/refresh-beneficiary.md) to re-check.

## Purpose codes

Every order needs a `purpose_code` that is valid for its Sender and Beneficiary. Always fetch the list with [Get purpose codes](https://docs.mansa.xyz/api-reference/v2/payouts/get-sender-purposes.md) and use the `code` exactly as returned. Do not hard-code it.

```json theme={null}
GET /api/v2/payouts/senders/{id}/purposes?beneficiaryId={beneficiary id}

[
  { "code": "006-01", "name": "同名划转" },
  { "code": "006-26", "name": "货款" },
  { "code": "006-27", "name": "物流费用" }
]
```

Names are returned in Chinese. In order, the codes cover: same-name transfer, payment for goods, logistics, advertising, technical services, cloud services, rent, utilities, legal fees, accounting fees, consulting, sponsorship, investment and other.

> [!WARNING]
>
> `OTHR` ("other") is not supported yet. It requires an extra description that orders can't carry. Don't offer it.

## Batches and orders

A batch is the unit of submission: always one or more orders. A single payment is a batch of one.

### Create

[Create a draft batch](https://docs.mansa.xyz/api-reference/v2/payouts/create-batch.md) quotes every order. Nothing is charged and no funds move until you confirm.

* `beneficiary_amount` is what the Beneficiary receives, in `beneficiary_currency`.
* `beneficiary_currency` is one of USD, EUR, CNH, AUD, CAD, HKD, JPY, NZD, SGD, GBP or AED. **Every order in a batch must use the same currency.**
* `fee_type` is `SHA` (bank charges shared with the Beneficiary) or `OUR` (you pay all bank charges). Your organization's configuration decides which are allowed.
* The Sender must be `ready` to quote. The Beneficiary must be `ready` by the time you confirm.

Each order comes back `DRAFT` with a quote: `fee_amount` and `fee_currency` (the wire fee for the chosen `fee_type`, always USD), and `source_amount` and `source_currency` (the total USDT the order costs, all fees included). Edit a draft with [Edit a draft order](https://docs.mansa.xyz/api-reference/v2/payouts/update-order.md); it is re-quoted.

> [!NOTE]
>
> The batch-level `source_amount` is meant to be the sum of its orders' `source_amount`, but currently returns `null` before confirm and `"0.000000"` after. Use the orders' own `source_amount` until this is fixed.

### Fund and confirm

Check the vault with [Get the funding address](https://docs.mansa.xyz/api-reference/v2/payouts/get-funding-address.md) first. Confirming moves the batch's total `source_amount` out of your payout vault in one transfer.

* Before any money moves, confirm checks that every Beneficiary is `ready` and each bank order's `purpose_code` is currently valid for its Sender and Beneficiary. Either failure rejects the confirm.
* An order whose deposit hasn't landed within **2 hours** of confirmation expires to `CANCELLED_EXPIRED` (see `expires_at`).
* [Cancel an order](https://docs.mansa.xyz/api-reference/v2/payouts/cancel-order.md) works while it is `DRAFT` or `AWAITING_DEPOSIT`.

### Track

[Get a batch](https://docs.mansa.xyz/api-reference/v2/payouts/get-batch.md) and [Refresh a batch](https://docs.mansa.xyz/api-reference/v2/payouts/refresh-batch.md) return the batch and all its orders. [Refresh an order](https://docs.mansa.xyz/api-reference/v2/payouts/refresh-order.md) returns a single order. A `FAILED` order carries a generic `failure_message`; Mansa follows up directly. [List batches](https://docs.mansa.xyz/api-reference/v2/payouts/list-batches.md) is paginated and returns batches without their orders.

`uetr` on an order holds the SWIFT UETR once the bank network reports one. It may stay `null` after `COMPLETED`.

## Statuses

### Order

| `status` | Meaning |
| - | - |
| `DRAFT` | Quoted, not confirmed. Can be edited or cancelled |
| `AWAITING_DEPOSIT` | Confirmed; USDT is moving out of your payout vault |
| `DEPOSIT_RECEIVED` | USDT received |
| `PAYING_BENEFICIARY` | The bank transfer is in progress |
| `COMPLETED` | Paid |
| `FAILED` | Not completed; `failure_message` is set |
| `CANCELLED_EXPIRED` | Cancelled by you, or the deposit never landed |

### Batch

`AWAITING_CONFIRMATION`, `IN_PROGRESS`, `COMPLETED`, `PARTIALLY_COMPLETED`, `FAILED`, `CANCELLED_EXPIRED`.

## Errors

Failed calls return a non-2xx HTTP status and a JSON body with `statusCode` and `message`. Use the HTTP status to branch; treat `message` as human-readable text, not a stable code.

```json theme={null}
HTTP 400
{ "statusCode": 400, "message": "No DRAFT orders left to confirm in this batch" }
```

Request-validation failures list every problem in `message` as an array:

```json theme={null}
HTTP 400
{
  "statusCode": 400,
  "message": ["orders.0.beneficiary_amount must be a string"],
  "error": "Bad Request"
}
```

| Status | Typical cause |
| - | - |
| `400` | Invalid request, Sender or Beneficiary not `ready`, mixed currencies in a batch, nothing left to confirm, purpose code not valid for the pair |
| `401` | Missing or invalid request signature |
| `403` | Payout product not enabled for your organization |
| `404` | Unknown Sender, Beneficiary, batch or order id |
| `409` | Payout vault not provisioned ([Get the funding address](https://docs.mansa.xyz/api-reference/v2/payouts/get-funding-address.md)) |

Money-moving calls (`confirm`) are checked before any funds move, so a rejected confirm leaves the batch unchanged and can be retried after you fix the cause.

## Changes from earlier versions

If you integrated against an earlier release, these changes are breaking:

| Area | Change |
| - | - |
| Sender KYC | The enterprise and personal payer-details endpoints now take the simplified payload. The old KYB payload (`member_name`, `stakeholder_info`, `kyc_files`, ...) is removed. |
| Beneficiaries | No longer linked to a Sender; the Sender is chosen per order. `remark` is removed. |
| `purpose_code` | Now a code from [Get purpose codes](https://docs.mansa.xyz/api-reference/v2/payouts/get-sender-purposes.md) (for example `006-26`). The old fixed values (`GDSP`, `SNTR`, ...) are no longer valid. |

Additive changes: new Beneficiary fields (`subject_type`, `beneficiary_*` address, intermediary bank); new order fields `fee_currency` and `uetr`; new batch field `source_amount`; new endpoints [Get ID types](https://docs.mansa.xyz/api-reference/v2/payouts/get-sender-id-types.md), [Get purpose codes](https://docs.mansa.xyz/api-reference/v2/payouts/get-sender-purposes.md) and the four `refresh` endpoints.


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