Incremental Authorization

Overview

Incremental authorization enables merchants to increase the authorized amount on an existing payment without creating a new authorization. This is commonly used in industries where the final transaction amount isn't known at the time of initial authorization, for example:

• Hotels: Guest extends stay or incurs additional charges.
• Car Rentals: Rental period extension or additional fees.
• Restaurants: Adding tip to the bill.

Instead of creating a new authorization, which would hold additional funds on the customer's card, incremental authorization increases the existing hold, providing a better customer experience.

Prerequisites

Before using Incremental Authorization, ensure the following:

• Original authorization exists: A valid, approved authorization must exist for the payment.
• Authorization not expired: The original authorization must not be expired.
• Not the final capture: The payment must not have been final captured.
• Currency matches: The incremental amount must be in the same currency as the original authorization.
• Visa amounts non-zero: Visa does not support zero-amount incremental authorizations (Mastercard does).
• Remaining amount non-zero: The authorized remaining amount must be available and not zero.

Inputs

Incremental authorizations operate on the initial payment transaction using the paymentTransactionId.

Authorization	Mutation	Input
Initial	authorizePaymentCard	Normal auth for $800
Incremental	incrementalAuthorizePaymentTransaction	paymentTransactionId + additional $500

incrementalAuthorizePaymentTransaction input

{
  "input": {
    "paymentTransactionId": "acqpt_552b9415686744859fb12585c1fd5b48",
    "amount": {
      "value": 100,
      "currencyCode": "USD"
    },
    "idempotencyKey": "B238076C-FCB4-44EE-9E90-E37ABA711A98"
  }
}

Field	Type	Required	Description
paymentTransactionId	String	Yes	ID of the existing payment to increment
amount	MoneyInput	Visa: Yes, Mastercard: No	Additional amount to authorize
amount.value	Integer	Yes	Monetary value (e.g., 5000)
amount.currencyCode	String	Yes	ISO 4217 currency code (e.g., USD)
idempotencyKey	String	No

Best practices

• Check authorization validity: Before attempting an incremental authorization, verify the original authorization hasn't expired.
• Handle declines gracefully: If an incremental authorization is declined, consider creating a new authorization.
• Monitor expiration: Authorization validity periods vary by card network and merchant category.
• Currency consistency: Always use the same currency as the original authorization.

Request incremental authorization

Use the incrementalAuthorizePaymentTransaction mutation to increase the authorized amount on an existing payment.

incrementalAuthorizePaymentTransaction

Query

mutation IncrementalAuthorizePaymentTransaction(
  $input: IncrementalAuthorizePaymentTransactionInput!
) {
  incrementalAuthorizePaymentTransaction(input: $input) {
    __typename
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
    ... on CardAuthorizationStepSummary {
      amount {
        value
        currencyCode
      }
      createdAt
      transaction {
        __typename
        id
        createdAt
        accountingDirection
        authorizedAmount {
          value
          currencyCode
        }
        authorizedRemainingAmount {
          value
          currencyCode
        }
        canceledAmount {
          value
          currencyCode
        }
        networkTransactionIdentifier
        settledAmount {
          value
          currencyCode
        }
        disbursedAmount {
          value
          currencyCode
        }
        refundedAmount {
          value
          currencyCode
        }
        responseCode {
          addressCode
          postalCode
          securityCode
          authorizationCode
          processorResponseCode
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentTransactionId": "acqpt_01",
    "amount": {
      "value": 100,
      "currencyCode": "USD"
    },
    "idempotencyKey": "UUID v4"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "incrementalAuthorizePaymentTransaction": {
      "__typename": "CardAuthorizationStepSummary",
      "amount": {
        "value": 100,
        "currencyCode": "USD"
      },
      "createdAt": "2026-01-09T18:36:14.562Z",
      "transaction": {
        "__typename": "PaymentDebitTransactionSummary",
        "id": "<payment-id>",
        "createdAt": "2026-01-09T18:36:14.562Z",
        "accountingDirection": "DEBIT",
        "authorizedAmount": {
          "value": 218,
          "currencyCode": "USD"
        },
        "authorizedRemainingAmount": {
          "value": 218,
          "currencyCode": "USD"
        },
        "canceledAmount": null,
        "networkTransactionIdentifier": "MCSKUV38O",
        "settledAmount": null,
        "disbursedAmount": null,
        "refundedAmount": null,
        "responseCode": {
          "addressCode": "SKIPPED",
          "postalCode": "SKIPPED",
          "securityCode": "SKIPPED",
          "authorizationCode": "58349Z",
          "processorResponseCode": "APPROVED"
        }
      }
    }
  },
  "extensions": {
    "requestId": "1c320813-7f6d-492a-8c8d-021bd3f2e3ab",
    "rateLimit": {
      "cost": 19,
      "limit": 60060,
      "remaining": 60040,
      "asOf": "2026-01-09T18:36:34.624Z",
      "complexity": {
        "limit": 60060,
        "remaining": 60040,
        "cost": 19
      },
      "count": {
        "limit": 60060,
        "remaining": 60058,
        "cost": 1
      }
    }
  }
}

Request $0 incremental authorization

info

Zero dollar incremental authorization only applies to Mastercard authorizations.

Use the following mutation to run an incremental authorization of zero dollars ($0) and extend the expiration date of the original authorization.

incrementalAuthorizePaymentTransaction

Query

mutation IncrementalAuthorizePaymentTransaction(
  $input: IncrementalAuthorizePaymentTransactionInput!
) {
  incrementalAuthorizePaymentTransaction(input: $input) {
    __typename
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
    ... on CardAuthorizationStepSummary {
      amount {
        value
        currencyCode
      }
      createdAt
      transaction {
        __typename
        id
        createdAt
        accountingDirection
        authorizedAmount {
          value
          currencyCode
        }
        authorizedRemainingAmount {
          value
          currencyCode
        }
        canceledAmount {
          value
          currencyCode
        }
        networkTransactionIdentifier
        settledAmount {
          value
          currencyCode
        }
        disbursedAmount {
          value
          currencyCode
        }
        refundedAmount {
          value
          currencyCode
        }
        responseCode {
          addressCode
          postalCode
          securityCode
          authorizationCode
          processorResponseCode
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentTransactionId": "acqpt_38563e7c4597456cbe03dd6c05eacf16",
    "amount": {
      "value": 0,
      "currencyCode": "USD"
    },
    "idempotencyKey": "UUID_v4"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "incrementalAuthorizePaymentTransaction": {
      "__typename": "CardAuthorizationStepSummary",
      "amount": {
        "value": 0,
        "currencyCode": "USD"
      },
      "createdAt": "2026-01-23T23:04:12.339Z",
      "transaction": {
        "__typename": "PaymentDebitTransactionSummary",
        "id": "acqpt_9b2b14deb2f34543b2b12b62ced47b9c",
        "createdAt": "2026-01-23T23:04:12.339Z",
        "accountingDirection": "DEBIT",
        "authorizedAmount": {
          "value": 100000,
          "currencyCode": "USD"
        },
        "authorizedRemainingAmount": {
          "value": 75000,
          "currencyCode": "USD"
        },
        "canceledAmount": null,
        "networkTransactionIdentifier": "MCCQMP04RLBT",
        "settledAmount": null,
        "disbursedAmount": null,
        "refundedAmount": null,
        "responseCode": {
          "addressCode": "SKIPPED",
          "postalCode": "SKIPPED",
          "securityCode": "SKIPPED",
          "authorizationCode": "BBFROI",
          "processorResponseCode": "APPROVED"
        }
      }
    }
  }
}