Pagos Automáticos
/
API Pagos Automáticos

API Pagos Automáticos (v1.0)

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

Download OpenAPI description
openapi.json
openapi.yaml
Overview
Licencia

API Pagos Automáticos de Khipu

Languages
Servers
Production

https://payment-api.khipu.com/

Creación de suscripción

Request

Éste método permite crear una suscripción nueva para un cliente, que puede ser utilizada para pagos recurrentes automáticos.

Security
Api-Key
Bodyapplication/jsonRequerido
namestring<= 255 charactersrequerido

Nombre para identificar la suscripción.

Ejemplo: "Service XYZ Id 11.222.333-0"
emailstring<= 255 charactersrequerido

El correo electrónico del cliente que se suscribe al servicio.

Ejemplo: "personal.email@gmail.com"
max_amountnumber<= 255 charactersrequerido

Monto máximo que se puede cobrar mensualmente al cliente.

Ejemplo: 1000
currencystring<= 4 charactersrequerido

El código de moneda en el estándar ISO 4217.

Ejemplo: "CLP"
notify_urlstring<= 1024 charactersrequerido

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

Ejemplo: "https://my-domain.biz/subscription-notify-api"
return_urlstring<= 1024 charactersrequerido

URL a la que redirigir al cliente cuando el proceso de firma se haya completado.

Ejemplo: "https://my-domain.biz/subscription-result"
cancel_urlstring<= 1024 charactersrequerido

URL a la que redirigir al cliente si el proceso de firma no se pudo completar.

Ejemplo: "https://my-domain.biz/subscription-cancel"
service_referencestring

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.

Ejemplo: "12345678K"
image_urlstring<= 1024 characters

URL de la imagen asociada a la suscripción.

Ejemplo: "https://my-domain.biz/subscription-image.png"
descriptionstring

Descripción detallada de la suscripción PAC (Pago Automático) realizada en bancos para productos.

Ejemplo: "Suscripción PAC para el servicio XYZ."
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"
  }'

Responses

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.

Bodyapplication/json
subscription_idstring<= 255 charactersrequerido

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.

Ejemplo: "13a0f1aa-5e47-4894-aa8b-282dd19593ec"
redirect_urlstring<= 1024 charactersrequerido

La URL donde el comercio debe redirigir al usuario para que firme la suscripción con su banco personal. Utiliza el id de la suscripción como parámetro de la URL.

Ejemplo: "https://khipu.com/pac-manager/13a0f1aa-5e47-4894-aa8b-282dd19593ec"
Response
application/json
{
  "subscription_id": "13a0f1aa-5e47-4894-aa8b-282dd19593ec",
  "redirect_url": "https://khipu.com/pac-manager/13a0f1aa-5e47-4894-aa8b-282dd19593ec"
}

Estado de la Suscripción

Request

Éste método obtiene el estado actual de una suscripción de pago automático.

Security
Api-Key
Path
idstring<= 255 charactersrequerido

Identificador único de la suscripción a consultar.

curl -i -X GET \
  'https://payment-api.khipu.com/v1/automatic-payment/subscription/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Operación exitosa. Retorna un objeto JSON con la información de la suscripción asociada al id.

Bodyapplication/json
subscription_idstring<= 255 charactersrequerido

Identificador único de la suscripción.

Ejemplo: "13a0f1aa-5e47-4894-aa8b-282dd19593ec"
statusstringrequerido

El estado actual de la suscripción. Un intento de cobro solo se puede realizar si el estado es ENABLED.

Enum"DISABLED""SIGNED""ENABLED"
Ejemplo: "SIGNED"
developerbooleanrequerido

Indica si la suscripción fue creada usando el entorno de pruebas. Un valor false significa que es una suscripción de producción.

Ejemplo: false
customer_bank_codestring<= 255 charactersrequerido

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.

Ejemplo: "8"
service_referencestring<= 255 charactersrequerido

El alias utilizado para identificar la suscripción.

Ejemplo: "Nombre de mi comercio"
Response
application/json
{
  "subscription_id": "13a0f1aa-5e47-4894-aa8b-282dd19593ec",
  "status": "SIGNED",
  "developer": false,
  "customer_bank_code": "8",
  "service_reference": "Nombre de mi comercio"
}

Creación de intención de cobro

Request

Éste método crea una nueva solicitud de cargo para la suscripción especificada.

Security
Api-Key
Bodyapplication/jsonRequerido
subscription_idstring<= 255 charactersrequerido

El ID de la suscripción que se cobrará.

Ejemplo: "13a0f1aa-5e47-4894-aa8b-282dd19593ec"
amountnumber(float)>= 1requerido

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.

Ejemplo: 10000
subjectstring<= 255 charactersrequerido

Asunto para identificar el cobro.

Ejemplo: "Cargo por servicio XYZ Id 11.222.333-0"
bodystring<= 5120 charactersrequerido

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.

Ejemplo: "Servicio XYZ - Noviembre 2022 - Monto: $10.000"
error_response_urlstring<= 1024 charactersrequerido

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
  }
Ejemplo: "https://my-domain.biz/charge-error-api"
customstring<= 1073741824 charactersrequerido

Éste campo puede ser utilizado para enviar información personalizada sobre el cobro. Puede ser en formato texto o un documento codificado en base64.

Ejemplo: "Contenido personalizado del cobro en formato texto o base64."
transaction_idstring<= 255 charactersrequerido

El identificador único del comercio para esta operación. Por ejemplo, el número de factura.

Ejemplo: "INVOICE-23ffcfbe1e4a4d1c9dc631fe70bddaa0"
notify_urlstring<= 1024 charactersrequerido

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.

Ejemplo: "https://my-domain.biz/charge-notify-api"
notify_api_versionstring<= 255 characters

Version of the API used for the notification. This is useful to ensure compatibility with future changes in the API.

Ejemplo: "1.3"
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"
  }'

Responses

Operación exitosa. Retorna un objeto JSON con el id del intento de cargo que puede ser usado para rastrear la solicitud de un cargo.

Bodyapplication/json
payment_idstring<= 12 charactersrequerido

Identificador único del cobro. Representa el id de pago automático que se usará para rastrear la solicitud de cobro a la cuenta del cliente.

Ejemplo: "v67prof2ugg3"
Response
application/json
{
  "payment_id": "v67prof2ugg3"
}