> ## Documentation Index > Fetch the complete documentation index at: https://docs.payra.com/llms.txt > Use this file to discover all available pages before exploring further. # Cancel a terminal payment > Stops a terminal payment while the terminal still waits for a card: the payment answers `canceled` with `cancellation_reason: requested`. Once a card was presented, it is refused and the payment finishes on its own. Canceling a terminal payment that is already canceled answers it as it is. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /payments/{id}/cancel openapi: 3.1.0 info: title: Payra API version: v1 description: >- The Payra API. Authenticate with a secret key: `Authorization: Bearer sk_test_...`. The two payment method session endpoints Payra Elements calls also take a publishable key with the session's `client_secret`. servers: - url: https://api-dashboard.payra.com/v1 description: 'Sandbox and live: the key decides which' security: [] paths: /payments/{id}/cancel: post: tags: - Payments summary: Cancel a terminal payment description: >- Stops a terminal payment while the terminal still waits for a card: the payment answers `canceled` with `cancellation_reason: requested`. Once a card was presented, it is refused and the payment finishes on its own. Canceling a terminal payment that is already canceled answers it as it is. parameters: - schema: type: string minLength: 1 maxLength: 64 required: true name: id in: path responses: '200': description: The payment content: application/json: schema: $ref: '#/components/schemas/Payment' '400': description: >- Not a terminal payment still waiting for a card (`payment_not_cancelable`) content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, invalid or revoked API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The API is not enabled for the workspace, or the key lacks the scope content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No such payment in this workspace content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The cancel could not be confirmed and the payment is still waiting; retry the cancel content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded; see Retry-After content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: Payment: type: object properties: object: type: string enum: - payment id: type: string example: pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf status: type: string enum: - processing - requires_action - authorized - succeeded - failed - canceled - returned example: succeeded description: >- `processing` until the processor answers, and, on a bank debit, until it settles, that is until the processor sends it to the bank in its next batch; `authorized` when it approved but has not captured; `succeeded` once a card is captured or a bank debit has settled, which does not make a bank debit final (see `returned`); `failed` when it refused (the create then answers 402 and this object stays readable); `canceled` after a void, a cancel, or a terminal payment nobody paid within five minutes (see `cancellation_reason`); `returned` when the money came back after success (a bank return or a chargeback, see `failure`); `requires_action` while the customer has to pass 3-D Secure at `next_action.url`, which only a charge created with a `return_url` can reach; it then moves to `succeeded` or `failed`. amount: type: integer example: 12550 description: In the smallest unit of the currency (cents). amount_refunded: type: integer default: 0 example: 0 description: >- How much of `amount` has been refunded so far, counting refunds that succeeded, wherever they were made. `status` stays `succeeded`; `GET /v1/refunds?payment=` lists them. currency: type: string enum: - USD - CAD example: USD payment_method: type: - string - 'null' example: pm_test_9kQ2mL7Hs1pXv4cR8tWzAbCdEf description: >- The payment method charged; null on a terminal payment, where the customer presented the card on the terminal. payment_method_type: type: string enum: - card - us_bank_account - acss_debit - card_present default: card example: card description: >- `us_bank_account` for a US bank debit (ACH), `acss_debit` for a Canadian one (EFT), `card_present` for a terminal payment. More values may be added: treat one you do not know as a card. customer: type: - string - 'null' format: uuid example: null terminal: type: - string - 'null' default: null example: null description: >- The terminal a terminal payment was sent to (`GET /v1/terminals/{id}`); null on any other payment. description: type: - string - 'null' example: Invoice INV-1042 reference: type: - string - 'null' example: INV-1042 description: Your reference, as you sent it. line_items: type: - array - 'null' items: $ref: '#/components/schemas/LineItem' default: null example: null description: >- The order behind `amount`, as you sent it (or as the checkout session it was paid on had it); null when there was none. amount_details: type: - object - 'null' properties: shipping: type: integer example: 499 tax: type: integer example: 158 discount: type: integer example: 500 default: null required: - shipping - tax - discount example: null description: >- Shipping, tax and discount around `line_items`; null when none were sent. card: $ref: '#/components/schemas/PaymentCard' us_bank_account: type: - object - 'null' properties: last4: type: - string - 'null' example: '6789' description: Null when the account number has fewer than 7 digits. account_type: type: string enum: - checking - savings example: checking account_holder_type: type: string enum: - individual - company example: individual default: null required: - last4 - account_type - account_holder_type description: Set when `payment_method_type` is `us_bank_account`. example: null acss_debit: type: - object - 'null' properties: last4: type: string example: '3191' account_type: type: string enum: - checking - savings example: checking account_holder_type: type: string enum: - individual - company example: individual institution_number: type: string example: '001' description: The three-digit financial institution number. transit_number: type: string example: '00114' description: The five-digit branch transit number. default: null required: - last4 - account_type - account_holder_type - institution_number - transit_number description: Set when `payment_method_type` is `acss_debit`. example: null failure: type: - object - 'null' properties: code: type: string enum: - card_declined - insufficient_funds - authentication_failed - invalid_payment_method - duplicate_transaction - ach_returned - acss_returned - chargeback - processing_error example: invalid_payment_method reason: type: - string - 'null' enum: - cardholder_name_incomplete - expired_card - invalid_expiry_date - incorrect_cvc - incorrect_number - withdrawal_limit_exceeded - card_blocked - restricted_card - suspected_fraud example: expired_card description: >- Finer than `code`, when the processor says exactly what it refused: `cardholder_name_incomplete`, `expired_card`, `invalid_expiry_date`, `incorrect_cvc` and `incorrect_number` come with `invalid_payment_method`; `withdrawal_limit_exceeded`, `card_blocked`, `restricted_card` and `suspected_fraud` with `card_declined`. Null when it does not say. More values may be added. message: type: string example: The card has expired. required: - code - reason - message description: >- Set when `status` is `failed` or `returned`: why, in a fixed vocabulary. `card_declined`, `insufficient_funds`, `authentication_failed`, `invalid_payment_method` and `duplicate_transaction` are the processor refusing the card; `ach_returned`, `acss_returned` and `chargeback` are money coming back after success; `processing_error` is a fault on the way to the processor or in the request, safe to retry later; a refusal in words Payra cannot classify reads `card_declined`. `message` is Payra's own sentence for the reason, or for the code when there is none; the processor's own text is never relayed. cancellation_reason: type: - string - 'null' enum: - requested - expired - voided default: null example: null description: >- Set when `status` is `canceled`: `requested` (canceled on request before the card was presented, through the API or in RevOS), `expired` (no card was presented within five minutes) or `voided` (voided before the batch, in RevOS or by a full refund). More values may be added. next_action: type: - object - 'null' properties: type: type: string enum: - redirect url: type: string required: - type - url example: null description: >- Set while `status` is `requires_action`: send the customer to `url` for 3-D Secure. Only a charge created with a `return_url` can be challenged; otherwise this is null. livemode: type: boolean example: false created_at: type: string format: date-time example: '2026-09-18T20:00:00.000Z' succeeded_at: type: - string - 'null' format: date-time example: '2026-09-18T20:00:01.312Z' description: When the card was captured, or the bank debit settled. required: - object - id - status - amount - currency - payment_method - customer - description - reference - card - failure - next_action - livemode - created_at - succeeded_at Error: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - idempotency_error - card_error - api_error code: type: string message: type: string param: type: string request_id: type: string required: - type - code - message - request_id additionalProperties: type: string required: - error LineItem: type: object properties: sku: type: - string - 'null' example: VHC-BL-12 description: type: string example: Blue widget, case of 12 quantity: type: integer example: 2 unit_amount: type: integer example: 900 amount: type: integer example: 1800 description: '`quantity` × `unit_amount`.' required: - sku - description - quantity - unit_amount - amount PaymentCard: type: - object - 'null' properties: brand: type: - string - 'null' example: visa last4: type: string example: '4242' exp_month: type: integer example: 12 exp_year: type: integer example: 2030 required: - brand - last4 - exp_month - exp_year description: Set when `payment_method_type` is `card`. securitySchemes: bearerAuth: type: http scheme: bearer description: >- A secret key, `sk_test_...` or `sk_live_...`; a publishable key (`pk_...`) on the browser routes only ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.