Cancel a payment intent
const url = 'https://api.example.com/v1/payment_intents/example/cancel';const options = { method: 'POST', headers: { 'Idempotency-Key': 'order-1042-attempt-1', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"cancellation_reason":"duplicate"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.example.com/v1/payment_intents/example/cancel \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1042-attempt-1' \ --data '{ "cancellation_reason": "duplicate" }'Cancels an intent the customer has not paid: one that is requires_payment_method,
requires_confirmation or requires_action. Canceling one already canceled answers it
unchanged. Once it is processing or succeeded, or while a confirm is still reaching the
payment method, it cannot be canceled: that is a conflict.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The object’s id.
Header Parameters
Section titled “Header Parameters”A value unique to this operation, such as your order number and attempt, of 1 to 255 characters. A retry with the same key and body is done at most once; see Idempotency.
Example
order-1042-attempt-1Request Body
Section titled “Request Body”object
Why you are canceling it. Optional.
Examples
{ "cancellation_reason": "duplicate"}Responses
Section titled “Responses”The intent, in canceled, with canceled_at and cancellation_reason.
object
In the currency’s minor unit.
The amount paid: amount once succeeded, and 0 until then.
A three-letter ISO 4217 code, in lower case.
The chosen method, such as [qrph], once there is one. Until then, the methods that can
take this payment now: confirm with one. In an event for an intent with no method, the
methods you allowed at creation, or null if you allowed any.
Where the payment is taken: ecommerce for every intent your server creates. Payments
taken on terminals will say pos (Pending).
object
object
The QR payload. Render it as a QR code for the customer to scan with their banking app.
When the code stops being payable, as a Unix timestamp.
object
object
The payment reference, unique to this attempt. Give it to the customer to pay at a cash collection location.
The exact amount to pay, in the currency’s minor unit.
A three-letter ISO 4217 code, in lower case.
When the reference stops being payable, as a Unix timestamp. After it the attempt fails as expired.
Words to show the customer. May be reworded, so never branch on it.
object
object
The payment page: a card’s, or our hosted checkout page for an intent created without a method. Send the customer there.
Where the customer comes back to, or null when you gave none: your return_url, or our hosted checkout page when
the customer chose card there, which then sends them on to yours. For the hosted
checkout page itself, the return_url you gave on create.
An intent created with checkout_mode embedded, waiting for the customer in embedded
checkout on your page. See Embedded checkout.
object
object
What your page mounts embedded checkout with, beside your publishable key, from one of your registered origins. The same on every read while it is here. It opens this one payment’s checkout: give it only to the customer paying.
When the checkout session ends, as a Unix timestamp. After it, the client token opens nothing.
object
card_declined: the card was declined. expired_card: the card has expired (test mode
only today). payment_intent_authentication_failure: the customer did not complete the
card’s authentication. payment_intent_payment_attempt_failed: the attempt failed, or the
customer left without paying. payment_intent_payment_attempt_expired: the customer did
not pay in time.
Why the card was declined, when the decline names a reason. Test mode only today: it
appears when you simulate a decline with a decline_reason (see Simulate a payment’s
outcome), and a live decline does not carry it yet, so
never depend on it there.
Words you can show the customer. May be reworded, so never branch on it.
The reason given when it was canceled, if any.
When it was canceled, as a Unix timestamp.
The metadata you gave it. {} if none.
object
When it was created, as a Unix timestamp.
Example
{ "id": "pi_01j9x2m8k4q7r5t3v6w8y0z2a4", "object": "payment_intent", "currency": "php", "payment_method_types": [ "card", "qrph" ], "channel": "ecommerce", "status": "requires_payment_method", "next_action": { "type": "qrph_display_qr_code" }, "last_payment_error": { "code": "card_declined", "decline_code": "insufficient_funds" }, "cancellation_reason": "requested_by_customer", "created": 1790411400}Headers
Section titled “Headers”This request’s id. Quote it when you contact support.
validation_failure: invalid_parameter for a parameter missing or not valid, named in param; invalid_json for a body that is not JSON; unsupported_media_type for a body that is not sent as JSON; not_acceptable when the request will not accept JSON; method_not_allowed for an HTTP method the path does not take.
object
object
A stable name for this refusal. Branch on this, never on message.
For the developer reading a log. May be reworded.
The field or parameter at fault, when there is one.
Example
{ "error": { "type": "validation_failure", "code": "invalid_parameter", "message": "A whole number of minor units, from 1 to 999999999999999999.", "param": "amount", "request_id": "req_4f1c0b2e9a7d" }}authentication_failure: access_token_required when no token was sent, invalid_access_token when it is not valid, has expired, or is a client secret. Sent with a WWW-Authenticate: Bearer header, which adds error="invalid_token" when a token was sent.
object
object
A stable name for this refusal. Branch on this, never on message.
For the developer reading a log. May be reworded.
The field or parameter at fault, when there is one.
Example
{ "error": { "type": "validation_failure" }}authorization_failure with merchant_mismatch: a Merchant-Id header, query parameter or body field names a merchant or tenant other than the key’s.
object
object
A stable name for this refusal. Branch on this, never on message.
For the developer reading a log. May be reworded.
The field or parameter at fault, when there is one.
Example
{ "error": { "type": "validation_failure" }}not_found: resource_missing for an id this key cannot see, route_missing for a path that does not exist.
object
object
A stable name for this refusal. Branch on this, never on message.
For the developer reading a log. May be reworded.
The field or parameter at fault, when there is one.
Example
{ "error": { "type": "validation_failure" }}conflict: intent_state when the intent is not in a state that allows this; idempotency_key_reused when the Idempotency-Key was used for a different request. timeout_or_in_progress with idempotency_key_in_use while a request with the same key is still running, or with refund_in_progress for a refund while another refund of the same payment is still being processed.
object
object
A stable name for this refusal. Branch on this, never on message.
For the developer reading a log. May be reworded.
The field or parameter at fault, when there is one.
Example
{ "error": { "type": "validation_failure" }}dependency_failure with service_unavailable: something on our side, or a payment network behind it, did not answer, or failed part-way. Whether the call took effect is not known, so do not assume it did not. Retry the same request with the same Idempotency-Key, and never make a new key for the retry: if the first call took effect, you are answered with its result (the payment intent or refund it made, or the intent as it now is) and nothing is done a second time. A retry refused with conflict and intent_state means the intent is no longer in a state that allows the call: the first call may have taken effect, or the customer may have acted since. Read the intent. If the failure came while the answer was being stored, the key is held for five minutes and a retry in that time answers 409 with idempotency_key_in_use: retry shortly. See When a write answers 503.
object
object
A stable name for this refusal. Branch on this, never on message.
For the developer reading a log. May be reworded.
The field or parameter at fault, when there is one.
Example
{ "error": { "type": "validation_failure" }}