API reference

Payouts

Send money from your StablePay balance to Cash App and PayPal recipients. Payouts are asynchronous: create one, then wait for the signed notification.

Create a payout

POST/api/v1/payouts/create

Field	Type	Required	Description
`payment_method`	string	Yes	`CASH_APP` or `PAYPAL`.
`merchant_payout_no`	string	Yes	Your payout number. Unique; used for idempotency.
`trans_amount.currency`	string	Yes	Currency code.
`trans_amount.value`	string	Yes	Amount the recipient receives, as a decimal string.
`payee.account_id`	string	Usually yes	Recipient account — the value matching account_type.
`payee.account_type`	string	Usually yes	`EMAIL`, `MOBILE`, `CASHTAG`, `USERID`, etc.
`payee.full_name`	string	Some methods	Recipient full name. Required for some payout methods.
`payee.email`	string	No	Recipient email.
`payee.mobile`	string	No	Recipient mobile number.
`payee.country`	string	No	2-letter country code.
`payee.payee_id`	string	No	Wallet-side user ID.
`memo`	string	No	Memo shown to the recipient where supported.
`notify_url`	string	Yes	URL that receives the signed payout notification once the payout reaches a final result.
`metadata`	string	No	Opaque passthrough.
`client_ip`	string	No	Client IP.

{
  "payment_method": "CASH_APP",
  "merchant_payout_no": "MP202606240001",
  "trans_amount": {
    "currency": "USD",
    "value": "88.50"
  },
  "payee": {
    "account_id": "$cashdemo",
    "account_type": "CASHTAG",
    "full_name": "John Doe",
    "country": "US"
  },
  "memo": "June commission",
  "notify_url": "https://merchant.example.com/callback/payout",
  "metadata": "batch=20260624"
}

Field	Type	Description
`payment_method`	string	Payment method.
`payout_no`	string	StablePay payout number.
`merchant_payout_no`	string	Your payout number.
`status`	string	`PENDING`, `PROCESSING`, `SUCCESS` or `FAILED`.
`trans_amount`	object	Payout amount.
`fee`	object	Fee charged for this payout.
`total_debit`	object	Total debited from your balance (amount + fee).
`psp_payout_no`	string	StablePay processing reference.
`next_action`	string	`WAIT_NOTIFY`, `SUCCESS` or `FAILED`.
`created_at`	string	Creation time.

200 · response

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CASH_APP",
    "payout_no": "P202606240001",
    "merchant_payout_no": "MP202606240001",
    "status": "PENDING",
    "trans_amount": {
      "currency": "USD",
      "value": "88.50"
    },
    "fee": {
      "currency": "USD",
      "value": "1.50"
    },
    "total_debit": {
      "currency": "USD",
      "value": "90.00"
    },
    "psp_payout_no": "SPR_P_001",
    "next_action": "WAIT_NOTIFY",
    "created_at": "2026-06-24T12:00:00Z"
  }
}

next_action=WAIT_NOTIFY is the normal case: the final result arrives as a PAYOUT event at notify_url.
total_debit — amount plus fee — is what leaves your balance.
code=5004 means insufficient spendable balance; code=5008 means the amount is outside the current limits. Run a precheck first to catch both.

Query a payout

POST/api/v1/payouts/query

Provide exactly one identifier.

Field	Type	Required	Description
`payout_no`	string	One of two	StablePay payout number.
`merchant_payout_no`	string	One of two	Your payout number.

{
  "merchant_payout_no": "MP202606240001"
}

Field	Type	Description
`payment_method`	string	Payment method.
`payout_no`	string	StablePay payout number.
`merchant_payout_no`	string	Your payout number.
`status`	string	Payout status.
`status_reason`	string	Failure or cancellation reason, sanitized for merchants.
`trans_amount`	object	Payout amount.
`fee`	object	Fee.
`total_debit`	object	Total debit.
`psp_payout_no`	string	StablePay processing reference.
`payee`	object	Snapshot of the recipient as submitted.
`metadata`	string	Your passthrough value.
`paid_at`	string	Completion time.
`created_at`	string	Creation time.
`updated_at`	string	Last update time.

200 · response

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "CASH_APP",
    "payout_no": "P202606240001",
    "merchant_payout_no": "MP202606240001",
    "status": "SUCCESS",
    "status_reason": "",
    "trans_amount": {
      "currency": "USD",
      "value": "88.50"
    },
    "fee": {
      "currency": "USD",
      "value": "1.50"
    },
    "total_debit": {
      "currency": "USD",
      "value": "90.00"
    },
    "psp_payout_no": "SPR_P_001",
    "payee": {
      "account_id": "$cashdemo",
      "account_type": "CASHTAG",
      "full_name": "John Doe",
      "country": "US"
    },
    "metadata": "batch=20260624",
    "paid_at": "2026-06-24T12:00:08Z",
    "created_at": "2026-06-24T12:00:00Z",
    "updated_at": "2026-06-24T12:00:08Z"
  }
}

Cancel a payout

POST/api/v1/payouts/cancel

Cancellation is rarely available

Most integrations can ignore this endpoint. Use it only where StablePay has explicitly confirmed that cancellation is supported for your payout method.

Field	Type	Required	Description
`payout_no`	string	One of two	StablePay payout number.
`merchant_payout_no`	string	One of two	Your payout number.
`reason`	string	No	Cancellation reason.

{
  "merchant_payout_no": "MP202606240001",
  "reason": "manual cancel"
}

Field	Type	Description
`payout_no`	string	StablePay payout number.
`merchant_payout_no`	string	Your payout number.
`status`	string	Expected to be `CANCELED`.

200 · response

{
  "code": 0,
  "msg": "success",
  "data": {
    "payout_no": "P202606240001",
    "merchant_payout_no": "MP202606240001",
    "status": "CANCELED"
  }
}

Balance precheck

POST/api/v1/payouts/precheck

Check your balances for a payout method and, optionally, estimate the fee and total debit for a specific amount — without creating anything.

Field	Type	Required	Description
`payment_method`	string	Yes	`CASH_APP` or `PAYPAL`.
`trans_amount`	object	No	If provided, the response includes `estimated_fee` and `estimated_debit`. Returns `5008` if the amount is outside the current limits.

{
  "payment_method": "PAYPAL",
  "trans_amount": {
    "currency": "USD",
    "value": "88.50"
  }
}

Field	Type	Description
`payment_method`	string	Payment method.
`currency`	string	Balance currency.
`available_balance`	object	Available balance.
`unsettled_balance`	object	Funds not yet settled.
`frozen_balance`	object	Funds on hold.
`spendable_balance`	object	Balance eligible for payouts.
`estimated_fee`	object	Only when trans_amount was provided.
`estimated_debit`	object	Only when trans_amount was provided.
`can_payout`	bool	Whether a payout can be created right now.

200 · response

{
  "code": 0,
  "msg": "success",
  "data": {
    "payment_method": "PAYPAL",
    "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": "1200.00"
    },
    "estimated_fee": {
      "currency": "USD",
      "value": "1.50"
    },
    "estimated_debit": {
      "currency": "USD",
      "value": "90.00"
    },
    "can_payout": true
  }
}

Read can_payout together with spendable_balance and estimated_debit before calling create. Error codes are listed under Responses & errors.