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

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Increment Authorization

> Raises an existing authorization hold by a delta amount, without creating a new authorization.

This request raises the amount of a previously authorized payment (an incremental authorization). It is designed for open-ended-amount scenarios — EV charging, fuel, hospitality, car rental — where you authorize a small amount first and grow the hold as the final amount becomes known, then capture once with the [capture API](https://docs.y.uno/reference/payments/capture-authorization.md).

The `amount` you send is a **delta**: how much to add to the current authorized amount. Yuno translates it to each provider's expected semantics.

Each increment creates its own `AUTHORIZE_INCREMENT` transaction with a per-increment result, visible in [Retrieve Payment](https://docs.y.uno/reference/payments/retrieve-payment-by-id-v2.md). Increments are notified with the `payment.authorize` [webhook event](https://docs.y.uno/docs/webhooks/events.md), so subscribe to the `AUTHORIZE` trigger to receive them; there is no separate increment event. A successful increment raises `payment.amount.authorized`; `payment.amount.value` keeps the original amount. A declined increment leaves the previously authorized amount untouched. Multiple increments can be performed on the same authorization, but they must be sequential: a new increment requested while a previous one is still in progress returns a `400`.

Note that this request requires an `X-Idempotency-Key`. Check the [Authentication](https://docs.y.uno/reference/authentication.md#idempotency) page for more information.

## Capturing after increments

A [capture](https://docs.y.uno/reference/payments/capture-authorization.md) with an explicit `amount` can settle any amount up to the current total authorized (original authorization plus all succeeded increments). A capture **without an amount** settles the transaction's full current hold — the original authorized amount plus all `SUCCEEDED` increments on that transaction. Increments still `PENDING` at capture time are not included.

> [!WARNING]
>
> **The original authorization must opt in**
>
> Some providers only allow increments on authorizations created as pre-authorization holds. Set `authorization_type: "PRE_AUTHORIZATION"` (together with `capture: false`) when [creating the payment](https://docs.y.uno/reference/payments/create-payment.md); see the [Cancel and Capture Flow](https://docs.y.uno/docs/payment-features/Cancel-and-capture-flow.md#pre-authorization-holds-authorization_type) guide. When the provider rejects the increment — because the original authorization was not a pre-authorization, or because the provider's increment limits were exceeded (for example more than 10 increments, or a total above 5× the initial amount) — the increment transaction is returned with the `AUTHORIZATION_NOT_INCREMENTABLE` response code.

## Provider support

Support is provider-dependent. If the provider routed for the payment does not support incremental authorizations, the call still returns `201`, but with an increment transaction whose `status` is `ERROR` and whose `response_code` is `OPERATION_NOT_SUPPORTED_BY_PROVIDER` — it is not an HTTP error, so branch on the transaction `status`, not the HTTP status code. The previously authorized amount is left untouched.

**Revolut** is currently the only provider with incremental authorization support.

| Provider | Result | Notes |
| - | - | - |
| Revolut | Asynchronous | The transaction is returned as `PENDING`; the final result is delivered via the `payment.authorize` webhook. Increments require the original authorization created with `authorization_type: "PRE_AUTHORIZATION"`, are available on card, Apple Pay, and Google Pay only, can only be tested in Production (not available in sandbox), and are limited to 10 sequential increments with a total of up to 5× the initial amount |

Other providers (Stripe, Adyen, Checkout.com, CyberSource) are on the roadmap and not yet available; calling the endpoint on them today returns the `OPERATION_NOT_SUPPORTED_BY_PROVIDER` transaction described above.


## OpenAPI

````yaml openapi/payments/increment-authorization.json POST /payments/{payment_id}/transactions/{transaction_id}/increment
openapi: 3.1.0
info:
  title: payment-api-increment-authorization
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
    sec2: []
paths:
  /payments/{payment_id}/transactions/{transaction_id}/increment:
    post:
      summary: Increment Authorization
      description: >-
        Raises an existing authorization hold by a delta amount. Each increment
        creates its own `AUTHORIZE_INCREMENT` transaction with a per-increment
        result.
      operationId: increment-authorization
      parameters:
        - name: payment_id
          in: path
          description: The unique identifier of the payment (UUID, 36 chars).
          schema:
            type: string
          required: true
        - name: transaction_id
          in: path
          description: >-
            The unique identifier of the original AUTHORIZE transaction to
            increment (UUID, 36 chars).
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - merchant_reference
              properties:
                amount:
                  type: object
                  description: >-
                    The amount to ADD to the current authorized amount (a delta,
                    not the new total). The currency must match the original
                    authorization.
                  required:
                    - value
                    - currency
                  properties:
                    value:
                      type: number
                      description: The delta to add to the current authorized amount.
                      example: 50
                    currency:
                      type: string
                      description: >-
                        Three-letter ISO 4217 currency code. Must match the
                        original authorization.
                      example: EUR
                merchant_reference:
                  type: string
                  description: The reference for this increment.
                description:
                  type: string
                  description: Optional description of the increment.
            examples:
              Increment by 50:
                value:
                  amount:
                    value: 50
                    currency: EUR
                  merchant_reference: session-8842-inc-2
                  description: EV charging session top-up
      responses:
        '201':
          description: '201'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier of the increment transaction (UUID).
                  type:
                    type: string
                    description: Transaction type.
                    example: AUTHORIZE_INCREMENT
                  status:
                    type: string
                    enum:
                      - SUCCEEDED
                      - DECLINED
                      - PENDING
                      - ERROR
                    description: >-
                      Per-increment result. `SUCCEEDED`: the hold was raised.
                      `DECLINED`: the issuer or provider declined this
                      increment; the previous authorized amount stands.
                      `PENDING`: the provider processes increments
                      asynchronously; the final result is delivered via webhook.
                      `ERROR`: the increment could not be processed.
                  amount:
                    type: object
                    description: The delta added by this increment.
                    properties:
                      value:
                        type: number
                        example: 50
                      currency:
                        type: string
                        example: EUR
                  merchant_reference:
                    type: string
                    description: The reference sent in the request.
                  parent_transaction_id:
                    type: string
                    description: >-
                      The `transaction_id` of the original AUTHORIZE transaction
                      this increment belongs to.
                  response_code:
                    type: string
                    description: >-
                      Yuno response code for this increment: the transaction
                      sub-status when the provider returns one, otherwise the
                      transaction status (for example `SUCCEEDED`,
                      `PENDING_PROVIDER_CONFIRMATION`,
                      `AUTHORIZATION_NOT_INCREMENTABLE`). It is not an ISO 8583
                      issuer code. `AUTHORIZATION_NOT_INCREMENTABLE` indicates
                      the provider rejected the increment — either the original
                      authorization was not created as `PRE_AUTHORIZATION`, or
                      the provider's increment limits were exceeded (for example
                      more than 10 increments, or a total above 5× the initial
                      amount on Revolut).
                  response_message:
                    type: string
                    description: Human-readable detail of the result.
                  provider_data:
                    type: object
                    description: Raw provider identifiers and status for this increment.
                  payment:
                    type: object
                    description: The parent payment after this increment.
                    properties:
                      id:
                        type: string
                        description: Unique identifier of the payment (UUID).
                      status:
                        type: string
                        example: AUTHORIZED
                      amount:
                        type: object
                        description: >-
                          Amounts of the parent payment. Increments do not
                          change `value`; they raise `authorized`.
                        properties:
                          value:
                            type: number
                            description: >-
                              The original payment amount. Not changed by
                              increments.
                            example: 100
                          authorized:
                            type: number
                            description: >-
                              Total authorized amount: the original
                              authorization plus all `SUCCEEDED` increments.
                              When the provider processes increments
                              asynchronously (Revolut), the increment is still
                              `PENDING` in this response, so `authorized` does
                              not include it yet; the raised total is reflected
                              once the increment succeeds.
                            example: 150
                          currency:
                            type: string
                            example: EUR
              examples:
                Approved Increment:
                  value:
                    id: 8f2f4bce-1d2f-4f6e-9a3b-0c1e5d3a7b21
                    type: AUTHORIZE_INCREMENT
                    status: SUCCEEDED
                    amount:
                      value: 50
                      currency: EUR
                    merchant_reference: session-8842-inc-2
                    parent_transaction_id: 1a71c7b7-80c2-4ba5-b601-4d34d48c0e18
                    response_code: SUCCEEDED
                    response_message: Approved
                    provider_data:
                      id: prov-ref-001
                      status: ...
                    payment:
                      id: d19205be-1a70-4c13-a4e6-8b7a9f3e2c11
                      status: PENDING
                      sub_status: AUTHORIZED
                      amount:
                        value: 100
                        authorized: 150
                        currency: EUR
                Pending Increment (async provider):
                  value:
                    id: 8f2f4bce-1d2f-4f6e-9a3b-0c1e5d3a7b21
                    type: AUTHORIZE_INCREMENT
                    status: PENDING
                    amount:
                      value: 50
                      currency: EUR
                    merchant_reference: session-8842-inc-2
                    parent_transaction_id: 1a71c7b7-80c2-4ba5-b601-4d34d48c0e18
                    response_code: PENDING_PROVIDER_CONFIRMATION
                    response_message: Increment in progress; final result delivered via webhook
                    provider_data:
                      id: prov-ref-001
                      status: ...
                    payment:
                      id: d19205be-1a70-4c13-a4e6-8b7a9f3e2c11
                      status: PENDING
                      sub_status: AUTHORIZED
                      amount:
                        value: 100
                        authorized: 100
                        currency: EUR
                Declined Increment:
                  value:
                    id: 8f2f4bce-1d2f-4f6e-9a3b-0c1e5d3a7b21
                    type: AUTHORIZE_INCREMENT
                    status: DECLINED
                    amount:
                      value: 50
                      currency: EUR
                    merchant_reference: session-8842-inc-2
                    parent_transaction_id: 1a71c7b7-80c2-4ba5-b601-4d34d48c0e18
                    response_code: DECLINED
                    response_message: Insufficient funds
                    provider_data:
                      id: prov-ref-001
                      status: ...
                    payment:
                      id: d19205be-1a70-4c13-a4e6-8b7a9f3e2c11
                      status: PENDING
                      sub_status: AUTHORIZED
                      amount:
                        value: 100
                        authorized: 100
                        currency: EUR
                Not Incrementable:
                  value:
                    id: 8f2f4bce-1d2f-4f6e-9a3b-0c1e5d3a7b21
                    type: AUTHORIZE_INCREMENT
                    status: DECLINED
                    amount:
                      value: 50
                      currency: EUR
                    merchant_reference: session-8842-inc-2
                    parent_transaction_id: 1a71c7b7-80c2-4ba5-b601-4d34d48c0e18
                    response_code: AUTHORIZATION_NOT_INCREMENTABLE
                    response_message: >-
                      The provider rejected the increment (not a
                      pre-authorization, or the provider's increment limits were
                      exceeded)
                    provider_data:
                      id: prov-ref-001
                      status: ...
                    payment:
                      id: d19205be-1a70-4c13-a4e6-8b7a9f3e2c11
                      status: PENDING
                      sub_status: AUTHORIZED
                      amount:
                        value: 100
                        authorized: 100
                        currency: EUR
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Invalid request:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - Invalid request
                Payment or transaction not found:
                  value:
                    code: TRANSACTION_NOT_FOUND
                    messages:
                      - Payment or transaction not found
                Transaction not an active authorization:
                  value:
                    code: INVALID_STATUS_WITH_FORMAT
                    messages:
                      - >-
                        The payment is not in an authorized hold state, the
                        authorization is not SUCCEEDED (already captured,
                        voided, or expired), or another increment is already in
                        progress
                Currency mismatch:
                  value:
                    code: INVALID_CURRENCY
                    messages:
                      - Currency does not match the original authorization
                Target transaction is not an authorization:
                  value:
                    code: INVALID_TRANSACTION_TYPE
                    messages:
                      - >-
                        The target transaction is not an AUTHORIZE transaction.
                        Use the transaction_id of the original authorization,
                        not a capture or purchase transaction.
                Invalid amount:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        Invalid amount. The increment amount (delta) must be
                        greater than zero.
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_REQUEST
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid request
        '401':
          description: '401'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: UNAUTHORIZED
                    messages:
                      - Invalid credentials
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_REQUEST
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid request
        '403':
          description: '403'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: FORBIDDEN
                    messages:
                      - Forbidden
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_REQUEST
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid request
      deprecated: false
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      x-default: <Your public-api-key>
      name: public-api-key
    sec1:
      type: apiKey
      in: header
      x-default: <Your private-secret-key>
      name: private-secret-key
    sec2:
      type: apiKey
      in: header
      x-default: <Your X-Idempotency-Key>
      name: X-Idempotency-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.