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

2. Submit the Sender's payer details

   Upload KYC documents, then submit the payer details. Wait for status: ready, using Refresh a Sender to re-check. Upload a Sender file, enterprise or personal payer details.

3. Register a Beneficiary

   Who gets paid. Wait for status: ready, using Refresh a Beneficiary to re-check. Register Beneficiaries

4. Fetch the purpose codes

   Every order needs a purpose_code that is valid for its Sender and Beneficiary. Get purpose codes

5. Create a batch

   A batch holds one or more orders. Each order comes back quoted in USDT. Create a draft batch

6. Fund and confirm

   Make sure your payout vault holds enough USDT, then confirm the batch. Get the funding address, Confirm a batch

7. Track the batch

   Follow the batch until every order is COMPLETED or FAILED. Get a batch, Refresh a batch

​

Conventions

• Base path: /api/v2/payouts. Your organization must have the Payout product enabled. Check product entitlements 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.
• 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. Each Sender starts pending.
2. Upload a Sender file 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 for an enterprise Sender, personal for an individual one. For an individual, use a value from Get ID types 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

Review is manual and there is no callback. Call Refresh a Sender 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 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 and use the code exactly as returned. Do not hard-code it.

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.

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 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; it is re-quoted.

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 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 works while it is DRAFT or AWAITING_DEPOSIT.

​

Track

Get a batch and Refresh a batch return the batch and all its orders. Refresh an order returns a single order. A FAILED order carries a generic failure_message; Mansa follows up directly. List batches 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.

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:

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)

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 (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, Get purpose codes and the four refresh endpoints.