Ésta no es la más reciente versión de la API. Quizás quieres ver la documentación de la versión actual
Introducción
La API de khipu para crear y recibir pagos permite a cobradores (individuos u organizaciones) que tengan una cuenta de cobro activada en khipu generar cobros para destinatarios:
- previamente definidos: útil para cobrar deudas que ya existen (arriendos, gastos comunes, boletas, facturas, deudas personales, etc)
- por definir: útil para vender productos o servicios en un sitio web o generar botones de donación
El proceso de creación, pago y validación es el siguiente:
- El cobrador genera un cobro en un botón de pago en un formulario web, una URL para un pago o agrega cobros en el portal de khipu.
- El pagador pincha el botón de pago en el sitio web, o un enlace de pago en un correo electrónico u otro medio y paga utilizando khipu.
- El pagador es redireccionado a la página de retorno definida por el cobrador donde se debe explicar que el pago está en verificación (o a la página de fracaso en el caso que no se haya podido hacer el pago).
- Unos momentos después khipu verifica la transacción y notifica al pagador por correo electrónico. Además, se notifica al comercio ya sea por correo electrónico y/o por la invocación de un web service.
- El cobrador valida la notificación de pago y entrega el bien transado al pagador (o descarta la notificación si es inválida).
¡Importante! En el tercer paso se redireccióna al pagador a una página de éxito, lo que quiere decir que la transferencia está en proceso de verificación, pero esto no quiere decir que se haya completado correctamente aún. Es fundamental completar la verificación hasta el paso 5.
Tabla de contenidos
- Preparando el ambiente de desarrollo
- Creando un cobro
- Recibiendo y validando la notificación de un pago
- Administrar pagos
- Enviar a conciliar un pago con transferencia normal y obtener datos para transferencia
- Marcar un cobro como expirado
- Marcar un pago como pagado
- Marcar un pago como rechazado
- Reversar un pago
- Consultar el estado de un pago
- Consultar la información de un pago
- Obtener un código de pago
- Liberar un pago retenido
- Recibiendo y validando notificación de rendición
Preparando el ambiente de desarrollo
Multiples cuentas de cobro
En khipu, cada usuario identificado por un correo electrónico puede crear varias cuentas de cobro, por ejemplo para gestionar los cobros de más de una empresa, o gestionar los cobros personales y los de negocio en cuentas separadas.
Cada cuenta de cobro se asocia a una cuenta corriente o cuenta vista bancaria donde recibirá sus pagos, tiene sus propios datos de facturación con los que se generará la boleta de la comisión de khipu y está sujeta a un Contrato del cobrador independiente.
Cuando una persona crea una cuenta de usuario en khipu se le crea automáticamente una cuenta de cobro. La primera vez que intente cobrar (por e-mail o por enlace) el sistema lo hace pasar por una secuencia de pasos que culmina con la firma del contrato del pagador.
Para crear una nueva cuenta de cobro primero debes ingresar a khipu, y en el menú de la izquierda debes seleccionar "Opciones de la cuenta". Luego en la parte superior aparecera la selección de cuentas. La ultima de las opciones es "Administrar" donde podrás crear nuevas cuentas de cobro, cambiarte a la cuenta de cobro que se deseas utilizar o archivar alguna de las que ya tienes.
Activar modo desarrollador
Para evitar sobrecargar la interfaz de khipu para los usuarios no desarrolladores, algunas de las opciones e información necesaria para los desarrolladores están ocultas y para mostrarlas es necesario ir al Perfil de usuario (en el menú superior) y buscar la sección Modo desarrollador al final de la página, en ésta pinchar "activar".
Llave del cobrador
Para impedir que otra persona utilice la API khipu a nombre de tu sitio web, khipu utiliza un esquema de seguridad con una llave secreta. Para obtener las credenciales de la cuenta cobrador activa debes ir a Opciones de la cuenta en el menu lateral izquierdo y buscar la sección Para integrar khipu a tu sitio web. En esta sección puedes obtener tu Id de cobrador y tu Llave de cobrador. El Id de cobrador es un número único para tu cobrador. La llave de cobrador es una cadena de caracteres única parecido a este: a40ac9591200b23c927a8d1c795af82d618cf78e. Cada cuenta de cobro tiene una llave y esta no se repite. Esta llave es de uso exclusivo para esa cuenta y no debe ser compartida con nadie.
Importante: si alguien robara tu llave de cobrador siempre tienes la opción de generar una nueva llave. Sin embargo, debes modificar todas las partes en que hayas utilizado la llave antigua pues si no, dejarán de funcionar.
Cuentas de cobro en modo desarrollador
En toda la API de khipu se utiliza el concepto de un cobrador o cuenta de cobro. Un cobrador es una entidad asociada a uno o más usuarios khipu que tiene una cuenta corriente o cuenta vista bancaria donde khipu abona sus pagos. Esta cuenta tiene además los datos de facturación que khipu usa para generar una boleta por las comisiones cobradas.
Para simplificar el proceso de desarrollo y pruebas de una aplicación o sistema que se interconecte con khipu, hemos creado las cuentas de cobro en modo desarrollador, estas generan cobros que sólo se pagan con bancos de pruebas que no mueven dinero realmente pero cumplen con todas las etapas necesarias para un pago real.
Para crear una cuenta de cobro en modo desarrollador, se debes seguir los siguientes pasos:
- Activar el modo desarrollador en el usuario conectado: pincha en tu ávatar arriba a la derecha y selecciona "Perfil del usuario", al final de esa página picha "activar" en el "Modo desarrollador".
- Crear una cuenta de cobro en modo desarrollador: ve a las "Opciones de la cuenta" en el menú de la izquierda, en el listado de cuentas de cobro selecciona "Administrar". En la página siguente usa el botón naranja que dice "Crear cuenta en modo desarrollador" y sigue las instrucciones para la creación del cobrador ficticio.
Luego de crear el cobrador de desarrollo, podrás usar el id de cobrador y su llave única para hacer las pruebas en tu sitio. Los cobradores de desarrollo también tienen una llave única que permite identificarlos.
Importante: para hacer pagos en el banco de prueba "DemoBank" puedes usar un RUT válido y la clave "1234". Cuando llegues a la tarjeta matricial debes introducir las coordenadas "11", "22"y "33".
Importante: recuerda volver a utilizar una cuenta de cobro normal antes de salir al aire con tus clientes. Esto quiere decir utilizar los parámetros Id de cobrador y llave de cobrador correspondientes a alguna de tus cuentas de cobrador regulares.
Como usar la API
Las llamadas a la API de khipu se ejecutan mediante una llamada POST a una URL en particular, existiendo una URL para cada operación que deses hacer. Cada llamada puede recibir uno o más parámetros.
Caso de éxito
En el caso de una llamada termine de manera correcta khipu entregará el código de HTTP STATUS con valor de 200. Los valores que entrega una llamada te serán devueltos en el cuerpo de la respuesta usando el formato JSON para los datos. En el caso de que una llamada a la API no entrege datos, igualmente se entregará un objeto JSON en la respuesta pero será un objeto vacio de la forma {}.
Caso de error
Cuando una llamada a la API encuentra algún error khipu entregará el código de HTTP STATUS con valor de 400 que indica que existen errores en los parámetros. El cuerpo de la respuesta contiene un objeto de formato JSON que contiene un error con los siguiente valores:
- type: Es el tipo de error. Por ahora solo puede contener invalid-request que significa que alguno de los parametros contiene un valor inválido.
- message: La explicación del error.
Cálculo del parámetro HASH
En la mayoría de las llamadas a la API debes incluir un parámetro extra llamado HASH. Este parámetro se incluye para impedir que otras personas hagan una llamada a la API impersonando tu comercio.
El cálculo del hash se hace de la siguiente manera creando un string usando el nombre y el valor de todos los parametros que espera la llamada y concatenarlos como los parámetros de una URL. Luego debes usar HMAC-256 con ese string y tu llave de cobrador.
khipu recibe los parámteros y genera el mismo string. Si el valor del hash calculado es distinto al que llega el el parámetro hash encontes la llamada no se ejecuta.
Ejemplo
Supongamos que los parámetros que recibe una llamada a la API son "subject", "body" y "code" (sin incluir al parámetro HASH) y que subject tiene como valor "Este es un ejemplo" y que body tiene como valor "Este es el cuerpo del ejemplo". El parámetro code es opcional y no lo enviaremos.
Suponiendo que estamos trabajando con PHP y que nuestra llave de cobrador es a40ac9591200b23c927a8d1c795af82d618cf78e debemos ejecutar el siguiente código
$concatenated = "subject=Este es un ejemplo&body=Este es el cuerpo del ejemplo&code="; $secret = "a40ac9591200b23c927a8d1c795af82d618cf78e"; $hash = hash_hmac('sha256', $concatenated , $secret);
El valor de hash será 9f2c5c659b7f7897542afea377b1e90d8e7ab9dc9b3ccdf2b2c215a1d25d0ab2 y es el que debemos enviar junto a los demás parámetros de la llamada.
Importante: Debes tener en cuenta dos cosas importantes:
- El orden en que concatenas los parámetros depende de cada llamada a la API y es siempre el mismo. Cada llamada especifica el orden correcto.
- Aun si no envías un parámetro opcional deberás incluirlo en el cálculo del hash, como hicimos con code en el ejemplo de más arriba.
Consultar el estado de un cobrador
https://khipu.com/api/1.3/receiverStatus
Esta opción permite saber el estado y algunas capacidades de tu cuenta de cobro. Para esto debes hacer una petición POST a la url https://khipu.com/api/1.3/receiverStatus. El resultado es un JSON muy parecido al siguiente:
{ "ready_to_collect": true, "type": "production" }
Los campos de este JSON son los siguientes
- ready_to_collect indica si tu cuenta de cobro se encuentra lista para recibir pagos. Puede ser true o false
- type es el tipo de cuenta de cobro. Puede ser production o development
Parámetros
Nombre | Descripción |
---|---|
receiver_id | tu id de cobrador. |
hash | String de verficiación |
El string para el hash solo debe incluir el parámetro receiver_id
. Para el cálculo debes referirte a la documentación de cálculo del hash.
Ejemplo en PHP
Él siguiente código en php crea un formulario y su hash asociado.
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $concatenated = "receiver_id=$receiver_id"; $hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/receiverStatus'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id, 'hash' => $hash); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Obtener listado de bancos
https://khipu.com/api/1.3/receiverBanks
Con esta llamada puedes obtener el listado de bancos disponibles para poder hacer un pago a una determinaada cuenta de cobro. Puedes presentar esta lista en tu sitio web para que tus clientes elijan su banco antes de llegar a khipu.
Cuando estés utilizando una cuenta de cobro, el listado sólo tendrá al banco de pruebas DemoBank que realiza transferencias sin dinero real.
Parámetros
Nombre | Descripción |
---|---|
receiver_id | tu id de cobrador. |
hash | String de verficiación |
El string para el hash solo debe incluir el parámetro receiver_id
. Para el cálculo debes referirte a la documentación de cálculo del hash.
Resultado
Si la llamada es correcta se retornará un HTTP STATUS 200 y en el cuerpo de la respuesta vendrá un objecto JSON con el listado de bancos parecido al siguiente:
{ "banks":[ { "id":"BdfFD", "name":"Banco BBVA", "message":"", "min-amount":200 }, { "id":"Evdfk", "name":"Banco BCI", "message":"Recuerda esperar que cambie tu Digipass entre cada uso.", "min-amount":200 }, "id":"dfFbF", "name":"Banco de Chile (Edwards, Citi)", "message":"", "min-amount":200 }, { "id":"SDdGj", "name":"Banco Estado", "message":"Es posible que Banco Estado realice cargos adicionales al utilizar cuenta RUT.", "min-amount":200 } ] }
En cada banco la propiedad id es el identificador único del banco y es el que debemos mandar en las distintas llamadas a la API. name es el nombre del banco. message es un mensaje relevante para los usuarios que deseen usar ese banco. min-amount indica la cantidad mínima que se puede transferir usando ese banco.
Ejemplo en PHP
Él siguiente código en php hace la petición POST con el hash correcto.
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $khipu_url = 'https://khipu.com/api/1.3/receiverBanks'; $concatenated = "receiver_id=$receiver_id"; $hash = hash_hmac('sha256', $concatenated , $secret); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $khipu_url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array( 'receiver_id' => $receiver_id, 'hash' => $hash ); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Creando un cobro
https://khipu.com/api/1.3/createPaymentPage
Botón de pago en un formulario web
Con esta opción puedes crear formularios web que permitirán a tus clientes pagar utilizando khipu. En los formularios puedes enviar toda la información necesaria para hacer el pago. Puedes incluir también la dirección en tu sitio a donde tus clientes deben volver automáticamente después de pagar.
Parámetros
Nombre | Descripción | |
---|---|---|
receiver_id | tu id de cobrador. | |
subject | el asunto del cobro. Con un máximo de 255 caracteres. | |
body | la descripción del cobro. | opcional |
amount | el monto del cobro. | |
notify_url | la dirección de tu web service que utilizará khipu para notificarte de un pago realizado. Ver Notificaciones por web service | opcional |
return_url | la dirección URL a donde enviar al cliente cuando el pago está siendo verificado. | opcional |
cancel_url | la dirección URL a donde enviar al cliente si se arrepiente de hacer la transacción. | opcional |
transaction_id | en esta variable puedes enviar un identificador propio de tu transacción, como un número de factura. | opcional |
expires_date | fecha de expiración del cobro. Pasada esta fecha el cobro es inválido. Formato Unix timestamp. Debe corresponder a una fecha en el futuro. | opcional |
payer_email | es el correo del pagador. Si lo envias, su correo aparecerá pre-configurado en la página de pago | opcional |
bank_id | el código del banco. Puedes obtener los códigos usando la llamada receiverBanks | opcional |
picture_url | una dirección URL de una foto de tu producto o servicio para mostrar en la página del cobro. | opcional |
custom | en esta variable puedes enviar información personalizada de la transacción, como por ejemplo, instrucciones de preparación o dirección de envio. | opcional |
hash | String de verficiación |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, subject
, body
, amount
, payer_email
, bank_id
, expires_date
, transaction_id
, custom
, notify_url
, return_url
, cancel_url
, picture_url
.
Ejemplo en PHP
Él siguiente código en php crea un formulario y su hash asociado.
<?php // Llenamos los parametros $receiver_id = '<id de cobrador>'; $subject = 'Impresora Laser'; $body = 'Una impresora laser con multiples bandejas de entrada'; $amount = '100'; $notify_url = 'http://misitio.com/notificacion'; $return_url = 'http://misitio.com/exito'; $cancel_url = ''; $transaction_id = 'T-1000'; $expires_date = time() + 30*24*60*60; //treinta dias a partir de ahora $payer_email = 'mi.cliente@misitio.com'; $bank_id=''; $picture_url = ''; $secret = 'e40ac9591200b2ec9277cd1c795af82d618ff78e'; $custom = 'el modelo en color rojo'; $khipu_url = 'https://khipu.com/api/1.3/createPaymentPage'; // creamos el hash $concatenated = "receiver_id=$receiver_id&subject=$subject&body=$body&amount=$amount&payer_email=$payer_email&bank_id=$bank_id&expires_date=$expires_date&transaction_id=$transaction_id&custom=$custom¬ify_url=$notify_url&return_url=$return_url&cancel_url=$cancel_url&picture_url=$picture_url"; $hash = hash_hmac('sha256', $concatenated , $secret); ?> <form action="<?php echo $khipu_url ?>" method="post"> <input type="hidden" name="receiver_id" value="<?php echo $receiver_id ?>"> <input type="hidden" name="subject" value="<?php echo $subject ?>"/> <input type="hidden" name="body" value="<?php echo $body ?>"> <input type="hidden" name="amount" value="<?php echo $amount ?>"> <input type="hidden" name="notify_url" value="<?php echo $notify_url ?>"/> <input type="hidden" name="return_url" value="<?php echo $return_url ?>"/> <input type="hidden" name="cancel_url" value="<?php echo $cancel_url ?>"/> <input type="hidden" name="custom" value="<?php echo $custom ?>"> <input type="hidden" name="transaction_id" value="<?php echo $transaction_id ?>"> <input type="hidden" name="payer_email" value="<?php echo $payer_email ?>"> <input type="hidden" name="expires_date" value="<?php echo $expires_date ?>"> <input type="hidden" name="bank_id" value="<?php echo $bank_id ?>"> <input type="hidden" name="picture_url" value="<?php echo $picture_url ?>"> <input type="hidden" name="hash" value="<?php echo $hash ?>"> <input type="image" name="submit" src="https://s3.amazonaws.com/static.khipu.com/buttons/200x50.png"> </form>
Importante: tenemos más ejemplos de botones de pago preparados para ti.
Crear URL para un pago
https://khipu.com/api/1.3/createPaymentURL
Con esta opción puedes crear un pago desde tu servidor y obtener la URL para enviar a pagar a tus pagadores (tanto en escritorios como aplicaciones móviles).
Parámetros:
Nombre | Descripción | |
---|---|---|
receiver_id | tu id de cobrador. | |
subject | el asunto del cobro. Con un máximo de 255 caracteres. | |
body | la descripción del cobro. | opcional |
amount | el monto del cobro. | |
notify_url | la dirección de tu web service que utilizará khipu para notificarte de un pago realizado. Ver Notificaciones por web service | opcional |
return_url | la dirección URL a donde enviar al cliente cuando el pago está siendo verificado | opcional |
cancel_url | la dirección URL a donde enviar al cliente si se arrepiente de hacer la transacción | opcional |
transaction_id | en esta variable puedes enviar un identificador propio de tu transacción, como un número de factura. | opcional |
expires_date | fecha de expiración del cobro. Pasada esta fecha el cobro es inválido. Formato Unix timestamp. Debe corresponder a una fecha en el futuro. | opcional |
payer_email | es el correo del pagador. Si lo envias, su correo aparecerá pre-configurado en la página de pago | opcional |
bank_id | el código del banco. Puedes obtener los códigos usando la llamada receiverBanks | opcional |
picture_url | una dirección URL de una foto de tu producto o servicio para mostrar en la página del cobro | opcional |
custom | en esta variable puedes enviar información personalizada de la transacción, como por ejemplo, instrucciones de preparación o dirección de envio. | opcional |
hash | String de verificación. |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, subject
, body
, amount
, payer_email
, bank_id
, expires_date
, transaction_id
, custom
, notify_url
, return_url
, cancel_url
, picture_url
.
Ejemplo en PHP
Él siguiente código en php hace la petición POST con el hash correcto.
<?php // Llenamos los parametros $receiver_id = '<id de cobrador>'; $subject = 'Impresora Laser'; $body = 'Una impresora laser con multiples bandejas de entrada'; $amount = '100'; $notify_url = 'http://misitio.com/notificacion'; $return_url = 'http://misitio.com/exito'; $cancel_url = ''; $transaction_id = 'T-1000'; $payer_email = 'mi.cliente@misitio.com'; $bank_id = ''; $expires_date = time() + 30*24*60*60; //treinta dias a partir de ahora $picture_url = ''; $secret = 'e40ac9591200b2ec9277cd1c795af82d618ff78e'; $custom = 'el modelo en color rojo'; $khipu_url = 'https://khipu.com/api/1.3/createPaymentURL'; $concatenated = "receiver_id=$receiver_id"; $concatenated .= "&subject=$subject&body=$body&amount=$amount"; $concatenated .= "&payer_email=$payer_email&bank_id=$bank_id"; $concatenated .= "&expires_date=$expires_date&transaction_id=$transaction_id"; $concatenated .= "&custom=$custom¬ify_url=$notify_url"; $concatenated .= "&return_url=$return_url&cancel_url=$cancel_url"; $concatenated .= "&picture_url=$picture_url"; $hash = hash_hmac('sha256', $concatenated , $secret); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $khipu_url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array( 'receiver_id' => $receiver_id, 'subject' => $subject, 'body' => $body, 'amount' => $amount, 'notify_url' => $notify_url, 'return_url' => $return_url, 'cancel_url' => $cancel_url, 'transaction_id' => $transaction_id, 'payer_email' => $payer_email, 'expires_date' => $expires_date, 'bank_id' => $bank_id, 'picture_url' => $picture_url, 'custom' => $custom, 'hash' => $hash ); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Resultado
Si la petición está correcta, khipu retornará un HTTP STATUS con valor 200 y en el cuerpo será un objeto JSON con la información del cobro. Ejemplo:
{ "id":"5wb665tyvm1p", "bill-id":"SSRwa", "url":"https://khipu.com/payment/show/5wb665tyvm1p", "manual-url":"https://khipu.com/payment/manual/5wb665tyvm1p", "mobile-url":"khipu:///pos/5wb665tyvm1p", "ready-for-terminal":false }
El valor id es el código único de operación. Puedes usar url para enviar al pagador a hacer el pago en un navegador web o mobile-url si el pagador se encuentra en un dispositivo iOS o Android que tiene el Terminal de pagos khipu instalado.
Agregar cobros en portal de khipu
https://khipu.com/api/1.3/createEmail
Con esta opción podrás crear un cobro con hasta 50 destinatarios distintos (cada uno con su monto a pagar) y recibir los enlaces para que cada uno de ellos pague o dejar que khipu envíe los correos de cobro.
Parámetros
Nombre | Descripción | |
---|---|---|
receiver_id | tu id de cobrador. | |
subject | el asunto del cobro. Con un máximo de 255 caracteres. | |
body | la descripción del cobro | opcional |
transaction_id | en esta variable puedes enviar un identificador propio de tu transacción, como un número de factura. | opcional |
notify_url | la dirección de tu web service que utilizará khipu para notificarte de un pago realizado Ver Notificaciones por webservice | opcional |
return_url | la dirección URL a donde enviar al cliente cuando el pago está siendo verificado | opcional |
cancel_url | la dirección URL a donde enviar al cliente si se arrepiente de hacer la transacción | opcional |
pay_directly | si es "true" se enviará en el correo de cobro las instrucciones para pagar con trasferencia de fondos entre cuentas corrientes por si el cliente prefiere pagar así y no usar khipu. | |
send_emails | si es "true" khipu enviará los correos de cobro. Si deseas enviar los correos usando tu propio sistema (o noenviarlos), envía "false" | |
expires_date | fecha de expiración del cobro. Pasada esta fecha el cobro es inválido. Formato Unix timestamp. Debe corresponder a una fecha en el futuro. | opcional |
destinataries | los destinatarios del cobro se deben enviar como una lista de mapas en formato JSON donde cada entrada del mapa debe tener "name", "email" y "amount". | |
picture_url | una dirección URL de una foto de tu producto o servicio para mostrar en la página del cobro | opcional |
custom | en esta variable puedes enviarinformación personalizada de la transacción, como por ejemplo, instrucciones de preparacion o dirección de envio. | opcional |
hash | String de verificación. |
El parámetro de destinatarios tiene la siguiente estructura:
[ { "name":"Juan Rojo", "email":"juan.rojo@ejemplo.com", "amount":"1000" }, { "name":"Pedro Piedra", "email":"pedro.piedra@ejemplo.com", "amount":"2000" }, { "name":"Ana Soto", "email":"ana.soto@ejemplo.com", "amount":"3000" } ]
Resultado
Si la petición está correcta, khipu retornará un HTTP STATUS con valor 200 y en el cuerpo será un objeto JSON con los cobros a los destinatarios pedidos. Ejemplo:
{ "id": "HWkZc", "payments": [ { "id": "cghs6n7mtklx", "destinataries":[ { "name": "Juan Rojo", "email": "juan.rojo@ejemplo.com" } ], "url": "https://khipu.com/payment/show/cghs6n7mtklx" }, { "id": "ueqahp3e4xq3", "destinataries":[ { "name": "Pedro Piedra", "email": "pedro.piedra@ejemplo.com" } ], "url": "https://khipu.com/payment/show/ueqahp3e4xq3" }, { "id": "9823ojq8ahs", "destinataries":[ { "name": "Ana Soto", "email": "ana.soto@ejemplo.com" } ], "url": "https://khipu.com/payment/show/9823ojq8ahs" } ] }
Es importante entender los campos de este JSON
- id: Este es el id de cobro. Este id es necesario para operaciones como marcar un cobro como expirado.
- payments: Este es listado de los pagos generados para este cobro. Cada pago tiene su código único de operación, el email al que está asociado y la URL del pago..
El código único de operación es importante para operaciones como marcar un pago como expirado
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, subject
, body
, destinataries
, pay_directly
, send_emails
, expires_date
, transaction_id
, custom
, notify_url
, return_url
, cancel_url
, picture_url
.
Ejemplo en PHP
El siguiente código en php crea un formulario y su hash asociado.
<?php // Llenamos los parametros $receiver_id = '<id de cobrador>'; $subject = 'Impresora Laser'; $body = 'Una impresora laser con multiples bandejas de entrada'; $transaction_id = 'T-1004'; $pay_directly = 'true'; $send_emails = 'true'; $expires_date = time() + 30*24*60*60; //treinta dias a partir de ahora $destinataries = '[{"name":"Juan Rojo", "email": "juan.rojo@ejemplo.com", "amount": "1000"},{"name": "Pedro Piedra", "email": "pedro.piedra@ejemplo.com", "amount": "2000"},{"name": "Ana Soto", "email": "ana.soto@ejemplo.com", "amount": "3000"}]'; $picture_url = ''; $notify_url = ''; $return_url = ''; $cancel_url = ''; $custom = ''; $secret = 'f6bbee2441874f778df2267234dfdf3a4b3265eac'; $khipu_url = 'https://khipu.com/api/1.3/createEmail'; // creamos el hash $concatenated = "receiver_id=$receiver_id&subject=$subject"; $concatenated .= "&body=$body&destinataries=$destinataries"; $concatenated .= "&pay_directly=$pay_directly&send_emails=$send_emails"; $concatenated .= "&expires_date=$expires_date&transaction_id=$transaction_id"; $concatenated .= "&custom=$custom¬ify_url=$notify_url"; $concatenated .= "&return_url=$return_url&cancel_url=$cancel_url"; $concatenated .= "&picture_url=$picture_url" $hash = hash_hmac('sha256', $concatenated , $secret); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $khipu_url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array( 'receiver_id' => $receiver_id, 'subject' => $subject, 'body' => $body, 'transaction_id' => $transaction_id, 'pay_directly' => $pay_directly, 'send_emails' => $send_emails, 'expires_date' => $expires_date, 'destinataries' => $destinataries, 'picture_url' => $picture_url, 'notify_url' => $notify_url, 'return_url' => $return_url, 'cancel_url' => $cancel_url, 'custom' => $custom, 'hash' => $hash ); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Recibiendo y validando la notificación de un pago
Notificaciones por correo electrónico
khipu permite enviar una notificación por correo electrónico a tantos correos como desees cada vez que un pago es recibido para tu cobrador. Este correo electrónico tendrá un enlace a una versión en PDF del comprobante de pago. Este comprobante estará firmado electrónicamente por el representante legal de khipu SpA.
Configuración
Para recibir notificaciones primero debes ingresar a tu cuenta khipu e ir a "Opciones de la cuenta". En la sección Notificaciones por correo electrónico debes agregar los correos donde quieres recibir las notificaciones usando la opción "Al recibir un pago".
Notificaciones por web service
khipu permite recibir notificaciónes en tu sitio web de manera automática por cada cobro exitoso. Esto es útil para que tu sitio web realize algún proceso cada vez que alguien pague, como por ejemplo habilitar un servicio o enviar algún bien a tus clientes.
khipu espera recibir un "Ok" como respuesta a la notificación (HTTP/1.1 Status code 200), de no ser así la notificación será reintentada múltiples veces de forma espaciada hasta por 48 horas, luego de lo cuál se enviará un correo electrónico al comercio advirtiendo la situación anómala. El dinero recibido será igualmente enviado al comercio a pesar de no tener exito en la notificación, teniendo como respaldo de la operación el envío por correo electrónico del comprobante de pago.
Configuración manual
Para recibir notificaciones primero debes ingresar a tu cuenta khipu e ir a "Opciones de la cuenta", en la sección "Para integrar khipu a tu sitio web". En la sección Notificación instantánea de pagos debes agregar la URL en donde tu sitio web escuchará las notificaciones y definir la versión de la API de notificaciones que quieres usar para las notificaciones.
Configuración por web service
https://khipu.com/api/1.3/updatePaymentNotificationUrl
Permite configurar las opciones de notificación instantanea de manera automática.
Parámetros:
Nombre | Descripción | |
---|---|---|
receiver_id | el id del cobrador | |
url | la url en tu sitio para enviar las notificaciones. | opcional |
api_version | la versión de la API de notificaciones | |
hash | String de verficación |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, url
, api_version
.
Ejemplo en PHP
En el siguiente ejemplo se configura la versión de la API de notificaciones en 1.3 y la url como "http://miurldenotificacion.com".
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $api_version = '1.3'; $notify_url = 'http://mi.url.cl'; $concatenated = "receiver_id=$receiver_id&url=$notify_url&api_version=$api_version"; $hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/updatePaymentNotificationUrl'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'url' => $notify_url , 'api_version' => $api_version , 'hash' => $hash ); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch);
Notificaciones versión API 1.3
Cada notificación enviada por khipu trae los siguientes parámetros:
Nombre | Descripción | |
---|---|---|
api_version | la versión de la API de notificación. (1.3) | |
notification_token | Cadena de caractéres única para cada pago, con esta se obtiene la notificación completa (ver) |
Notificaciones versión API 1.0, 1.1 y 1.2
Cada notificación enviada por khipu trae los siguientes parámetros:
Nombre | Descripción | |
---|---|---|
api_version | la versión de la API de notificación. (1.0, 1.1 o 1.2) | |
receiver_id | el id del cobrador (desde la api_version 1.2). | |
subject | el asunto del cobro. | |
amount | el monto total del pago. | |
custom | variable personalizada con datos. | |
currency | el código de la moneda en que se generó el cobro (código único de operación). | |
transaction_id | el identificador de la transacción. | |
notification_id | código único generado por khipu para cada pago. | |
payer_email | Correo electrónico del pagador (desde la api_version 1.1). | |
notification_signature | firma electrónica de los datos para validar la integridad de los datos. |
Importante: para evitar que alguien envie una notifiación fraudulenta, es muy importante que verifiques la autenticidad de los datos. Para esto, revisa la documentación para validación de pagos
Validación de pagos
Tu decides como khipu te informará cuando un pago se verifique para tu cuenta de cobro, en https://khipu.com/merchant/profile -> "Para integrar khipu a tu sitio web" -> "Notificación instantánea de pagos" puedes configurar una URL de notificación (que puedes sobreescribir al crear cada pago) y la versión de la API de notificación que khipu usará.
Validación mediante token de validación (API de notificación 1.3 o superior) (RECOMENDADA)
https://khipu.com/api/1.3/getPaymentNotification
Desde la versión 1.3 de la API de notificación de pagos el esquema de notificación es más simple y seguro.
La notificación de pago sólo tendrá dos campos api_version
y notification_token
Con ese token de notificación debes usar el endpoint https://khipu.com/api/1.3/getPaymentNotification
para obtener todos los datos de la notificación y si coinciden con un pago que estabas esperando procesarlo.
<?php $receiver_id = '<id de cobrador>'; $secret = '<id de cobrador>'; $notification_token = $_POST['notification_token']; $api_version = $_POST['api_version']; if($api_version != '1.3'){ exit('not supported'); } $concatenated = "receiver_id=$receiver_id¬ification_token=$notification_token"; $hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/getPaymentNotification'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'notification_token' => $notification_token , 'hash' => $hash); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); $notification = json_decode($output); // revisamos que correspondan una solicitud de pago generada por nosotros if($notification->receiver_id != $receiver_id){ exit('no es para mi'); } $orden = obtengoOrdenDesdeElBackend($notification->transaction_id); if($notification->amount == $orden->amount){ // procesamos el pago }
Resultado
Si la petición está correcta, khipu retornará un HTTP STATUS con valor 200 y en el cuerpo será un objeto JSON con la información del cobro. Ejemplo:
{ "notification_token": "j8kPBHaPNy3PkCh...hhLvQbenpGjA", "receiver_id": ID_DEL_COBRADOR, "subject": "Motivo del cobro", "amount": "100", "custom": "", "transaction_id": "MTX_123123", "payment_id": "qpclzun1nlej", "currency": "CLP", "payer_email": "ejemplo@gmail.com", "out_of_date_conciliation": false, "conciliation_date": 1436809600 }
Especial atención merecen los valores de conciliation_date
y out_of_date_conciliation
. El primero es la fecha exacta en la que khipu verificó que el dinero y se generaron los comprobantes de pago asociados. El segundo, es true
solo en el caso de que el dinero hubiera llegado después de la fecha máxima máxima especificada al generar el cobro.
Validación mediante web service (API de notificación 1.2 o inferior) (OBSOLETA)
https://khipu.com/api/1.3/verifyPaymentNotification
Cuando se trabaja con Notificación instantánea de pagos es importante verificar que los datos que llegán a tu servidor hayan sido enviados por khipu. Para evitar que alguien envie una notificación fraudulenta diciendo que un pago fue realizado, khipu envía en los parámetros de la notificación una firma digital que permite comprobar que el pago es verdadero. Para hacer esta comprobación existen dos alternativas.
La manera más sencilla de verificar los parámetros de un pago es usar el web service de verificación de khipu. Este servicio recibe los datos del pago y comprueba que la firma sea la correcta.
La respuesta de khipu en este servicio web puede ser VERIFIED cuando los parámetros fueron correctamente firmados o INVALID si la firma no concuerda con los parámetros. En ambos caso se devolverá HTTP STATUS 200.
Parametros de la validación mediante web service
Los parámetros que llegarán en la notificación están definidos por la versión de la api de notificación que estés usando. Esta versión se puede modificar en el menú "Opciones de la cuenta" en la sección "Notificación instantánea de pagos".
En la siguiente tabla se muestran los parámetros para cada versión de la API de notificaciones. También se indica el orden en que deben ser enviados para la validación
Versión | Orden | Comentarios |
---|---|---|
1.2 | api_version, receiver_id, notification_id, subject, amount, currency, transaction_id, payer_email, custom | |
1.1 | api_version, notification_id, subject, amount, currency, transaction_id, payer_email, custom | Descontinuada |
1.0 | api_version, notification_id, subject, amount, currency, transaction_id, custom | Descontinuada |
Importante: las versiones de la API de notificaciones inferiores anteriores a la 1.2 han sido descontinuadas y ya no pueden ser seleccionadas.
Verificación de seguridad
Es fundamental verificar que todos los parámetros de la notificación coincidan con los esperados, en particular receiver_id
debe ser tu Id de Cobrador, amount
, transaccion_id
, custom
y subject
: deben corresponder al producto o servicio que te pagaron.
Ejemplo en PHP
En el siguiente ejemplo se reciben los datos de notificación más el parametro con la firma notification_signature
. Estos parámetros se envían a khipu para verificar la integridad.
<?php // Mi verdadero id de cobrador $my_receiver_id = '<id de cobrador>'; // Leer los parametros enviados por khipu $api_version = $_POST['api_version']; $receiver_id = $_POST['receiver_id']; $notification_id = $_POST['notification_id']; $subject = $_POST['subject']; $amount = $_POST['amount']; $currency = $_POST['currency']; $custom = $_POST['custom']; $transaction_id = $_POST['transaction_id']; $payer_email = $_POST['payer_email']; // La firma digital enviada por khipu $notification_signature = $_POST['notification_signature']; if($api_version != '1.2'){ exit('not supported'); } // Creamos el string para enviar // Todos los parametros debene enviarse en este mismo orden $to_send = 'api_version='.urlencode($api_version). '&receiver_id='.urlencode($receiver_id). '¬ification_id='.urlencode($notification_id). '&subject='.urlencode($subject). '&amount='.urlencode($amount). '¤cy='.urlencode($currency). '&transaction_id='.urlencode($transaction_id). '&payer_email='.urlencode($payer_email). '&custom='.urlencode($custom); // Usamos CURL para hacer POST HTTP $ch = curl_init("https://khipu.com/api/1.3/verifyPaymentNotification"); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $to_send."¬ification_signature=".urlencode($notification_signature)); $response = curl_exec($ch); curl_close($ch); if ($response == 'VERIFIED' && $receiver_id == $my_receiver_id) { // Los parametros son correctos, ahora falta verificar que transacion_id, custom, subject y amount correspondan al pedido }
Cuando la respuesta de khipu es 'VERIFIED'
significa que podemos confiar en los parámetros recibidos y si el resto de los parámetros están en regla, terminar la transacción, por ejemplo, enviando el producto comprado.
Validación local (API de notificación 1.2 o inferior) (OBSOLETA)
La validación local permite verificar en tu propio servidor si los parámetros recibidos están bien firmados
Lo primero que debes hacer para verificar la firma es descargar el certificado de clave pública de khipu y subirlo a tu servidor.
Descargar el certificado de clave pública
Si estás usando una cuenta de cobro de desarrollo entonces deberás usar el certificado de desarrollo de khipu.
Descargar el certificado de clave pública (desarrollo)
Debes crear un string con todos los parámetros recibidos. Este orden debe ser siempre el mismo pues si cambia, las firmas no serán las mismas. Los parámetros a utilizar dependen de la versión de la api de notificación utilizada por tu comercio como se detalla en la siguiente tabla.
Versión | Parámetros | Comentarios |
---|---|---|
1.2 | api_version, receiver_id, notification_id, subject, amount, currency, transaction_id, payer_email, custom | |
1.1 | api_version, notification_id, subject, amount, currency, transaction_id, payer_email, custom | Descontinuada |
1.0 | api_version, notification_id, subject, amount, currency, transaction_id, custom | Descontinuada |
Luego debes extraer la llave pública del certificado y usarla para verificar la firma digital.
Ejemplo en PHP
En este ejemplo se hace el proceso completo. Se reciben los campos y se crea el string para verificar. Se lee la llave desde un certificado llamado khipu.pem y se comprueba la firma digital enviada por khipu.
<?php // Mi verdadero id de cobrador $my_receiver_id = '<id de cobrador>'; // Leer los parametros enviados por khipu $api_version = $_POST['api_version']; $receiver_id = $_POST['receiver_id']; $notification_id = $_POST['notification_id']; $subject = $_POST['subject']; $amount = $_POST['amount']; $currency = $_POST['currency']; $custom = $_POST['custom']; $payer_email = $_POST['payer_email']; $transaction_id = $_POST['transaction_id']; $notification_signature = $_POST['notification_signature']; if($api_version != '1.2'){ exit('not supported'); } // Creamos el string para verificar. El orden de los parametros // debe ser siempre el mismo $to_validate = 'api_version='.$api_version. '&receiver_id='.$receiver_id. '¬ification_id='.$notification_id. '&subject='.$subject. '&amount='.$amount. '¤cy='.$currency. '&transaction_id='.$transaction_id. '&payer_email='.$payer_email. '&custom='.$custom; // Leemos el certificado con la clave publica $filename = 'khipu.pem'; $fp = fopen($filename, "r"); $cert = fread($fp, filesize($filename)); fclose($fp); $pubkey = openssl_get_publickey($cert); // verificamos la firma $notification_validity = (openssl_verify($to_validate, base64_decode($notification_signature), $pubkey) == 1); openssl_free_key($pubkey); if ($notification_validity && $receiver_id == $my_receiver_id) { // Los parámetros son correctos. Si el receiver_id // es el correcto y los demás parámetros // coinciden con el pago esperado podemos procesar el pago. }
Cuando la variable $notification_validity
tiene valor true
y el resto de los parámetros (incluyendo el receiver_id, amount, transaccion_id, subject y custom) son los esperados, quiere decir que el pago fue hecho correctamente y podemos terminar la transacción, por ejemplo, enviando el producto comprado.
Importante: Aun cuando algunos parámetros pueden llegar vacios, como por ejemplo
custom
, igual debes incluirlo en el string de la firma. Por ejemplo, sitransaction_id
es vacio el string quedará parecido a"...rency=CLP&transaction_id=&custo..."
Administrar pagos
Enviar a conciliar un pago con transferencia normal y obtener datos para la transferencia
https://khipu.com/api/1.3/setRegularTransferConciliationInfo
Hay comercios que prefieren mantener el usuario en su sitio, para ellos es posible enviar a conciliar un pago con transferencia normal y obtener los datos para que el pagador haga la transferencia.
Para esto primero se debe haber creado el cobro usando la api de creación de URL de pago obteniendo el id del pago, posteriormente obtener el listado de bancos disponibles para pagar y preguntarle al pagador con que Banco hará el pago, cual es su identificador personal (RUT, DNI, etc) y su correo electrónico.
Parámetros:
Nombre | Descripción | |
---|---|---|
receiver_id | tu id de cobrador. | |
payment_id | el id de pago del pago que deseas conciliar. | |
bank_id | el id de banco del Banco seleccionado por el usuario para pagar. | |
payer_email | el correo electrónico del pagador | |
payer_personal_identifier | el RUT del pagador | |
hash | String de verificación. |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, payment_id
, bank_id
, payer_email
y payer_personal_identifier
.
Resultado
Si la llamada es exitosa se devolverá un código HTTP 200 y un objeto JSON con la información necesaria para el el pagador haga la transferencia.
Nombre | Descripción | |
---|---|---|
payment-id | id del pago. | |
currency-code | código ISO 4217 de la moneda a usar para pagar | |
amount | monto a transferir | |
country-code | código de dos letras ISO 3166-1 del país de la cuenta corriente destino | |
destination-bank-name | nombre del banco de destino | |
destination-bank-url | url del banco de destino | |
account-identifier | identificador (número) de la cuenta de destino | |
account-type | tipo de la cuenta de destino | |
account-holder-personal-identifier | identificador personal (RUT) del titular de la cuenta corriente de destino | |
account-holder-personal-name | nombre del titular de la cuenta corriente de destino | |
account-holder-personal-email | correo electrónico del titular de la cuenta corriente de destino | |
deadline | plazo hasta el que se aceptará la transferencia (en Unix timestamp) |
Ejemplo:
{ "payment-id": "d6somipp7y7v" ,"currency-code": "CLP" ,"amount": 50000.0 ,"country-code": "cl" ,"destination-bank-name": "Banco de Chile - Empresas" ,"destination-bank-url": "http://www.bancodechile.cl" ,"account-identifier": "18668108" ,"account-type": "Cuenta Corriente" ,"account-holder-personal-identifier": "76.187.287-7" ,"account-holder-personal-name": "Khipu CL B" ,"account-holder-email": "transferencias@khipu.com" ,"deadline": 1441816369 }
Ejemplo en PHP:
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $payment_id = '<id de pago>'; $bank_id = '<id del banco>'; // banco chile $payer_email = '<correo elecrónico del pagador>'; $payer_personal_identifier = '<RUT del pagador>'; $concatenated = "receiver_id=" . $receiver_id; $concatenated .= "&payment_id=" . $payment_id; $concatenated .= "&bank_id=" . $bank_id; $concatenated .= "&payer_email=" . $payer_email; $concatenated .= "&payer_personal_identifier=" . $payer_personal_identifier; $$hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/setRegularTransferConciliationInfo'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'payment_id' => $payment_id , 'bank_id' => $bank_id , 'payer_email' => $payer_email , 'payer_personal_identifier' => $payer_personal_identifier , 'hash' => $hash ); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Marcar un cobro como expirado
https://khipu.com/api/1.3/setBillExpired
Los cobros de khipu poseen fecha de expiración. Una vez que la fecha de expiración de un cobro se alcanza, este cobro no puede ser pagado. Con esta función puedes hacer adelantar la fecha de expiración para invalidar este cobro. Si es un cobro con varios destinatarios, ninguno de los destinatarios que aún no ha pagado podrá pagar. Los pagos que ya fueron pagados no sufrirán ningún cambio.
Para marcar un cobro como expirado, debes tener en el id del cobro. Esto se explica en la sección "Agregar cobros en portal de khipu".
Parámetros:
Nombre | Descripción | |
---|---|---|
receiver_id | tu id de cobrador. | |
bill_id | el id de cobro del cobro que deseas que expire. | |
text | Un texto que leerá la gente que llegue a la página de pago de un cobro expirado. | opcional |
hash | String de verificación. |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, bill_id
, text
.
Resultado
Si la llamada es exitosa se devolverá un código HTTP 200 y un objeto JSON vacio en el cuerpo de la respuesta.
Ejemplo en PHP
En este ejemplo se hace una llamada para expirar un cobro con el idenficador YaKIR. Además, se da un texto que leerá la gente que intente pagar fuera de plazo.
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $bill_id = 'YaKIR'; $text = 'Este cobro ha expirado'; $concatenated = "receiver_id=$receiver_id&bill_id=$bill_id&text=$text"; $$hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/setBillExpired'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'bill_id' => $bill_id , 'text' => $text , 'hash' => $hash ); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Marcar un pago como pagado
https://khipu.com/api/1.3/setPaidByReceiver
En el caso de que alguien te pague sin usar khipu, por ejemplo con una transferencia directa entre cuentas corrientes, esta función sirve para marcar un pago como realizado.
Para marcar un pago como realizado, debes tener en el id del pago. Esto se explica en la sección "Agregar cobros en portal de khipu".
Parámetros
Nombre | Descripción | |
---|---|---|
receiver_id | tu id de cobrador. | |
payment_id | el id de pago que deseas marcar como pagado. | |
hash | String de verificación. |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, payment_id
.
Resultado
Si la llamada es exitosa se devolverá un código HTTP 200 y un objeto JSON vacio en el cuerpo de la respuesta.
Ejemplo en PHP
En este ejemplo se hace una llamada para expirar un pago con el idenficador zfpmx5peen85.
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $payment_id = 'zfpmx5peen85'; $concatenated = "receiver_id=$receiver_id&payment_id=$payment_id"; $hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/setPayedByReceiver'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'payment_id' => $payment_id , 'hash' => $hash); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Marcar un pago como rechazado
https://khipu.com/api/1.3/setRejectedByPayer
En el caso de una persona definitvamente no pague o que un cobro sea inválido esta opción da la posibilidad de marcarlo como rechazado por el que paga. El cobro no podrá ser pagado y quedará en estado términado.
Para marcar un pago como rechazado, debes tener en el id del pago. Esto se explica en la sección "Agregar cobros en portal de khipu".
Para usar esta función debes hacer una llamada POST a la URL https://khipu.com/api/1.3/setRejectedByPayer con los siguientes parámetros:
Nombre | Descripción | |
---|---|---|
receiver_id | tu id de cobrador | |
payment_id | el id de pago que deseas marcar como rechazado. | |
text | un texto para indicar la razón de que el pago sea rechazado. | opcional |
hash | String de verificación. |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, payment_id
, text
.
Resultado
Si la llamada es exitosa se devolverá un código HTTP 200 y un objeto JSON vacio en el cuerpo de la respuesta.
Ejemplo en PHP
En este ejemplo se hace una llamada para marcar un pago con el idenficador gvektct6yjbl como rechazado.
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $payment_id = 'gvektct6yjbl'; $text = 'no corresponde'; $concatenated = "receiver_id=$receiver_id&payment_id=$payment_id&text=$text"; $hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/setRejectedByPayer'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'payment_id' => $payment_id , 'text' => $text , 'hash' => $hash); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Reversar un pago
https://khipu.com/api/1.3/instantReverse
Si deseas devolver el dinero de una transacción debes hacer esta llamada. Para poder devolver el dinero el pago tiene que estar pagado correctamente. Además, el pago solamente puede ser reversado durante el mismo día en que se efectuó.
Para marcar un pago como rechazado, debes tener en el notification_id del pago que te llega en la notificación instantanea
Para usar esta función debes hacer una llamada POST a la URL https://khipu.com/api/1.3/instantReverse con los siguientes parámetros:
Nombre | Descripción | |
---|---|---|
receiver_id | tu id de cobrador | |
notification_id | el igual al id de pago. | |
hash | String de verificación. |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, notification_id
.
Resultado
Si la llamada es exitosa se devolverá un código HTTP 200 y un objeto JSON vacio en el cuerpo de la respuesta.
Ejemplo en PHP
En este ejemplo se hace una llamada para reversar un pago con el idenficador gvektct6yjbl.
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $notification_id = 'gvektct6yjbl'; $concatenated = "receiver_id=$receiver_id¬ification_id=$notification_id"; $hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/instantReverse'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'notification_id' => $notification_id , 'hash' => $hash ); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Consultar el estado de un pago
https://khipu.com/api/1.3/paymentStatus
Es posible consultar el estado en que se encuentra un pago en particular. Esto es útil para saber, por ejemplo, si el pago está siendo verificado por khipu o no se ha comenzado a pagar.
Para consultar el estado de un pago, debes tener en el id del pago. Esto se explica en la sección "Agregar cobros en portal de khipu".
Si la llamada es exitosa se devolverá un JSON con la información del pago. El siguiente es un ejemplo de este JSON.
{ "status": "done", "detail": "normal" }
El significado del campo status
es el siguiente:
- pending: khipu no ha recibido notificación de que sehaya hecho la transferencía.
- verifying: khipu ha recibido notificación de que se ha hecho una transferencía desde el terminal de pagos y está verificando con los bancos.
- done: el pago está marcado como listo. Esto no asegura que la transferencía se haya realizado por khipu. Para revisar el detalle de esto, se debe consultar el campo detail del JSON.
El campo detail
contiene el detalle de como acabó el pago. Este campo solo toma importancía cuando status
es done.
- pending: el pago no ha sido terminado.
- normal: el pago fue pagado usando khipu y terminó de manera normal.
- marked-payed-by-receiver: el cobrador ha indicado que el pago ha finalizado, aunque no haya sido hecho usando khipu.
- rejected-by-payer: el pagador ha informado que no pagará este pago.
- reversed: el pago fue reversado y la plata será devuelta
- marked-as-abuse: el pagador indica que el pago no correspondía.
Parámetros
Nombre | Descripción |
---|---|
receiver_id | tu id de cobrador. |
payment_id | el id de pago que deseas consultar. |
hash | String de verificación. |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, payment_id
.
Ejemplo en PHP
En este ejemplo se hace una llamada para ver el estado del pago con identificador gvektct6yjbl.
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $payment_id = 'gvektct6yjbl'; $concatenated = "receiver_id=$receiver_id&payment_id=$payment_id"; $hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/paymentStatus'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'payment_id' => $payment_id , 'hash' => $hash); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Consultar información de un pago
https://khipu.com/api/1.3/paymentInfo
Es posible consultar la información detallada de un pago en particular. Esto incluye toda la información con que fue creado el pago (asunto, cuerpo), dirección del comprobante de pago, dirección de las imagenes y adjuntos, etc.
Para consultar la información de un pago, debes tener en el id del pago. Esto se explica en la sección "Agregar cobros en portal de khipu".
Si la llamada es exitosa se devolverá un JSON con la información del pago. El siguiente es un ejemplo de este JSON.
{ "id": "y9zyjqdoiwfb" ,"subject": "El asunto del pago" ,"body": "El cuerpo del pago" ,"amount": 100 ,"status": "pending" ,"detail": "pending" ,"picture": "https://s3.amazonaws.com/billattachment.khipu.com/ff20a9e9e0e838107103ae5a0f5115e4aedd23df78001750bc3eb0c47544dxb/imagen2.png" ,"receipt_url": "https://s3.amazonaws.com/notifications.khipu.com/CPKH-9204141127-y9zyjqdoiwfb.pdf" ,"expires_date": 1400094079 ,"attachments": [] ,"return_url": "" ,"cancel_url": "" ,"detail_items":{} ,"fields" :{} }
Es importante notar que en esta llamada también está presente el estado del pago, pero es mejor usar la llamada de paymentStatus que es más eficiente. También se debe notar que con esta llamada también puedes obtener la dirección del comprobante de pago de la transacción.
Parámetros
Nombre | Descripción |
---|---|
receiver_id | tu id de cobrador. |
payment_id | el id de pago que deseas consultar. |
hash | String de verificación. |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, payment_id
.
Ejemplo en PHP
En este ejemplo se hace una llamada para ver la información del pago con identificador y9zyjqdoiwfb.
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $payment_id = 'y9zyjqdoiwfb'; $concatenated = "receiver_id=$receiver_id&payment_id=$payment_id"; $hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/paymentInfo'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'payment_id' => $payment_id , 'hash' => $hash); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Obtener un código de pago
https://khipu.com/api/1.3/paymentCode
Con esta llamada se obtiene un código único para poder usar la función de pago en persona en la aplicación móvil de khipu. Este código solo se puede obtener para pagos que estén pendientes de pagar.
Para obtener el código, debes tener en el id del pago. Esto se explica en la sección "Agregar cobros en portal de khipu".
Si la llamada es exitosa se devolverá un JSON con el código. El siguiente es un ejemplo de este JSON.
{"code":"924088"}
Parámetros
Nombre | Descripción |
---|---|
receiver_id | tu id de cobrador. |
payment_id | el id de pago del que deseas obtener un código. |
type | el tipo de código. Puede ser short o long. |
hash | String de verificación. |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, payment_id
, type
.
El parámetro type puede indicar un código corto o largo. El código corto (short) es de cuatro dígitos y tiene una duración de 2 minutos. Pasados estos dós minutos deberás obtener un nuevo código. El código largo (long) tiene seis dígitos y tiene una duración de un día desde que se pide.
Ejemplo en PHP
En este ejemplo se hace una llamada para obtener un código para un pago con identificador gvektct6yjbl.
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $payment_id = 'gvektct6yjbl'; $type = 'short'; $concatenated = "receiver_id=$receiver_id&payment_id=$payment_id&type=$type"; $hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/paymentStatus'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'payment_id' => $payment_id , 'type' => $type , 'hash' => $hash); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Liberar un pago retenido
https://khipu.com/api/1.3/confirmTransaction
Khipu permite que el dinero recaudado sea retenido durante una cantidad de días. El comercio tiene entonces tiempo verificar disponibilidad, despacho, etc. Cuando el comercio está listo para hacer la entrega, debe liberar el pago. Al liberar el pago se puede indicar que parte del dinero sea devuelto al pagados.
Si el pago no es liberado antes de una cantidad fija de días, la totalidad del dinero es devuelta al pagador.
Liberar el pago, debes tener en el id del pago. Esto se explica en la sección "Agregar cobros en portal de khipu".
Si la llamada es exitosa se devolverá un código HTTP 200 y un objeto JSON vacio en el cuerpo de la respuesta.
Atención: Esta funcionalidad no está disponible automáticamente. Si quieres usar pagos retenidos con tu cuenta de cobro, debes solicitarlo escribiendo en nuestro sistema de soporte.
Parámetros
Nombre | Descripción | |
---|---|---|
receiver_id | tu id de cobrador. | |
payment_id | el id de pago del que deseas liberar. | |
amount | la cantidad de dinero que se debe devolver al pagador. Si no se envía, entonces todo el dinero correspondiente se deposita en la cuenta de cobro. | opcional |
text | un texto para explicar la devolución (si es que existe). | opcional |
hash | String de verificación. |
Para el cálculo del parámetro hash debes referirte a la documentación de cálculo del hash. El orden de los parámetros es receiver_id
, payment_id
, amount
, text
.
Ejemplo en PHP
En este ejemplo se hace una llamada para liberar un pago con el id gvektct6yjbl.
<?php $receiver_id = '<id de cobrador>'; $secret = '<llave de cobrador>'; $payment_id = 'gvektct6yjbl'; $amount = '100'; $text = 'Falta de inventario'; $concatenated = "receiver_id=$receiver_id&payment_id=$payment_id&amount=$type&text=$text"; $hash = hash_hmac('sha256', $concatenated , $secret); $url = 'https://khipu.com/api/1.3/paymentStatus'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, true); $data = array('receiver_id' => $receiver_id , 'payment_id' => $payment_id , 'amount' => $amount , 'text' => $text , 'hash' => $hash); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); $output = curl_exec($ch); $info = curl_getinfo($ch); curl_close($ch); echo $output;
Recibiendo y validando notificación de rendición
Notificaciones por web service
khipu permite recibir notificaciónes en tu sitio web de manera automática con el detalle de cada rendición realizada hacia la cuenta corriente asociada a tu cuenta de cobro.
Configuración
Para recibir notificaciones primero debes ingresar a tu cuenta khipu e ir a "Opciones de la cuenta". En la sección Notificación instantanea de rendiciones debes agregar la URL en donde tu sitio web escuchará las notificaciones y definir la versión de la API de notificaciones que quieres usar.
Ejemplo en PHP
Las notificaciones de rendición se hacen utilizando un mensaje en estándar JOSE JWS, y ensobrado gzip.
Los mensajes de las notificaciones de rendición se firman con el siguiente certificado.
Descargar el certificado de clave pública
Si estás usando una cuenta de cobro de desarrollo entonces deberás usar el certificado de desarrollo de khipu.
Descargar el certificado de clave pública (desarrollo)
En este ejemplo se hace uso de la librería Namshi/Jose.
<?php require_once 'vendor/autoload.php'; use Namshi\JOSE\JWS; $jws_text=gzdecode($HTTP_RAW_POST_DATA); $jws=JWS::load($jws_text); // Leemos el certificado con la clave publica $filename = 'khipu_signer.pem'; $fp = fopen($filename, "r"); $cert = fread($fp, filesize($filename)); fclose($fp); $pubkey = openssl_get_publickey($cert); $payload = $jws->getPayload(); if ($jws->isValid($public_key)) { /* Si la firma del mensaje es valida se puede procesar el mensaje */ $report=$payload['report']; $fecha_desde=$report['startDate']; // fecha de inicio de la rendición $fecha_hasta=$report['endDate']; //fecha de termino de la rendición $report_items=$report['items']; //pagos incluidos en la rendición foreach($report_items as $item){ $customer=$item['customer']; //datos del pagador local_process($item['paymentDate'], //fecha del pago $item['paymentSubject'], //asunto del pago $item['khOperationCodeUID'],//codigo unico de operación khipu $item['merchantTxID'], //id de transacción informado por el comercio $item['customer']['customerName'], //nombre del pagador $item['customer']['customerUID'], //rut del pagador $item['customer']['customerEmail'],//correo electrónico del pagador $item['customer']['customerBankName'], //nombre del banco origen $item['feeScheme'], //esquema de comision $item['txAmount'], //monto de la transacción $item['khipuFee']); //comisión khipu } }