> ## Documentation Index
> Fetch the complete documentation index at: https://nextgen-docs.enfuce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send an Incremental Authorisation

> Send a request to this endpoint to increase the total authorised amount, submitted as an additional request after the initial authorisation request. This is commonly used in hospitality and car rental scenarios where the final amount is not known at check-in.

References the initial authorisation request by its `metadata.id`.




## OpenAPI

````yaml json-files/mycore-test-api.openapi.json post /v1/authorizations/incremental
openapi: 3.0.3
info:
  version: '1'
  title: Test API
  description: >
    Available in the integration environment. Use this API to simulate payment
    card transactions

    for integration testing and card programme.


    All endpoints require **HTTP Basic Authentication** with the `CAT2_API_ALL`
    role.
servers:
  - url: https://test-api.ext-uat1-sandbox.mycore.enfuce.com/test-api
security:
  - basicAuth: []
tags:
  - name: authorizations
    description: Send authorisation, reversal, advice, and adjustment messages.
  - name: incremental
    description: >-
      Incremental authorisation — add authorized amount on top of an existing
      authorization.
  - name: stip
    description: Stand-In Processing — simulate scheme-initiated authorization decisions.
  - name: batch-transactions
    description: Run a full transaction lifecycle in one call.
  - name: legacy
    description: Legacy load-testing endpoint.
paths:
  /v1/authorizations/incremental:
    post:
      tags:
        - incremental
      summary: Send an Incremental Authorisation
      description: >
        Send a request to this endpoint to increase the total authorised amount,
        submitted as an additional request after the initial authorisation
        request. This is commonly used in hospitality and car rental scenarios
        where the final amount is not known at check-in.


        References the initial authorisation request by its `metadata.id`.
      operationId: postIncrementalAuthorization
      parameters:
        - $ref: '#/components/parameters/auditUser'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/incrementalAuthorizationRequest'
            example:
              id: '123456789012345678'
              transactionData:
                transactionAmount:
                  amount: 50
                  currency: EUR
                transactionType: RETAIL
                cardEntryMode: CHIP_READ
      responses:
        '200':
          description: Incremental authorization processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authorizationResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
components:
  parameters:
    auditUser:
      name: auditUser
      in: query
      description: Identifier of the user performing the action, used for audit logging.
      required: true
      schema:
        type: string
  schemas:
    incrementalAuthorizationRequest:
      description: Incremental authorisation request payload.
      type: object
      required:
        - id
        - transactionData
      properties:
        id:
          $ref: '#/components/schemas/docId'
        transactionData:
          $ref: '#/components/schemas/transactionRequestData'
    authorizationResponse:
      description: Response to the request.
      type: object
      properties:
        metadata:
          type: object
          properties:
            mti:
              type: string
              description: ISO 8583 Message Type Indicator of the response.
              maxLength: 4
              example: '0110'
            id:
              $ref: '#/components/schemas/docId'
        transactionData:
          type: object
          properties:
            authResponseCode:
              $ref: '#/components/schemas/authResponseCode'
            retrievalReferenceNumber:
              $ref: '#/components/schemas/retrievalReferenceNumber'
    docId:
      type: string
      description: Unique authorization identifier (internal docId / ISO 8583 DE37).
      maxLength: 18
    transactionRequestData:
      description: Transaction details.
      type: object
      required:
        - transactionAmount
        - transactionType
        - cardEntryMode
      properties:
        transactionAmount:
          $ref: '#/components/schemas/moneyAmount'
        settlementAmount:
          $ref: '#/components/schemas/moneyAmount'
        transactionType:
          $ref: '#/components/schemas/transactionType'
        cardEntryMode:
          $ref: '#/components/schemas/cardEntryMode'
        transactionDateTime:
          type: string
          format: date-time
          description: >
            Date and time of the transaction in ISO 8601 format with timezone
            offset

            (e.g. `2025-05-21T14:30:00Z`). Defaults to current time if omitted.
          example: '2025-05-21T14:30:00Z'
    authResponseCode:
      type: string
      description: |
        ISO 8583 DE39 response code. Common values:
        - `00` — Approved
        - `05` — Do not honour
        - `51` — Insufficient funds
        - `54` — Expired card
      maxLength: 2
      example: '00'
    retrievalReferenceNumber:
      type: string
      description: |
        Merchant/acquirer reference number (ISO 8583 DE37).
        Stays the same across all messages in a transaction lifecycle.
      maxLength: 12
    errorResponse:
      description: Standard error response.
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        id:
          type: string
          format: uuid
        errorCode:
          type: string
        errorType:
          type: string
          enum:
            - STATIC_VALIDATION_ERROR
            - DYNAMIC_VALIDATION_ERROR
            - INTEGRATION_ERROR
            - SECURITY_ERROR
            - UNEXPECTED_ERROR
        errorReason:
          type: string
        timestamp:
          type: string
          format: date-time
    moneyAmount:
      description: A monetary amount with currency.
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: number
          minimum: 0
          example: 25
        currency:
          type: string
          description: ISO 4217 currency code.
          example: EUR
    transactionType:
      type: string
      description: |
        The transaction type.
        - `ATM` requires `merchantCategoryCode: 6011`
      enum:
        - RETAIL
        - CASH
        - ATM
        - CREDIT
        - UNIQUE
        - P2P_CREDIT
        - P2P_DEBIT
        - BALANCE_INQUIRY
    cardEntryMode:
      type: string
      description: How card credentials were captured.
      enum:
        - MANUAL_ENTRY
        - MAGNETIC_STRIPE_READ
        - CHIP_READ
        - CONTACTLESS
        - ELECTRONIC_COMMERCE
  responses:
    badRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    notFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    internalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth. Credentials must carry the `CAT2_API_ALL` role.

````