Cancel order

Cancels an order. The behaviour depends on the moment:

• Before emission (awaiting_payment): the sale is undone and the order moves to cancelled.
• After emission (emitted): the order itself does not change status. The call triggers one cancellation request per policy of the order; each policy follows its own cancellation flow, including the premium refund computation.

Request

ENDPOINT

/v1/insurance/orders/{order_key}/cancel

METHOD

POST

Path params

Parameter	Type	Required	Description
order_key	string	required	Order key.

Request Body

{
  "reason": "Customer changed their mind"
}

Field	Type	Required	Description
reason	string	optional	Cancellation reason, recorded in the event trail and propagated to the policy cancellations in the post-emission case.

Response

The Pix QR is not revoked on a pre-emission cancel

In this version the pre-emission cancel is a local transaction: the Pix mandate is not cancelled on the charge, and the QR simply expires with the payment window. An insured person who authorises payment anyway pays into an already-cancelled order — the payment is stopped before issuance and returned to the payer. Treat the cancellation as final and stop showing the QR to the insured person.

Pre-emission

STATUS

200

Response Body

{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "cancelled"
}

Post-emission

STATUS

202

Response Body

{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "emitted",
  "policies_cancellation_requested": 2
}

Field	Type	Description
policies_cancellation_requested	integer	Number of policies whose cancellation was requested — one per product of the order. Track each one through the policy webhooks or the policy retrieval.

Semantics per status

Current order status	Result
awaiting_payment	200 — sale undone, order moves to cancelled.
emitted	202 — cancellation requested for each policy; the order stays emitted.
cancelled	200 — idempotent, nothing changes.
rejected / declined / expired	409 — terminal status, nothing to cancel.

Race between payment and cancellation

If a payment is confirmed practically at the same time as the pre-emission cancel, the order is still cancelled: the payment is stopped before issuance and returned to the payer. If the payment was confirmed first and the order is already emitted, the same call behaves as a post-emission cancel (202) — there is never a 409 in this race.

Possible errors

Every error (non-2xx) returns the standard body { "title", "description", "translation", "code" } — programmatically handle only the code field.

Status	Code	Description
401 / 403	—	Authentication or authorization failure.
404	ORD000001	Order nonexistent or belonging to another integration.
409	ORD000010	The order is in a terminal status with nothing to cancel (rejected, declined, expired).
502 / 504	ORD000031	A synchronous cancellation integration failed. No state was changed — retry the call, it is idempotent.