Sessions#

A session is one hosted checkout attempt. Creating a session returns a gateway_url you redirect the tenant to.

The session object#

Attribute	Type	Description
`session_id`	string	Unique ID, prefixed `gwy_`. Also the tenant-facing access token.
`gateway_url`	string	Hosted checkout URL. Always use it as returned.
`status`	enum	`pending`, `processing`, `completed`, `expired`, `cancelled`, `failed`.
`current_step`	enum	`verification`, `deposit_choice`, `payment`, or `null` when finished.
`expires_at`	timestamp	ISO-8601. `null` for invoice sessions, which never expire.
`total_amount`	number	What the tenant pays now. Excludes a guaranteed deposit.
`cover_amount`	number	Deposit or guarantee amount, when used.
`deposit_mode`	enum	`deposit_upfront`, `deposit_guaranteed`, `choice`.
`first_payment_amount`	number	Rent portion, when used.
`subscription_fee`	number	Monthly CasaPay fee, when the deposit is guaranteed.

Create a session

POST/api/v1/gateway/sessions

Creates a checkout session. The payment agreement and invoice are created when the tenant pays.

Body

tenant.emailstringREQUIRED

Tenant email. Max 255.

tenant.first_namestringREQUIRED

Max 255.

tenant.last_namestringREQUIRED

Max 255.

tenant.phonestring

Digits, spaces, plus, dash, parentheses. Max 50.

tenant.personal_codestring

National ID. Alphanumeric and dashes. Max 50.

success_urlstringREQUIRED

Redirect after payment. Max 2048.

cancel_urlstringREQUIRED

Redirect if the tenant abandons. Max 2048.

agreement_typeenum

ontime, cover or payment_link. Defaults to ontime.

cover_amountnumber

Deposit or guarantee amount. 0 to 15000. Not allowed for payment_link.

deposit_modeenum

deposit_upfront, deposit_guaranteed or choice. Required when cover_amount is above 0.

first_payment_amountnumber

Rent charged now. 0.01 to 999999.99.

first_payment_descriptionstring

Shown on the invoice. Max 1000.

amountnumber

Legacy single amount. Prefer first_payment_amount.

currencyenum

EUR, GBP, USD or CAD. Defaults to the entity currency.

descriptionstring

Internal description. Max 1000.

reference_numberstring

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

document_urlstring

PDF shown to the tenant at checkout. Max 2048.

verification_requiredboolean

Force identity verification for this session.

allowed_payment_methodsarray

Subset of card, bank_transfer, open_banking. Max 5.

metadataobject

Up to 20 string values, each max 500 chars. Echoed on webhooks.

One of amount, cover_amount or first_payment_amount is required.

curl -X POST https://manage.casapay.com/api/v1/gateway/sessions \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant": {
      "email": "tenant@example.com",
      "first_name": "Mari",
      "last_name": "Tamm"
    },
    "agreement_type": "ontime",
    "cover_amount": 800,
    "deposit_mode": "choice",
    "first_payment_amount": 650,
    "currency": "EUR",
    "reference_number": "2026-03-4821",
    "metadata": { "property_id": "prop_456" },
    "success_url": "https://your-app.com/done",
    "cancel_url": "https://your-app.com/cancelled"
  }'

Returns 201:

{
  "session_id": "gwy_9mK2xQ7pLr4vT1sZ",
  "gateway_url": "https://gateway.casapay.com/s/gwy_9mK2xQ7pLr4vT1sZ",
  "status": "pending",
  "expires_at": "2026-03-02T09:00:00+00:00",
  "cover_amount": 800.0,
  "deposit_mode": "choice",
  "first_payment_amount": 650.0,
  "subscription_fee": 16.0,
  "total_amount": 650.0
}

total_amount excludes a guaranteed deposit

With deposit_mode: choice the tenant has not decided yet, so total_amount covers rent only. If they choose to pay the deposit in cash the charge rises at checkout. See Amounts and pricing.

Retrieve a session

GET/api/v1/gateway/sessions/{session_id}

Returns the current state, including current_step and the payment result. A session owned by another entity returns 404.

curl https://manage.casapay.com/api/v1/gateway/sessions/gwy_9mK2xQ7pLr4vT1sZ \
  -H 'Authorization: Bearer sk_live_...'

Cancel a session

POST/api/v1/gateway/sessions/{session_id}/cancel

Cancels an unpaid session and fires gateway.session.cancelled.

Body

reasonenum

customer_cancelled or operator_cancelled. Defaults to operator_cancelled.

notestring

Free-text detail stored on the session. Max 500.

cascadeboolean

Defaults to true. When true, an operator cancellation also cancels the linked invoice and its pending payout. Set false to cancel only the session.

curl -X POST https://manage.casapay.com/api/v1/gateway/sessions/gwy_9mK2xQ7pLr4vT1sZ/cancel \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ "reason": "operator_cancelled", "note": "Tenant asked to re-issue the link" }'

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

Returns 400 CANCEL_FAILED when the session is already terminal, or when its payment has completed. A paid session can never be cancelled.

Operator cancellation also cancels the invoice

An operator cancellation also cancels the linked invoice and its pending payout. Pass cascade: false to cancel only the session - useful when reissuing a fresh link for the same amount.

A tenant cancellation from the checkout never cascades, so a tenant cannot void their own debt. The cascade is also refused once the tenant has paid or the payout has left pending, reported as invoice_cancelled: false.

See Changing invoice amounts for the full correction flow, and Pay now button for keeping one live session per invoice.

List session logs

GET/api/v1/gateway/sessions/{session_id}/logs

Returns the API and webhook traffic recorded for a session. Useful when debugging an integration.

Query

directionenum

inbound or outbound.

successboolean

Filter by delivery outcome.

per_pageinteger

1 to 200. Defaults to 50.

pageinteger

Page number, from 1.