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

# POST Renewal Preauthorize

> Preauthorizes a configured amount for a subscription in a renewal cycle.

Preauthorize an amount for a new cycle of an existing subscription. This endpoint is used to process recurring payments on active subscriptions, linking the new transaction with the original preauthorization.

```bash theme={null}
curl --request POST 'https://tumipay-card-payments.uat.topup.com.co/production/api/v1/subscription/card/authorize/renewal' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'X-Merchant-ID: your_merchant_id' \
--header 'X-Request-ID: your-request-id' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subscription_id": "sub_93af8f63-97d1-4be0-9e0d-f6fd8c2d92a0",
    "reference_id": "ref_2025_002",
    "currency": "COP",
    "amount": 400000,
    "tax": 0,
    "linked_transaction_id": "7f45a9da-2f84-4103-ac54-05fe8ea693ca"
}'
```

```json Success - Renewal Authorization Successful (200) theme={null}
{
    "code": "AUTHORIZED",
    "status": true,
    "message": "Renovación de pago autorizada exitosamente",
    "data": {
        "transaction_id": "770e8400-e29b-41d4-a716-446655440002",
        "transaction_date": "2025-12-23T10:30:45Z",
        "linked_transaction_id": "660e8400-e29b-41d4-a716-446655440001",
        "transaction_status": "APPROVED",
        "transaction_type": "RENEWAL_PRE_AUTH_TRANSACTION",
        "reference_id": "reference-uuid-456",
        "amount": 150.0,
        "currency": "COP"
    }
}
```

```json Validation Error (422) theme={null}
{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "reference_id is required."
}
```

```json Missing Required Header - X-Merchant-ID (400) theme={null}
{
    "message": "Missing required header: X-Merchant-ID"
}
```

```json Missing Required Header - X-Request-ID (400) theme={null}
{
    "message": "Missing required header: X-Request-ID"
}
```

```json Internal Authentication Failed (401) theme={null}
{
    "code": "UNAUTHORIZED",
    "status": false,
    "message": "Unauthorized."
}
```

```json Subscription Not Found (404) theme={null}
{
    "code": "NOT_FOUND",
    "status": false,
    "message": "No se pudo localizar la suscripción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}
```

```json Invalid Subscription State - Not Active (422) theme={null}
{
    "code": "INVALID_STATE",
    "status": false,
    "message": "El pago no puede ser autorizado porque la suscripción no es válida."
}
```

```json Transaction Not Found (404) theme={null}
{
    "code": "NOT_FOUND",
    "status": false,
    "message": "No se pudo localizar la transacción solicitada con UUID: 660e8400-e29b-41d4-a716-446655440001"
}
```

```json Invalid Transaction State - Cannot Renew (422) theme={null}
{
    "code": "INVALID_STATE",
    "status": false,
    "message": "El pago no puede ser renovado porque la transacción original no está aprobada."
}
```

```json Payment Renewal Failed (422) theme={null}
{
    "code": "PAYMENT_RENEWAL_FAILED",
    "status": false,
    "message": "La autorización de renovación de pago falló. Por favor, verifique la información proporcionada."
}
```

```json Service Error (500) theme={null}
{
    "code": "SERVICE_ERROR",
    "status": false,
    "message": "Ocurrió un error. Por favor, intente nuevamente."
}
```

## Required Headers

**Token-Top** `string` *required*

Merchant authentication token

**Authorization** `string` *required*

Basic authentication (Basic Auth)

**X-Merchant-ID** `string` *required*

Unique identifier of the merchant invoking Card Payment services

**X-Request-ID** `string` *required*

Unique tracking identifier for the request

**Content-Type** `string` *required*

Must be "application/json"

## Request Body Parameters

**subscription\_id** `string` *required*

Identifier of the subscription for which the renewal payment is preauthorized

**reference\_id** `string` *required*

Unique transaction identifier provided by the client for this new cycle

**currency** `string` *required*

Currency code for transaction processing (e.g., "COP", "PEN", "USD")

**amount** `number` *required*

Amount to preauthorize for this renewal cycle. Must be a positive value.

**tax** `number` *required*

Processing tax associated with the transaction. If no tax will be charged, send `0`.

**linked\_transaction\_id** `string` *required*

Identifier of the original preauthorization transaction. This ID links the new transaction with the subscription history.

## Validation Rules

### Required Fields

| Field | Type | Rules | Description |
| - | - | - | - |
| `reference_id` | string | required, max:36 | Unique payment reference identifier |
| `subscription_id` | string | required, max:36 | Subscription UUID |
| `currency` | string | required, max:3 | ISO 4217 currency code |
| `amount` | numeric | required, min:0 | Payment amount (must be greater than or equal to 0) |
| `tax` | numeric | required, min:0 | Payment tax (must be greater than or equal to 0) |
| `linked_transaction_id` | string | required, max:36 | UUID of the original linked transaction |

### Allowed Values

#### currency

* `COP` - Colombian Peso

### Common Validation Error Messages

The following are common validation error messages returned by the API (in Spanish):

