Cancel Payment Intent

POST 
/payment_intents/:id/cancel

Cancel a payment intent that has not been used, so its client secret can no longer create a payment.

Use it when the customer abandons checkout, or when your backend decides the order should not be paid after all.

Only an intent that is still created and unexpired can be canceled. An intent that is already fulfilled, canceled, or expired returns intent_not_cancelable; an expired intent needs no cancellation, as it is already unusable.

No request body is needed.

Request

Path Parameters

id uuidrequired

ID of the payment intent to cancel.

Responses

200

Successful operation

application/json

Schema

Schema

id uuidrequired

Unique identifier of the payment intent.

amount Amount (integer)required
Possible values: >= 100
A positive integer representing the payment amount in the smallest currency unit.
Examples:
• 1.00 SAR = 100
• 1.00 KWD = 1000
• 1 JPY = 1
currency Currency (string)required

ISO-4217 three-letter currency code.

description stringnullable
callback_url urinullable
status PaymentIntentStatus (string)required

Possible values: [created, fulfilled, canceled]

The intent's own lifecycle, not the payment's outcome.

• created — awaiting fulfillment. Fulfillable until expires_at passes.
• fulfilled — the intent was used to create a payment. Whether that payment was approved or declined is tracked on the payment, not here.
• canceled — canceled before use; the client_secret no longer works.

Expiry is not a status. An intent past its expires_at stays created but can no longer be fulfilled or canceled.

client_secret ClientSecret (string)required

Possible values: Value must match regular expression ^pi_secret_

Single-use token that authorizes fulfillment of this intent. Pass it to your frontend and treat it as a credential — it is all a browser needs, alongside your publishable key, to create this one payment.

expires_at date-timerequired

Fulfillment deadline. Set automatically to one hour after creation.

fulfilled_at date-timenullable

Date and time when the intent was fulfilled. null until then.

created_at date-timerequired

Example (from schema)

{
  "id": "8f4d1c3e-6a52-4f0b-9a1e-2c7b5d8e0f31",
  "amount": 100,
  "currency": "SAR",
  "description": "Order",
  "callback_url": "https://example.com/checkout/payer-return",
  "status": "created",
  "client_secret": "pi_secret_7Kq2mXbN9vT4wPzR1sYcHdLjF6aGuE8oQ3iK5nB0xVtZrWyM",
  "expires_at": "2024-07-29T15:51:28.071Z",
  "fulfilled_at": "2024-07-29T15:51:28.071Z",
  "created_at": "2024-07-29T15:51:28.071Z"
}

400

Business Error. type is intent_not_cancelable when the intent is already fulfilled, canceled, or expired.

application/json

Schema

Schema

type string

Contains the error type

message string

Human readable error message for the error

errors object

Contains string-array pair representing a field and list of validation errors.

Example (from schema)

{
  "type": "invalid_request",
  "message": null,
  "errors": {
    "foo": "this is returned for validation errors only"
  }
}

401

Invalid authorization credentials

application/json

Schema

Schema

type string

Possible values: [authentication_error]

message string

Possible values: [Invalid authorization credentials]

errors object

Example (from schema)

{
  "type": "authentication_error",
  "message": "Invalid authorization credentials",
  "errors": null
}

403

The request was not authenticated with the secret key.

application/json

Schema

Schema

type string

Possible values: [api_error]

message string

Possible values: [User not authorized]

errors object

Example (from schema)

{
  "type": "api_error",
  "message": "User not authorized",
  "errors": null
}

404

Payment intent not found.

application/json

Schema

Schema

type string

Possible values: [record_not_found]

message string
errors object

Example (from schema)

{
  "type": "record_not_found",
  "message": "The <object type> record you were looking for was not found.",
  "errors": null
}

Loading...