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

# API de Autorización con Cuotéalo

> Inicia pagos con Cuotéalo usando el API de autorización de PayIn.

Usa este flujo para iniciar operaciones en cuotas con Cuotéalo desde el API de autorización de PayIn.

<ParamField path="POST /charges" type="endpoint" />

<Note>
  Este flujo utiliza el mismo endpoint base de autorización. Revisa los ambientes y la configuración general en el [Overview](/payin/autorizacion).
</Note>

***

## Características del flujo

<CardGroup cols={2}>
  <Card title="Tipo de flujo" icon="clock">
    Asíncrono.
  </Card>

  <Card title="Método de pago" icon="receipt">
    Permite iniciar cobros ecommerce con Cuotéalo.
  </Card>

  <Card title="Redirección" icon="arrow-up-right-from-square">
    El usuario continúa el flujo de pago fuera de tu checkout.
  </Card>

  <Card title="Validación final" icon="shield-check">
    El resultado final debe confirmarse por backend con notificación o consulta.
  </Card>
</CardGroup>

***

## Consideraciones

<Note>
  Este flujo requiere `redirect_url` para retornar al comercio cuando finalice la autorización y permite enviar `callback_url` para notificación host to host.
</Note>

<Note>
  Si trabajas con redirect, revisa también las [Consideraciones para métodos con Redirect](/payin/autorizacion-metodos-con-redirect).
</Note>

<Warning>
  No tomes como final la respuesta inicial del `POST /charges`. Confirma el resultado con [Notificaciones](/payin/notificaciones) o con [Consulta](/payin/consulta-cuotealo).
</Warning>

***

## Request