* `:attribute es obligatorio.` - Required field missing
* `:attribute debe ser una cadena de texto.` - Invalid data type (expected string)
* `:attribute debe ser un número.` - Invalid data type (expected numeric)
* `:attribute no puede tener más de :max caracteres.` - Maximum length exceeded
* `:attribute debe ser mayor o igual a :min.` - Minimum value not met
* `:attribute no es válido.` - Invalid value

## Response Fields

### Success Response (200 OK)

**code** `string` *required*

Response code. Value: `"AUTHORIZED"` when renewal is successful

**status** `boolean` *required*

Operation status. `true` when successful, `false` when there is an error

**message** `string` *required*

Descriptive message about the renewal result

**data** `object` *required*

**Transaction data**

**transaction\_id** `string` *required*

Unique identifier of the new renewal transaction created. This ID will be used to capture the transaction later.

**transaction\_date** `string` *required*

Transaction processing date and time in ISO 8601 format with UTC timezone (format: `Y-m-d\TH:i:s\Z`)

**linked\_transaction\_id** `string` *required*

Identifier of the original preauthorization transaction to which this renewal is linked

**transaction\_status** `string` *required*

Transaction status. Value: `"APPROVED"` when renewal is successful

**transaction\_type** `string` *required*

Transaction type. Value: `"RENEWAL_PRE_AUTH_TRANSACTION"` for renewal transactions

**reference\_id** `string` *required*

Transaction identifier provided by the client

**amount** `number` *required*

Preauthorized amount for this cycle

**currency** `string` *required*

Transaction currency code (e.g., "COP")

## HTTP Status Codes

| Status Code | Description | Response Body |
| - | - | - |
| `200 OK` | Successful renewal | `status: true`, `code: "AUTHORIZED"` |
| `400 Bad Request` | Missing required header (`X-Merchant-ID` or `X-Request-ID`) | Simple error message |
| `401 Unauthorized` | Authentication failed (invalid `Token-Top` or `Authorization`) | `code: "UNAUTHORIZED"` |
| `404 Not Found` | Subscription or transaction not found | `code: "NOT_FOUND"` |
| `422 Unprocessable Entity` | Validation error, invalid subscription/transaction state, or provider renewal failure | `code: "VALIDATION_ERROR"`, `"INVALID_STATE"` or `"PAYMENT_RENEWAL_FAILED"` |
| `500 Internal Server Error` | Internal server error | `code: "SERVICE_ERROR"` |

## Response Codes

| Code | Description |
| - | - |
| `AUTHORIZED` | Successful renewal |
| `VALIDATION_ERROR` | Validation error in sent data (missing fields, incorrect types, invalid UUID, etc.) |
| `UNAUTHORIZED` | Authentication error |
| `NOT_FOUND` | Subscription or transaction not found |
| `INVALID_STATE` | Invalid state of subscription or original transaction (inactive subscription, unapproved transaction, etc.) |
| `PAYMENT_RENEWAL_FAILED` | Renewal failed at the payment provider |
| `SERVICE_ERROR` | Internal server error |

## Transaction Types

### Pre-Authorization Renewal (RENEWAL\_PRE\_AUTH\_TRANSACTION)

* **Type**: `RENEWAL_PRE_AUTH_TRANSACTION`
* **Status**: `APPROVED` (success) or `DECLINED`/`ERROR` (failure)
* **Purpose**: Renew a previous authorization, cancelling the original and creating a new one
* **Linkage**: `linked_transaction_id` points to the original transaction
* **Next Step**: Requires an additional capture step to charge the funds

## Supported Currencies

The `currency` field must be one of the allowed values according to the `Currency` enum. Example:

* `COP`: Colombian Peso


## OpenAPI

````yaml post /api/subscription/card/authorize/renewal
openapi: 3.0.0
info:
  title: Payment Platform - Card Payment API
  version: 1.0.0
  description: API for managing subscriptions with credit and debit cards.
  contact:
    url: https://docs.tumipay.co
    name: Payment Platform Card Payment
    email: it@tumipay.co
  license:
    name: Proprietary License
    url: https://tumipay.com/license
servers:
  - url: https://tumipay-card-payments.uat.topup.com.co/production
    description: UAT server
security: []
tags:
  - name: CardPayment
    description: Operations related to subscription creation, authorization, and capture.
