Licencia
La API de Pago Automático (versión 1.0) de Khipu permite a los comercios establecer suscripciones para pagos recurrentes mediante débito bancario (PAC). A través del endpoint POST /v1/automatic-payment/subscription, el comerciante envía información como nombre de la suscripción, correo del cliente, monto máximo, moneda, y URLs para notificación, retorno o cancelación. Al procesarse exitosamente, la API genera un subscription_id único y una redirect_url donde el usuario firma el mandato de débito con su banco. Luego, el comerciante puede consultar y gestionar el estado del PAC mediante otros endpoints. La autenticación se realiza utilizando la cabecera x-api-key
https://payment-api.khipu.com/
Nombre para identificar la suscripción.
El correo electrónico del cliente que se suscribe al servicio.
Monto máximo que se puede cobrar mensualmente al cliente.
La URL que se llamará cuando el cliente complete el proceso de firma con el banco. Se enviará un mensaje JSON a través de POST con la información de la suscripción con la siguiente estructura (status puede ser "enabled" o "disabled"): ```json { "subscription_id": string, "status": "enabled" }
URL a la que redirigir al cliente cuando el proceso de firma se haya completado.
URL a la que redirigir al cliente si el proceso de firma no se pudo completar.
Valor a asociar con la suscripción. Puede ser útil cuando no quieres que tu cliente sea identificado con un string único aleatorio en el formulario de suscripción de mandato del banco.
URL de la imagen asociada a la suscripción.
https://payment-api.khipu.com/v1/automatic-payment/subscription
curl -i -X POST \
https://payment-api.khipu.com/v1/automatic-payment/subscription \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-d '{
"name": "Service XYZ Id 11.222.333-0",
"email": "personal.email@gmail.com",
"max_amount": 1000,
"currency": "CLP",
"notify_url": "https://my-domain.biz/subscription-notify-api",
"return_url": "https://my-domain.biz/subscription-result",
"cancel_url": "https://my-domain.biz/subscription-cancel"
}'Operación exitosa. Retorna un objeto JSON con el id de la suscripción que puede ser utilizado para solicitar al cliente que firme el mandato de pago autómatico.
Identificador único de la suscripción, que se asociará al servicio adquirido por el cliente. Posteriormente, este valor puede ser usado para consultar el estado de la suscripción.
{ "subscription_id": "13a0f1aa-5e47-4894-aa8b-282dd19593ec", "redirect_url": "https://khipu.com/pac-manager/13a0f1aa-5e47-4894-aa8b-282dd19593ec" }
https://payment-api.khipu.com/v1/automatic-payment/subscription/{id}
curl -i -X GET \
'https://payment-api.khipu.com/v1/automatic-payment/subscription/{id}' \
-H 'x-api-key: YOUR_API_KEY_HERE'Operación exitosa. Retorna un objeto JSON con la información de la suscripción asociada al id.
Identificador único de la suscripción.
El estado actual de la suscripción. Un intento de cobro solo se puede realizar si el estado es ENABLED.
Indica si la suscripción fue creada usando el entorno de pruebas. Un valor false significa que es una suscripción de producción.
El banco utilizado por el cliente para firmar la suscripción. Los valores posibles son los utilizados en la API de Pagos de Khipu, o no-bank si la suscripción no ha sido firmada.
{ "subscription_id": "13a0f1aa-5e47-4894-aa8b-282dd19593ec", "status": "SIGNED", "developer": false, "customer_bank_code": "8", "service_reference": "Nombre de mi comercio" }
El ID de la suscripción que se cobrará.
Monto que se cobrará. No use separador de miles, y un máximo de 4 decimales. Se asumirá la moneda en que el comercio registró su cuenta en Khipu.
Asunto para identificar el cobro.
Descripción del cobro. Puede incluir información adicional sobre el cobro, como el servicio o producto asociado, fecha, etc. Se recomienda que sea lo más descriptivo posible.
URL que será llamada si ocurre un error en el proceso de cobro. Se enviará un JSON por POST con la siguiente estructura:
{
"subscription_id": string,
"transaction_id": string,
"error_message": string
}Éste campo puede ser utilizado para enviar información personalizada sobre el cobro. Puede ser en formato texto o un documento codificado en base64.
El identificador único del comercio para esta operación. Por ejemplo, el número de factura.
URL que será llamada una vez que el proceso de cobro finalice y el pago sea conciliado. Se enviará un POST con los parámetros que permiten obtener los detalles del pago, utilizando el mismo flujo de un pago normal. Consulte la documentación para más detalles.
https://payment-api.khipu.com/v1/automatic-payment/charge-intent
curl -i -X POST \
https://payment-api.khipu.com/v1/automatic-payment/charge-intent \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-d '{
"subscription_id": "13a0f1aa-5e47-4894-aa8b-282dd19593ec",
"amount": 10000,
"subject": "Cargo por servicio XYZ Id 11.222.333-0",
"body": "Servicio XYZ - Noviembre 2022 - Monto: $10.000",
"error_response_url": "https://my-domain.biz/charge-error-api",
"custom": "Contenido personalizado del cobro en formato texto o base64.",
"transaction_id": "INVOICE-23ffcfbe1e4a4d1c9dc631fe70bddaa0",
"notify_url": "https://my-domain.biz/charge-notify-api"
}'{ "payment_id": "v67prof2ugg3" }