API reference
中文Payouts
Pay out to a Cash App $cashtag from your available balance, query the result, and check the fee before you send.
Payouts are available for CASH_APP only. A payout is sent to a Cash App $cashtag, in USD, once payouts are enabled for your account. Until then, and for PAYPAL and PIX, /payouts/create and /payouts/precheck with an amount return code=5007. You can also send a payout from the merchant portal, under Payouts → Send payout.
A payout is paid from your available balance only: unsettled money can be paid out once it settles. When a payout is created, its amount and fee are taken from your available balance and held until the result is known. A successful payout debits them; a failed one gives them back. If your available balance does not cover the amount and the fee, the payout is refused with code=5004 and nothing is held.
The fee is your payout rate times the amount, plus your fixed fee per payout, rounded to the cent. /payouts/precheck with an amount returns the fee and the total debit before you send (see Payout Balance Precheck).
Create Payout
POST/api/v1/payouts/createRequest fields
| Field | Type | Required | Description |
|---|---|---|---|
payment_method | string | Yes | CASH_APP / PAYPAL / PIX (only CASH_APP is currently available) |
merchant_payout_no | string | Yes | Merchant payout number, used for idempotency |
trans_amount.currency | string | Yes | Currency. PIX requires BRL |
trans_amount.value | string | Yes | Amount |
payee.account_id | string | Usually yes | Recipient account. For PIX this is the PIX key value |
payee.account_type | string | Usually yes | EMAIL / MOBILE / CASHTAG / USERID etc. For PIX: CPF / CNPJ / PHONE / EMAIL |
payee.full_name | string | Required by some channels | Recipient full name. Required for PIX |
payee.document | string | Required by some channels | Recipient tax/ID number. Required for PIX (Brazilian CPF) |
payee.email | string | No | Recipient email |
payee.mobile | string | No | Recipient mobile |
payee.country | string | No | Country code |
payee.payee_id | string | No | Wallet-side user ID |
memo | string | No | Payout memo |
notify_url | string | Yes | Merchant URL for receiving payout result notifications after HansaPay receives the upstream result |
metadata | string | No | Merchant passthrough field |
client_ip | string | No | Client IP |
Cash App payout notes:
trans_amount.currencymust beUSDpayee.account_idis the recipient's Cash App$cashtag; the leading$may be left out.payee.account_typeisCASHTAGor omitted. The other payee fields are optional. Anaccount_idthat is not a$cashtagis refused withcode=5006- The amount must be within your payout channel's limits, currently 10.00 to 1,000.00 USD per
payout and shown in the merchant portal. An amount outside them is refused with
code=5008and nothing is held - If the payout is refused when it is sent, the response still has
code=0, withstatusandnext_actionFAILED. The amount and fee go back to your available balance at once, apayout.updatednotification is sent, and querying the payout gives the reason instatus_reason(see Query Payout) - If Cash App does not accept the recipient, the payout ends
FAILEDwithstatus_reasonRecipient not valid, and the amount is returned to your available balance - An accepted payout is
PROCESSING, with the amount and fee held, until the result arrives. If you get no response (for example a timeout), query it with yourmerchant_payout_no(see Query Payout) before sending it again: a new number would send a second payout - Cash App payouts cannot be cancelled. The result usually arrives within minutes, by
notification to
notify_url, or by querying the payout (see Query Payout)
Notes:
- If
code=5008is returned, the payout amount does not satisfy the current available channel limits
Successful data
| Field | Type | Description |
|---|---|---|
payment_method | string | Payment method |
payout_no | string | HansaPay payout number |
merchant_payout_no | string | Merchant payout number |
status | string | PENDING / PROCESSING / SUCCESS / FAILED |
trans_amount | object | Payout amount |
fee | object | Fee |
total_debit | object | Total merchant debit |
next_action | string | WAIT_NOTIFY / SUCCESS / FAILED |
created_at | string | Creation time |
Full success response example
{
"code": 0,
"msg": "success",
"data": {
"payment_method": "CASH_APP",
"payout_no": "P202406240001",
"merchant_payout_no": "MP202406240001",
"status": "PENDING",
"trans_amount": {
"currency": "USD",
"value": "88.50"
},
"fee": {
"currency": "USD",
"value": "1.50"
},
"total_debit": {
"currency": "USD",
"value": "90.00"
},
"next_action": "WAIT_NOTIFY",
"created_at": "2026-06-24T12:00:00+08:00"
}
}Query Payout
POST/api/v1/payouts/queryRequest fields
| Field | Type | Required | Description |
|---|---|---|---|
payout_no | string | One of two | HansaPay payout number |
merchant_payout_no | string | One of two | Merchant payout number |
Successful data
| Field | Type | Description |
|---|---|---|
payment_method | string | Payment method |
payout_no | string | HansaPay payout number |
merchant_payout_no | string | Merchant payout number |
status | string | Payout status |
status_reason | string | FAILED: Payout request failed, Recipient not valid or Payout failed; CANCELED: Payout canceled; otherwise absent. Never the provider's message |
trans_amount | object | Amount |
fee | object | Fee |
total_debit | object | Total debit |
payee | object | Recipient snapshot |
metadata | string | Merchant passthrough field |
paid_at | string | Completion time |
created_at | string | Creation time |
updated_at | string | Update time |
Full success response example
{
"code": 0,
"msg": "success",
"data": {
"payment_method": "CASH_APP",
"payout_no": "P202406240001",
"merchant_payout_no": "MP202406240001",
"status": "SUCCESS",
"trans_amount": {
"currency": "USD",
"value": "88.50"
},
"fee": {
"currency": "USD",
"value": "1.50"
},
"total_debit": {
"currency": "USD",
"value": "90.00"
},
"payee": {
"account_id": "$cashdemo",
"account_type": "CASHTAG",
"full_name": "John Doe",
"country": "US"
},
"metadata": "batch=20260624",
"paid_at": "2026-06-24T12:00:08+08:00",
"created_at": "2026-06-24T12:00:00+08:00",
"updated_at": "2026-06-24T12:00:08+08:00"
}
}Cancel Payout
POST/api/v1/payouts/cancelNotes:
- Most channels do not support payout cancellation
- Cash App payouts cannot be cancelled
- In most integrations, merchants can ignore this endpoint
- Use it only if HansaPay and the specific payout channel explicitly support cancellation
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
payout_no | string | One of two | HansaPay payout number |
merchant_payout_no | string | One of two | Merchant payout number |
reason | string | No | Cancellation reason |
Successful data
| Field | Type | Description |
|---|---|---|
payout_no | string | HansaPay payout number |
merchant_payout_no | string | Merchant payout number |
status | string | Expected to be CANCELED |
Full success response example
{
"code": 0,
"msg": "success",
"data": {
"payout_no": "P202406240001",
"merchant_payout_no": "MP202406240001",
"status": "CANCELED"
}
}Payout Balance Precheck
POST/api/v1/payouts/precheckRequest fields
| Field | Type | Required | Description |
|---|---|---|---|
payment_method | string | Yes | CASH_APP / PAYPAL / PIX |
trans_amount | object | No | If provided, the system returns estimated fee and estimated total debit |
Notes:
- If
trans_amountis provided andcode=5008is returned, the payout amount does not satisfy the current available channel limits
Successful data
| Field | Type | Description |
|---|---|---|
payment_method | string | Payment method |
currency | string | Currency |
available_balance | object | Available balance |
unsettled_balance | object | Unsettled balance |
frozen_balance | object | Frozen balance |
spendable_balance | object | Payout-eligible balance, equal to available_balance |
estimated_fee | object | Estimated fee, returned only when amount is provided |
estimated_debit | object | Estimated total debit, returned only when amount is provided |
can_payout | bool | Without trans_amount: whether available_balance is above zero. It does not mean a payout method is available. With trans_amount: whether available_balance covers the estimated total debit |
Full success response example
{
"code": 0,
"msg": "success",
"data": {
"payment_method": "CASH_APP",
"currency": "USD",
"available_balance": {
"currency": "USD",
"value": "1000.00"
},
"unsettled_balance": {
"currency": "USD",
"value": "200.00"
},
"frozen_balance": {
"currency": "USD",
"value": "50.00"
},
"spendable_balance": {
"currency": "USD",
"value": "1000.00"
},
"estimated_fee": {
"currency": "USD",
"value": "1.50"
},
"estimated_debit": {
"currency": "USD",
"value": "90.00"
},
"can_payout": true
}
}