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.

POST /charges · endpoint

Este flujo utiliza el mismo endpoint base de autorización. Revisa los ambientes y la configuración general en el Overview.

---

Características del flujo

Tipo de flujo

Asíncrono.

Método de pago

Permite iniciar cobros ecommerce con Cuotéalo.

Redirección

El usuario continúa el flujo de pago fuera de tu checkout.

Validación final

El resultado final debe confirmarse por backend con notificación o consulta.

---

Consideraciones

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.

Si trabajas con redirect, revisa también las Consideraciones para métodos con Redirect.

No tomes como final la respuesta inicial del POST /charges. Confirma el resultado con Notificaciones o con Consulta.

---

Request

Antes de consumir este endpoint, solicita tu Access Token en Autenticación.

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

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

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.

---

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

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

---

Ejemplo de request

{
  "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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

Para recibir la respuesta final de una autorización con redirect, toma en cuenta las Consideraciones para métodos con Redirect. La respuesta inicial normalmente deja la transacción en seguimiento.

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

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

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.

---

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

En lifecycle puedes recibir estados como REGISTRADO, PENDIENTE e INVALIDO.

---

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

{
  "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

Confirmación prematura

No marques una orden como pagada solo porque el usuario regresó a tu sitio o porque recibiste una respuesta inicial PENDIENTE.

Redirect incompleto

Si redirect_url no está correctamente implementado, el usuario puede completar el flujo de Cuotéalo sin que tu comercio procese bien el retorno.

---

Siguiente paso

Api de Consulta con Cuotéalo

Consulta el estado final de una operación iniciada con Cuotéalo.