---
title: "Increment authorization"
method: POST
path: "/payments/{id}/authorizations"
tags: ["Payments"]
---

# Increment authorization

`POST /payments/{id}/authorizations`

## Request

- Base URL: `https://{prefix}.api.sandbox.checkout.com`
- URL: `https://{prefix}.api.sandbox.checkout.com/payments/{id}/authorizations`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `string` scopes: `gateway`, `gateway:payment-authorizations`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/payments/:id/authorizations/post.ts> (a function with typed inputs; its response is checked against the schema)

Request an incremental authorization to increase the authorization amount or extend the authorization's validity period.

## Path parameters

- `id` string, required

## Headers

- `Cko-Idempotency-Key` string

## Request body

- AuthorizationRequest
  - `amount` integer: The amount to increase the authorization by. Omit the amount or provide a value of `0` to extend the authorization validity period
  - `reference` string: A reference you can later use to identify this authorization request
  - `metadata` object: A set of key-value pairs to attach to the authorization request. You can use this to store additional information in a structured format. The `metadata` object only supports primitive data types. Objects and arrays are not supported.

## Response `201`

Authorization processed successfully

- AuthorizationResponse: Authorization Response
  - `action_id` string, required: The action identifier
  - `amount` integer, required: The payment amount
  - `currency` string, required: The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO currency code</a> of the payment
  - `approved` boolean, required: Whether or not the authorization was successful
  - `status` 'Authorized' | 'Declined', required: The status of the payment
  - `auth_code` string: The acquirer authorization code if the payment was authorized
  - `response_code` string, required: The Gateway response code
  - `response_summary` string: The Gateway response summary
  - `expires_on` string: The timestamp (ISO 8601 code) for when the authorization's validity period ends
  - `balances` PaymentResponseBalances: The balances of the payment
    - `total_authorized` integer: The total amount that has been authorized
    - `total_voided` integer: The total amount that has been voided
    - `available_to_void` integer: The total amount that is still available for voiding
    - `total_captured` integer: The total amount that has been captured
    - `available_to_capture` integer: The total amount that is still available for capture
    - `total_refunded` integer: The total amount that has been refunded
    - `available_to_refund` integer: The total amount that is still available for refund
  - `processed_on` string, date-time, required: Read-only UTC timestamp, automatically assigned by us
  - `reference` string: Your reference for the payment
  - `processing` object: Returns information related to the processing of the payment
    - `retrieval_reference_number` string: A unique identifier for the authorization that is submitted to the card scheme during processing
    - `acquirer_transaction_id` string: A unique identifier for the transaction generated by the acquirer
    - `recommendation_code` string: A <a href="https://www.checkout.com/docs/resources/codes/recommendation-codes" target="blank">code</a> that represents the next recommended action for the payment
    - `surcharge_amount` integer: Surcharge amount applied to the transaction in minor units by the merchant
    - `scheme_transaction_link_id` string: The scheme transaction link identifier.
  - `eci` string: The final Electronic Commerce Indicator (ECI) security level used to authorize the payment. Applicable for 3D Secure and network token payments
  - `scheme_id` string: The scheme transaction identifier
  - `_links` object, required: The links related to the payment
    - `self` Link, required
      - `href` string, required: The link URL
    - `actions` Link, required
      - `href` string, required: The link URL
    - `authorize` Link
      - `href` string, required: The link URL
    - `void` Link
      - `href` string, required: The link URL
    - `capture` Link
      - `href` string, required: The link URL
    - `refund` Link
      - `href` string, required: The link URL

## Other responses

- `401`: Unauthorized
- `403`: Incremental authorization not allowed
- `404`: Payment not found
- `422`: Invalid data was sent
- `502`: Bad gateway

---

[API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)