paths:
  /api/subscription/card/authorize/renewal:
    post:
      tags:
        - CardPayment
      summary: Renew a Pre Authorization
      description: Preauthorizes a configured amount for a subscription in a renewal cycle.
      operationId: renewalPpreAuthorizeCardPayment
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/TokenTop'
        - $ref: '#/components/parameters/BasicAuth'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reference_id
                - subscription_id
                - currency
                - amount
                - tax
                - linked_transaction_id
              properties:
                reference_id:
                  type: string
                  format: uuid
                  example: ORDER-123456
                subscription_id:
                  type: string
                  format: uuid
                  example: 550e8400-e29b-41d4-a716-446655440000
                currency:
                  type: string
                  example: COP
                amount:
                  type: number
                  minimum: 0
                  example: 1500
                tax:
                  type: number
                  minimum: 0
                  example: 0
                linked_transaction_id:
                  type: string
                  format: uuid
                  example: 7f45a9da-2f84-4103-ac54-05fe8ea693ca
      responses:
        '200':
          description: >-
            Successful renewal. A new transaction of type
            RENEWAL_PRE_AUTH_TRANSACTION is created and the original transaction
            is automatically cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenewalPreAuthorizeResponse'
              examples:
                success:
                  summary: Renewal successful
                  value:
                    code: AUTHORIZED
                    status: true
                    message: Renovación de pago autorizada exitosamente
                    data:
                      transaction_id: 770e8400-e29b-41d4-a716-446655440002
                      transaction_date: '2025-12-23T10:30:45Z'
                      linked_transaction_id: 660e8400-e29b-41d4-a716-446655440001
                      transaction_status: APPROVED
                      transaction_type: RENEWAL_PRE_AUTH_TRANSACTION
                      reference_id: reference-uuid-456
                      amount: 150
                      currency: COP
        '400':
          description: Missing required header (X-Merchant-ID or X-Request-ID).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication failed (invalid Token-Top or Authorization).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Suscripción o transacción no encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Validation error, invalid subscription/transaction state, or payment
            provider renewal failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    MerchantId:
      name: X-Merchant-ID
      in: header
      required: true
      description: >-
        Unique identifier of the Merchant invoking Card Payment services. Should
        not be used to authenticate end users.
      schema:
        type: string
    RequestId:
      name: X-Request-ID
      in: header
      required: true
      description: >-
        Tracking identifier associated with the request, used to establish a
        correlation_id between ecosystem components.
      schema:
        type: string
    TokenTop:
      name: Token-Top
      in: header
      required: true
      description: Token for authentication.
      schema:
        type: string
    BasicAuth:
      name: Authorization
      in: header
      required: true
      description: Basic authentication.
      schema:
        type: string
  schemas:
    RenewalPreAuthorizeResponse:
      type: object
      description: >-
        Renewal preauthorization response. Creates a new transaction of type
        RENEWAL_PRE_AUTH_TRANSACTION and automatically cancels the original
        transaction when the renewal is successful or rejected.
      required:
        - code
        - status
        - message
        - data
      properties:
        code:
          type: string
          description: 'Response code. Value: ''AUTHORIZED'' when renewal is successful'
          example: AUTHORIZED
        status:
          type: boolean
          description: Operation status. true when successful, false when there is an error
          example: true
        message:
          type: string
          description: Descriptive message about the renewal result
          example: Renovación de pago autorizada exitosamente
        data:
          type: object
          properties:
            transaction_id:
              type: string
              format: uuid
              description: >-
                Unique identifier of the new renewal transaction created. This
                ID will be used to capture the transaction later.
              example: 770e8400-e29b-41d4-a716-446655440002
            transaction_date:
              type: string
              format: date-time
              description: >-
                Transaction processing date and time in ISO 8601 format with UTC
                timezone (format: Y-m-d\TH:i:s\Z)
              example: '2025-12-23T10:30:45Z'
            linked_transaction_id:
              type: string
              format: uuid
              description: >-
                Identifier of the original preauthorization transaction to which
                this renewal is linked
              example: 660e8400-e29b-41d4-a716-446655440001
            transaction_status:
              type: string
              description: 'Transaction status. Value: ''APPROVED'' when renewal is successful'
              example: APPROVED
            transaction_type:
              type: string
              description: >-
                Transaction type. Value: 'RENEWAL_PRE_AUTH_TRANSACTION' for
                renewal transactions
              example: RENEWAL_PRE_AUTH_TRANSACTION
            reference_id:
              type: string
              description: Transaction identifier provided by the client
              example: reference-uuid-456
            amount:
              type: number
              description: Preauthorized amount for this cycle
              example: 150
            currency:
              type: string
              description: Transaction currency code (e.g., 'COP')
              example: COP
          required:
            - transaction_id
            - transaction_date
            - linked_transaction_id
            - transaction_status
            - transaction_type
            - reference_id
            - amount
            - currency
    ErrorResponse:
      type: object
      description: >-
        Standard structure for error responses. For 400 errors (missing
        headers), it only contains 'message'.
      oneOf:
        - type: object
          properties:
            code:
              type: string
              description: >-
                Error code. Possible values: 'VALIDATION_ERROR', 'UNAUTHORIZED',
                'NOT_FOUND', 'ACCESS_DENIED', 'SUBSCRIPTION_CREATION_FAILED',
                'SERVICE_ERROR'
              example: VALIDATION_ERROR
            status:
              type: boolean
              description: Always false for error responses
              example: false
            message:
              type: string
              description: Descriptive error message
              example: The given data was invalid.
            details:
              type: object
              additionalProperties: true
              description: Additional error details (optional)
        - type: object
          properties:
            message:
              type: string
              description: Error message for missing headers
              example: 'Missing required header: X-Merchant-ID'
          required:
            - message

````

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