Cancellation and Expiration

How HellOOpass payments are cancelled or expire, and how to recover when checkout is no longer payable.

Placeholder API contract

Path, headers, and fields below are illustrative until the final HellOOpass API contract is published.

Availability depends on your project

Cancellation and expiration may be limited at launch — confirm which capabilities are enabled for your project before depending on them.

Cancellation

POST/v1/payments/{payment_id}/cancel

Cancels a payment that has not completed. Illustrative — confirm availability for your project.

Authentication: Secret API key (Bearer)

Use it when the order is no longer fulfillable — the customer abandoned the flow or you are replacing the payment. Send an Idempotency-Key and reuse it on retries.

Parameter	Type	Required	Example
`payment_id`	string	Yes	`pay_01HZX9K2EXAMPLE`

Example request

curl -X POST https://sandbox-api.helloopass.example/v1/payments/pay_01HZX9K2EXAMPLE/cancel \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY"

Returns 200 OK with the payment in its new state. A payment already in a terminal state cannot be cancelled — that returns 409 conflict (Payment Errors).

Expiration

Payments may carry an expires_at timestamp, set at initialization or by project configuration.
After that moment the payment becomes expired and cannot be completed, even if the customer is still on the hosted checkout page.
If a customer arrives at an expired checkout_url, initialize a new payment and send them to the fresh URL.

Statuses

Aspect	`cancelled`	`expired`
How it happens	Explicit — via the cancel endpoint or the customer.	Automatic — `expires_at` elapses.
Recovery	Initialize a new payment if the customer still wants to pay.	Same — send a fresh `checkout_url`.
Reversible	No — terminal.	No — terminal.

Both are unpaid terminal states — never fulfill on them, and treat them like failed when messaging the customer.

Related: Payment Statuses · Verify Payment