Changing invoice amounts#

There is no endpoint to edit an amount. Sessions and invoices are immutable once created, so correcting a premium, a rent figure or any other price means cancel and recreate.

Why immutable

An amount that could change after the fact would break reconciliation: the tenant may already have the old figure in their inbox, the invoice may already be booked, and the operator payout may already be scheduled against it. Replacing the invoice keeps a clean audit trail of what was actually charged.

Can you still change it?#

Cancellation is only permitted up to the point money has moved.

InvoicePayoutChange allowed
unpaidnone or pendingYes - cancel and recreate
unpaidin_disbursementNo - funds are in flight
unpaidsettledNo - the operator has been paid
paidanyNo - issue a credit note instead

If cancellation is refused you will get 400 with a reason such as payout_settled or invoice_paid. Handle the correction out of band (refund or credit note) rather than trying to force it.

The flow#

1

Cancel the existing session

Cancel first, before you send anything new. The old gateway_url may already be sitting in the tenant's inbox, and cancelling makes that stale link fail instead of charging the old amount.

curl -X POST https://manage.casapay.com/api/v1/gateway/sessions/gwy_4tR8yN2wQe6xV3bM/cancel \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "operator_cancelled",
    "note": "Premium corrected from 650 to 720"
  }'

Use the note to record why - it is stored on the session and echoed on the gateway.session.cancelled webhook, which makes a later audit much easier.

2

Cancel the invoice

Nothing to do - this is automatic.

An operator-initiated session cancellation also cancels the linked invoice and its pending operator payout, in the same call. The response tells you what happened:

{
  "session_id": "gwy_4tR8yN2wQe6xV3bM",
  "status": "cancelled",
  "cancellation_reason": "operator_cancelled",
  "invoice_cancelled": true
}

If invoice_cancelled is false, money had already moved - the tenant had paid, or the payout had left pending - so the invoice was deliberately left intact. Handle those out of band with a refund or credit note.

To cancel only the session and keep the invoice payable (for example to reissue a fresh link at the same amount), send "cascade": false.

3

Create a new invoice session at the corrected amount

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": 720,
    "description": "April rent (corrected)",
    "due_date": "2026-04-05",
    "success_url": "https://your-app.com/done",
    "cancel_url": "https://your-app.com/cancelled"
  }'
4

Overwrite your stored session reference

Replace the casapay_session_id on your invoice record with the new one, then send the new gateway_url to the tenant.

If you skip this, your Pay now button will keep serving the cancelled link. See Pay now button.

Cancel the session before emailing the replacement

If you send the new link first, both links are briefly live and the tenant may pay the old amount. Cancel, then send.

Who can cancel what#

Only operator cancellations cascade

An operator cancellation (source: operator, via the authenticated API or the dashboard) cancels the session, the invoice and the pending payout together.

A tenant abandoning checkout cancels only the session. The invoice stays payable and the payout stays scheduled, so a tenant can never void their own debt by clicking cancel.

System cancellations - for example when an invoice is settled another way - also touch only the session, because they are already triggered by an invoice change.

Payment method fees are re-resolved#

If your entity has per-payment-method fees configured, the fee is calculated and frozen when the tenant picks a method. A replacement invoice re-resolves them against the new amount, so the tenant-facing surcharge may differ from the original - a percentage fee on 720 is not the same as on 650.

See Amounts and pricing.

Related#