<Note>
  Antes de consumir este endpoint, solicita tu `Access Token` en [Autenticación](/autenticacion#param-post-token).
</Note>

### Headers

| Campo             | Descripción                               | Valor                   | Tipo   | Obligatorio |
| :---------------- | :---------------------------------------- | :---------------------- | :----- | :---------- |
| `Authorization`   | Token Bearer obtenido desde autenticación | `Bearer {access_token}` | String | SI          |
| `Content-Type`    | Formato del request                       | `application/json`      | String | SI          |
| `ALG-API-VERSION` | Versión del API                           | `1709847567`            | String | SI          |

```bash theme={"system"}
Authorization: Bearer {access_token}
Content-Type: application/json
ALG-API-VERSION: 1709847567
```

***

### Body

#### Objeto raíz del request

| Campo                       | Descripción                                                                                     | Ejemplo              | Tipo   | Obligatorio |
| :-------------------------- | :---------------------------------------------------------------------------------------------- | :------------------- | :----- | :---------- |
| `action`                    | Acción a ejecutar                                                                               | `authorize`          | String | SI          |
| `channel`                   | Canal de la operación                                                                           | `ecommerce`          | String | SI          |
| `merchant_code`             | Código del comercio                                                                             | `your_merchant_code` | String | SI          |
| `merchant_operation_number` | Identificador único de la operación en el comercio. **Debe ser diferente en cada transacción.** | `5974483`            | String | SI          |
| `payment_method`            | Objeto con la información del método de pago                                                    | Object               | Object | SI          |
| `payment_details`           | Objeto con el detalle del pago y datos del cliente                                              | Object               | Object | SI          |

***

#### Objeto `payment_method`

| Campo            | Descripción                                      | Ejemplo    | Tipo   | Obligatorio |
| :--------------- | :----------------------------------------------- | :--------- | :----- | :---------- |
| `method_name`    | Nombre del método de pago                        | `CUOTEALO` | String | SI          |
| `method_details` | Objeto con la información específica de Cuotéalo | Object     | Object | SI          |

***

#### Objeto `payment_method.method_details`

| Campo          | Descripción                                                            | Ejemplo                       | Tipo   | Obligatorio |
| :------------- | :--------------------------------------------------------------------- | :---------------------------- | :----- | :---------- |
| `redirect_url` | URL donde se realizará el redirect cuando finalice la autorización     | `https://pay-me.com`          | String | SI          |
| `callback_url` | URL donde se realizará la notificación host to host (server to server) | `https://pay-me.com/callback` | String | NO          |

<Note>
  `redirect_url` debe apuntar a una ruta de tu comercio preparada para recibir el retorno del usuario. Si envías `callback_url`, asegúrate de que sea accesible desde backend.
</Note>

***

#### Objeto `payment_details`

| Campo             | Descripción                                 | Ejemplo | Tipo   | Obligatorio |
| :---------------- | :------------------------------------------ | :------ | :----- | :---------- |
| `amount`          | Monto de la operación en centavos           | `15000` | String | SI          |
| `currency`        | Código de la moneda                         | `604`   | String | SI          |
| `billing`         | Datos de facturación                        | Object  | Object | SI          |
| `shipping`        | Datos de envío                              | Object  | Object | SI          |
| `customer`        | Datos del cliente                           | Object  | Object | SI          |
| `product_details` | Lista de productos asociados a la operación | `[]`    | Array  | SI          |

<Note>
  Para `billing`, `shipping` y `customer`, usa la estructura ecommerce estándar con `first_name`, `last_name`, `email`, `phone` y `location`.
</Note>

***

### Ejemplo de request

```json theme={"system"}
{
  "action": "authorize",
  "channel": "ecommerce",
  "merchant_code": "your_merchant_code",
  "merchant_operation_number": "5974483",
  "payment_method": {
    "method_name": "CUOTEALO",
    "method_details": {
      "redirect_url": "https://pay-me.com",
      "callback_url": "https://pay-me.com/callback"
    }
  },
  "payment_details": {
    "amount": "15000",
    "currency": "604",
    "billing": {
      "first_name": "Pedro",
      "last_name": "Miranda",
      "email": "pedro@pay-me.com",
      "phone": {
        "country_code": "+51",
        "subscriber": "999835685"
      },
      "location": {
        "line_1": "Av. Casimiro Ulloa 333",
        "line_2": "Miraflores",
        "city": "Lima",
        "state": "Lima",
        "country": "Peru"
      }
    },
    "shipping": {
      "first_name": "Pedro",
      "last_name": "Miranda",
      "email": "pedro@pay-me.com",
      "phone": {
        "country_code": "+51",
        "subscriber": "999835685"
      },
      "location": {
        "line_1": "Av. Casimiro Ulloa 333",
        "line_2": "Miraflores",
        "city": "Lima",
        "state": "Lima",
        "country": "Peru"
      }
    },
    "customer": {
      "first_name": "Pedro",
      "last_name": "Miranda",
      "email": "pedro@pay-me.com",
      "phone": {
        "country_code": "+51",
        "subscriber": "999835685"
      },
      "location": {
        "line_1": "Av. Casimiro Ulloa 333",
        "line_2": "Miraflores",
        "city": "Lima",
        "state": "Lima",
        "country": "Peru"
      }
    },
    "product_details": []
  }
}
```

***

## Response

<Note>
  Para recibir la respuesta final de una autorización con redirect, toma en cuenta las [Consideraciones para métodos con Redirect](/payin/autorizacion-metodos-con-redirect). La respuesta inicial normalmente deja la transacción en seguimiento.
</Note>

### Objeto `transaction`

| Campo               | Descripción                                                       | Ejemplo                                                                      | Tipo   | Obligatorio |
| :------------------ | :---------------------------------------------------------------- | :--------------------------------------------------------------------------- | :----- | :---------- |
| `transaction_id`    | Identificador único de la transacción                             | `5hk8rwa3h3cq9oyfs3a28v1ms`                                                  | String | SI          |
| `channel`           | Canal por el cual se realizó la transacción                       | `ecommerce`                                                                  | String | SI          |
| `state`             | Estado actual de la transacción                                   | `PENDIENTE`                                                                  | String | SI          |
| `state_reason`      | Observación o descripción del estado actual                       | `Url generada para continuar con el pago`                                    | String | SI          |
| `continue_url`      | URL para continuar el flujo del pago fuera del checkout           | `https://api.dev.alignet.io/payment/continue/card/81vrxn30vja1gwcfsdng4i5g5` | String | NO          |
| `amount`            | Monto de la transacción                                           | `15000`                                                                      | String | SI          |
| `currency`          | Código de la moneda de la operación                               | `604`                                                                        | String | SI          |
| `payment_method`    | Objeto con información del método de pago usado en la transacción | Object                                                                       | Object | SI          |
| `expiration_date`   | Fecha en la que expirará la transacción                           | Object                                                                       | Object | NO          |
| `additional_fields` | Datos adicionales enviados en el request                          | Object                                                                       | Object | NO          |
| `lifecycle`         | Historial de estados por los que pasó la transacción              | Array                                                                        | Array  | SI          |

<Note>
  `state` puede devolver valores como `PENDIENTE` o `INVALIDO`. `continue_url` y `expiration_date` suelen estar presentes cuando la transacción queda en estado `PENDIENTE`.
</Note>

<Warning>
  No uses `meta.status.code` como validador de autorización o denegación del pago. Ese código solo indica si el servicio procesó o respondió correctamente; el resultado del pago se valida con `transaction.state` y, como respaldo, desde backend con consulta o notificación.
</Warning>

***

### Objeto `transaction.payment_method`

| Campo            | Descripción                                                               | Ejemplo    | Tipo   | Obligatorio |
| :--------------- | :------------------------------------------------------------------------ | :--------- | :----- | :---------- |
| `method_name`    | Nombre del método de pago usado en la transacción                         | `CUOTEALO` | String | SI          |
| `method_details` | Objeto que contiene el detalle del método de pago usado en la transacción | Object     | Object | SI          |

***

### Objeto `transaction.payment_method.method_details`

| Campo          | Descripción                                                            | Ejemplo                       | Tipo   | Obligatorio |
| :------------- | :--------------------------------------------------------------------- | :---------------------------- | :----- | :---------- |
| `redirect_url` | URL donde se realizará el redirect cuando finalice la autorización     | `https://pay-me.com`          | String | SI          |
| `callback_url` | URL donde se realizará la notificación host to host (server to server) | `https://pay-me.com/callback` | String | NO          |

***

### Objeto `transaction.expiration_date`

| Campo       | Descripción                      | Ejemplo                    | Tipo    | Obligatorio |
| :---------- | :------------------------------- | :------------------------- | :------ | :---------- |
| `utc_time`  | Fecha de expiración en UTC       | `2024-03-12T22:49:36.018Z` | String  | NO          |
| `unix_time` | Fecha de expiración en unix time | `1711585037`               | Integer | NO          |

***

### Objeto `transaction.lifecycle`

| Campo   | Descripción                       | Ejemplo     | Tipo   | Obligatorio |
| :------ | :-------------------------------- | :---------- | :----- | :---------- |
| `state` | Estado registrado en el historial | `PENDIENTE` | String | SI          |
| `date`  | Fecha del cambio de estado        | Object      | Object | SI          |

<Note>
  En `lifecycle` puedes recibir estados como `REGISTRADO`, `PENDIENTE` e `INVALIDO`.
</Note>

***

### Objeto `transaction.lifecycle[].date`

| Campo       | Descripción        | Ejemplo                    | Tipo    | Obligatorio |
| :---------- | :----------------- | :------------------------- | :------ | :---------- |
| `utc_time`  | Fecha en UTC       | `2024-03-12T22:49:36.018Z` | String  | SI          |
| `unix_time` | Fecha en unix time | `1710282940`               | Integer | SI          |

***

### Ejemplo de response

```json theme={"system"}
{
  "success": "true",
  "action": "authorize",
  "merchant_code": "your_merchant_code",
  "merchant_operation_number": "2391645",
  "transaction": {
    "transaction_id": "5hk8rwa3h3cq9oyfs3a28v1ms",
    "channel": "ecommerce",
    "state": "PENDIENTE",
    "state_reason": "Url generada para continuar con el pago",
    "continue_url": "https://api.dev.alignet.io/payment/continue/card/81vrxn30vja1gwcfsdng4i5g5",
    "amount": "15000",
    "currency": "604",
    "payment_method": {
      "method_name": "CUOTEALO",
      "method_details": {
        "redirect_url": "https://pay-me.com",
        "callback_url": "https://pay-me.com/callback"
      }
    },
    "expiration_date": {
      "utc_time": "2024-03-12T22:49:36.018Z",
      "unix_time": 1711585037
    },
    "processor_response": null,
    "additional_fields": null,
    "lifecycle": [
      {
        "state": "REGISTRADO",
        "date": {
          "utc_time": "2024-03-12T22:49:36.018Z",
          "unix_time": 1710282940
        }
      },
      {
        "state": "PENDIENTE",
        "date": {
          "utc_time": "2024-03-12T22:49:36.018Z",
          "unix_time": 1710282940
        }
      }
    ]
  },
  "meta": {
    "status": {
      "code": "00",
      "message_ilgn": [
        {
          "locale": "es_PE",
          "value": "Procesado correctamente"
        }
      ]
    }
  }
}
```

***

## Buenas prácticas

* Confirma el resultado final por backend antes de actualizar la orden.
* Asegúrate de enviar un `merchant_operation_number` único por transacción.
* Implementa el manejo del retorno del usuario a `redirect_url` sin asumir que el pago terminó correctamente.
* Usa `callback_url` si tu operación necesita confirmación server to server.
* Conserva `transaction_id`, `merchant_operation_number` y `continue_url` para seguimiento, soporte y conciliación.

***

## Errores comunes

<CardGroup cols={2}>
  <Card title="Confirmación prematura" icon="triangle-exclamation">
    No marques una orden como pagada solo porque el usuario regresó a tu sitio o porque recibiste una respuesta inicial `PENDIENTE`.
  </Card>

  <Card title="Redirect incompleto" icon="ban">
    Si `redirect_url` no está correctamente implementado, el usuario puede completar el flujo de Cuotéalo sin que tu comercio procese bien el retorno.
  </Card>
</CardGroup>

***

## Siguiente paso

<Card title="Api de Consulta con Cuotéalo" icon="arrow-right" href="/payin/consulta-cuotealo">
  Consulta el estado final de una operación iniciada con Cuotéalo.
</Card>