# 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](https://www.hansapay.io/docs/payouts#payout-balance-precheck)).

## Create Payout

`POST /api/v1/payouts/create`

### Request 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.currency` must be `USD`
- `payee.account_id` is the recipient's Cash App `$cashtag`; the leading `$` may be left out.
  `payee.account_type` is `CASHTAG` or omitted. The other payee fields are optional. An
  `account_id` that is not a `$cashtag` is refused with `code=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=5008`
  and nothing is held
- If the payout is refused when it is sent, the response still has `code=0`, with `status` and
  `next_action` `FAILED`. The amount and fee go back to your available balance at once, a
  `payout.updated` notification is sent, and querying the payout gives the reason in
  `status_reason` (see [Query Payout](https://www.hansapay.io/docs/payouts#query-payout))
- If Cash App does not accept the recipient, the payout ends `FAILED` with `status_reason`
  `Recipient 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 your `merchant_payout_no`
  (see [Query Payout](https://www.hansapay.io/docs/payouts#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](https://www.hansapay.io/docs/payouts#query-payout))

Notes:

- If `code=5008` is 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

```json
{
  "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/query`

### 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 |

### 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

```json
{
  "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/cancel`

Notes:

- 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

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "payout_no": "P202406240001",
    "merchant_payout_no": "MP202406240001",
    "status": "CANCELED"
  }
}
```

## Payout Balance Precheck

`POST /api/v1/payouts/precheck`

### Request 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_amount` is provided and `code=5008` is 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

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