Invoices#

An invoice is a payable amount attached to an agreement. There are three ways one gets created.

How	When to use it
Automatically by a session	First payment at move-in. Created when the tenant pays.
Invoice endpoint below	Recurring rent, or any ad-hoc amount on a known tenant.
Email alias	Forward a PDF to the agreement `email_alias` and CasaPay parses and bills it.

Invoice state#

Two independent lifecycles matter. status tracks what the tenant owes; payout_status tracks money moving to you.

`status`	Meaning
`unpaid`	Nothing received.
`partial`	Part paid.
`paid`	Settled in full.
`cancelled` / `rejected`	Withdrawn, not collectable.

`payout_status`	Meaning
`created` / `pending`	Payout scheduled, not yet sent.
`in_disbursement`	Sent to the bank, in flight.
`settled`	Money has reached your account.
`failed`	Payout failed, needs review.
`cancelled`	Payout withdrawn before sending.

Cancellation is only possible before money moves

An invoice can be cancelled while it is unpaid and its payout is still pending. Once the tenant has paid (even partially), or the payout has reached in_disbursement or settled, cancellation is refused - otherwise real money would sit against a cancelled invoice. Refund or credit out of band instead.

Create an invoice session

POST/api/v1/gateway/agreements/{id}/invoice

Raises a new amount against an existing agreement and returns a checkout session for it. The tenant is already known, so no tenant block, verification or deposit decision is needed - they open the link and pay.

Body

amountnumberREQUIRED

Amount due. 0.01 to 999999.99.

success_urlstringREQUIRED

Redirect after payment. Max 2048.

cancel_urlstringREQUIRED

Redirect if the tenant abandons. Max 2048.

descriptionstring

Shown on the invoice. Max 1000.

reference_numberstring

Payment reference propagated to the invoice and payout. Max 35.

document_urlstring

Invoice PDF shown at checkout. Max 2048.

due_datestring

Due date, today or later. Drives the operator payout date.

metadataobject

Up to 20 string values, each max 500 chars.

curl -X POST https://manage.casapay.com/api/v1/gateway/agreements/4821/invoice \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 650,
    "description": "April rent",
    "reference_number": "2026-04-4821",
    "due_date": "2026-04-05",
    "success_url": "https://your-app.com/done",
    "cancel_url": "https://your-app.com/cancelled"
  }'

Returns 201 with a session you can email or redirect to:

{
  "session_id": "gwy_4tR8yN2wQe6xV3bM",
  "gateway_url": "https://gateway.casapay.com/s/gwy_4tR8yN2wQe6xV3bM",
  "status": "pending",
  "expires_at": null,
  "total_amount": 650.0,
  "invoice_id": 91801
}

Invoice sessions do not expire

expires_at is null, so a link you email in April still works in May. Cancel the session explicitly if you need to withdraw it.

Because the link stays valid, a returning customer should be sent the same session rather than a new one - see Pay now button.

Errors specific to this endpoint:

Status	Code	Cause
404	`AGREEMENT_NOT_FOUND`	No such agreement for your entity.
400	`AGREEMENT_NOT_ACTIVE`	Agreement is not `active`.
400	`AGREEMENT_NO_TENANT`	Agreement has no tenant attached.

Retrieve the invoice document

GET/api/v1/gateway/invoices/{id}/document

Returns a time-limited signed URL for the invoice PDF, when one exists. Use it to show or forward the original document.