Products
Developers
Resources
Company

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/create

Request fields

FieldTypeRequiredDescription
payment_methodstringYesCASH_APP / PAYPAL / PIX (only CASH_APP is currently available)
merchant_payout_nostringYesMerchant payout number, used for idempotency
trans_amount.currencystringYesCurrency. PIX requires BRL
trans_amount.valuestringYesAmount
payee.account_idstringUsually yesRecipient account. For PIX this is the PIX key value
payee.account_typestringUsually yesEMAIL / MOBILE / CASHTAG / USERID etc. For PIX: CPF / CNPJ / PHONE / EMAIL
payee.full_namestringRequired by some channelsRecipient full name. Required for PIX
payee.documentstringRequired by some channelsRecipient tax/ID number. Required for PIX (Brazilian CPF)
payee.emailstringNoRecipient email
payee.mobilestringNoRecipient mobile
payee.countrystringNoCountry code
payee.payee_idstringNoWallet-side user ID
memostringNoPayout memo
notify_urlstringYesMerchant URL for receiving payout result notifications after HansaPay receives the upstream result
metadatastringNoMerchant passthrough field
client_ipstringNoClient 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)
  • 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) 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=5008 is returned, the payout amount does not satisfy the current available channel limits

Successful data

FieldTypeDescription
payment_methodstringPayment method
payout_nostringHansaPay payout number
merchant_payout_nostringMerchant payout number
statusstringPENDING / PROCESSING / SUCCESS / FAILED
trans_amountobjectPayout amount
feeobjectFee
total_debitobjectTotal merchant debit
next_actionstringWAIT_NOTIFY / SUCCESS / FAILED
created_atstringCreation 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

FieldTypeRequiredDescription
payout_nostringOne of twoHansaPay payout number
merchant_payout_nostringOne of twoMerchant payout number

Successful data

FieldTypeDescription
payment_methodstringPayment method
payout_nostringHansaPay payout number
merchant_payout_nostringMerchant payout number
statusstringPayout status
status_reasonstringFAILED: Payout request failed, Recipient not valid or Payout failed; CANCELED: Payout canceled; otherwise absent. Never the provider's message
trans_amountobjectAmount
feeobjectFee
total_debitobjectTotal debit
payeeobjectRecipient snapshot
metadatastringMerchant passthrough field
paid_atstringCompletion time
created_atstringCreation time
updated_atstringUpdate 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

FieldTypeRequiredDescription
payout_nostringOne of twoHansaPay payout number
merchant_payout_nostringOne of twoMerchant payout number
reasonstringNoCancellation reason

Successful data

FieldTypeDescription
payout_nostringHansaPay payout number
merchant_payout_nostringMerchant payout number
statusstringExpected 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

FieldTypeRequiredDescription
payment_methodstringYesCASH_APP / PAYPAL / PIX
trans_amountobjectNoIf 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

FieldTypeDescription
payment_methodstringPayment method
currencystringCurrency
available_balanceobjectAvailable balance
unsettled_balanceobjectUnsettled balance
frozen_balanceobjectFrozen balance
spendable_balanceobjectPayout-eligible balance, equal to available_balance
estimated_feeobjectEstimated fee, returned only when amount is provided
estimated_debitobjectEstimated total debit, returned only when amount is provided
can_payoutboolWithout 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
  }
}