Versioning#

API version#

The gateway API is versioned in the URL path. The current version is v1:

https://manage.casapay.com/api/v1/gateway/...

There is no version header. A future breaking change would ship as /api/v2/gateway, and v1 would keep working until formally deprecated.

What is a breaking change#

These are backwards compatible and can ship at any time without a new version. Your integration must tolerate them:

• New endpoints.
• New optional request fields.
• New fields in responses and webhook payloads.
• New values in an enum - treat every enum as open-ended.
• New event types.
• Reordered JSON keys.

These are breaking and would require a new API version:

• Removing or renaming a field or endpoint.
• Making an optional field required.
• Changing a field's type or meaning.
• Removing an enum value or event type.

Docs version#

These docs are versioned alongside the API and published from the cp-api-docs repository. Each release is tagged docs-vN.N.N:

The current docs version is shown in the changelog below and in docs.version.json at the site root, so you can check programmatically whether your integration was written against an older revision.

Changelog#

1.3.0#

• Adds Embedding the checkout: how to render the hosted checkout in an iframe or popup instead of redirecting. Documents that framing is permitted - the checkout sets no X-Frame-Options and no CSP frame-ancestors, so no domain allowlisting is needed.
• Clarifies that there is no postMessage API on the checkout. The completion contract is the redirect to success_url in every integration style; embedded integrations bridge that redirect to the parent window themselves.
• Restates, for the embedded case, that any browser-delivered signal is a UX hint only. Fulfilment must come from gateway.session.completed or a server-side GET /sessions/{session_id}.

1.2.0#

• Operator-initiated session cancellation now cascades: cancelling a session via the authenticated API or the dashboard also cancels the linked invoice and its pending operator payout. The response reports the outcome as invoice_cancelled. Pass cascade: false to cancel only the session.
• A tenant cancelling from the checkout never cascades, so a tenant cannot void their own debt. System cancellations do not cascade either, since they are already triggered by an invoice change.
• The cascade is refused once money has moved - the tenant has paid, or the payout has left pending - leaving the invoice intact for a refund or credit note.

1.1.0#

• Adds Pay now button: how to keep one live session per invoice, so a returning or abandoning customer never creates a duplicate session. Covers storing the session_id, reusing pending / processing sessions, handling a mid-payment session, and why two live sessions on one invoice is a double-charge risk.
• Adds Changing invoice amounts: amounts are immutable, so correcting a premium means cancel and recreate. Documents when cancellation is still permitted, and that operator-initiated session cancellation will soon cascade to the invoice and its pending payout.

1.0.0#

First release of the gateway-focused documentation.

• Documents the live /api/v1/gateway surface: sessions, agreements, invoices, pricing preview and the public checkout API.
• Adds flow guides for checkout, deposits and guarantees, recurring rent and payment links.
• Documents reason and note on session cancellation, and the cancellation block on gateway.session.cancelled.
• Documents that a session whose payment has completed can no longer be cancelled, and that invoice cancellation is refused once the tenant has paid or the payout has left pending.
• Documents per-payment-method fees: the tenant-borne CasaPay transaction fee and the operator take rate.
• Replaces the previous speculative resource docs, which described endpoints the platform does not expose.