# Incremental authorization

This endpoint allows you to increase the authorized amount for an existing card transaction when the initial authorization is insufficient. The additional amount is appended to the original authorization, and the total authorized amount reflects both.

Endpoint: POST /payments/{id}/incrementals
Version: 2.0.0
Security: bearerAuth, basicAuth

## Path parameters:

  - `id` (string, required)
    payId assigned by Axepta Online in the initial request.

## Header parameters:

  - `Idempotency-Key` (string)
    A unique key provided by you to ensure that a particular operation is not processed multiple times in case of retries.

## Request fields (application/json):

  - `transId` (string, required)
    Transaction ID created in your system. It should be unique for each payment.

  - `amount` (object, required)

  - `amount.value` (number, required)
    Total order amount in smallest currency unit including taxes, shipping costs, discounts, etc.

  - `amount.currency` (string, required)
    3-character ISO currency code.

  - `duration` (number)
    Indicates the additional number of days to be added to the stay or rental. Valid only for merchants operating in specific industries like Hotel/Car rental.

## Response 200 fields (application/json):

  - `payId` (string)
    A unique identifier assigned by Axepta Online to the payment. This ID remains constant throughout the lifecycle of the payment and is used to track and reference the payment across all subsequent operations, such as authorization, capture, refund, or cancellation.

  - `merchantId` (string)
    Merchant ID assigned by Axepta Online.

  - `transId` (string)
    Transaction ID provided by you in the request.

  - `xId` (string)
    A unique identifier assigned by Axepta Online for each operation in the payment. For example: xId will be different for the authorization and capture operations of a payment whereas payId will be same.

  - `refNr` (string)
    Reference number provided by you in the request.

  - `status` (string)
    Status of the transaction.

  - `responseCode` (string)
    Response code of the transaction.

  - `responseDescription` (string)
    Response description associated with the response code.

  - `paymentMethods` (object)

  - `paymentMethods.ratepay` (object)

  - `paymentMethods.ratepay.authorizationExpiry` (string)
    The date and time when remaining un-cancelled and un-captured authorized amount will be automatically cancelled. Available only for successful responses HTTP 201.

  - `paymentMethods.ratepay.account` (object)

  - `paymentMethods.ratepay.account.bankName` (string)
    Bank name of the bank account the customer has to transfer the money to. Provided only when paymentMethod.ratepay.transferType is sent as BANK_TRANSFER in request.

  - `paymentMethods.ratepay.account.code` (string)
    Bank identifier code of the bank account the customer has to transfer the money to. Provided only when paymentMethod.ratepay.transferType is sent as BANK_TRANSFER in request.

  - `paymentMethods.ratepay.account.number` (string)
    International bank account number of the bank account the customer has to transfer the money to. Provided only when paymentMethod.ratepay.transferType is sent as BANK_TRANSFER in request.

  - `paymentMethods.ratepay.account.accountHolderName` (string)
    Account holder of the bank account the customer has to transfer the money to. Provided only when paymentMethod.ratepay.transferType is sent as BANK_TRANSFER in request.

  - `paymentMethods.ratepay.paymentReference` (string)
    Purpose to be indicated in the bank transfer (generated by Ratepay). Provided only when paymentMethod.ratepay.transferType is sent as BANK_TRANSFER in request.

  - `paymentMethods.ratepay.providerTransactionId` (string)
    ID of transaction generated by Ratepay during authorization. A transaction ID is generated for both accepted and declined transactions.

## Response 400 fields (application/json):

  - `field` (string)
    Example: "transId"

  - `error` (string)
    Example: "This field is required."

## Response 422 fields (application/json):

  - `payId` (string)
    A unique identifier assigned by Axepta Online to the payment. This ID remains constant throughout the lifecycle of the payment and is used to track and reference the payment across all subsequent operations, such as authorization, capture, refund, or cancellation.

  - `merchantId` (string)
    Merchant ID assigned by Axepta Online.

  - `transId` (string)
    Transaction ID provided by you in the request.

  - `xId` (string)
    A unique identifier assigned by Axepta Online for each operation in the payment. For example: xId will be different for the authorization and capture operations of a payment whereas payId will be same.

  - `refNr` (string)
    Reference number provided by you in the request.

  - `status` (string)
    Status of the transaction.

  - `responseCode` (string)
    Response code of the transaction.

  - `responseDescription` (string)
    Response description associated with the response code.

  - `paymentMethods` (object)

  - `paymentMethods.ratepay` (object)

  - `paymentMethods.ratepay.providerDeclineCategory` (string)
    Decline category provider by Ratepay. See Decline Categories for details.

  - `paymentMethods.ratepay.providerResponseText` (string)
    A message from Ratepay describing which constraint was violated.

  - `paymentMethods.ratepay.providerResponseCode` (string)
    List of none, one or multiple reasons why the request was declined. See Decline Categories to learn about possible reasons for each decline category.

## Response 500 fields (application/json):

  - `responseCode` (string)
    Example: "A specific identifier for the error cause"

  - `responseDescription` (string)
    Example: "A brief message explaining the error"