Payouts#

A Payout object is created when you send funds to a bank account. Payouts disburse collected payments to landlords and property managers.

The Payout object#

Attribute	Type	Description
`id`	string	Unique identifier with `po_` prefix
`object`	string	Always `"payout"`
`amount`	integer	Payout amount in smallest currency unit
`currency`	string	ISO 4217 currency code
`status`	enum	`pending`, `in_transit`, `paid`, `failed`, `canceled`
`destination`	string	Bank Account ID
`arrival_date`	timestamp	Expected arrival date
`description`	string	Payout description
`method`	enum	`standard` or `instant`
`failure_code`	string	Failure reason code
`failure_message`	string	Human-readable failure message
`metadata`	hash	Key-value pairs
`created`	timestamp	Time at which the object was created

{
  "id": "po_xyz789",
  "object": "payout",
  "amount": 1150000,
  "currency": "gbp",
  "status": "paid",
  "destination": "ba_abc123",
  "arrival_date": 1706572800,
  "description": "January 2025 rent disbursement",
  "method": "standard",
  "metadata": {
    "landlord_id": "ll_789",
    "period": "2025-01"
  },
  "created": 1706140800
}

Create a Payout#

POST /v1/payouts

Parameter	Type	Required	Description
`amount`	integer	Yes	Amount in smallest currency unit
`currency`	string	Yes	ISO 4217 currency code
`destination`	string	Yes	Bank Account ID
`description`	string	No	Payout description
`method`	string	No	`standard` (default) or `instant`
`metadata`	hash	No	Key-value pairs

curl https://api.casapay.com/v1/payouts \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1150000,
    "currency": "gbp",
    "destination": "ba_abc123",
    "description": "January 2025 rent disbursement"
  }'

Retrieve a Payout#

GET /v1/payouts/:id

curl https://api.casapay.com/v1/payouts/po_xyz789 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

List Payouts#

GET /v1/payouts

Parameter	Type	Description
`status`	string	Filter by status
`destination`	string	Filter by bank account
`arrival_date[gte]`	timestamp	Arrival on or after
`arrival_date[lte]`	timestamp	Arrival on or before
`limit`	integer	Number of objects (1–100)

curl "https://api.casapay.com/v1/payouts?status=paid&limit=10" \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"