API de khipu para crear cobros y recibir pagos (v1.3)

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:

1. 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.
2. 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.
3. 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).
4. 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.
5. 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
  • Multiples cuentas de cobro
  • Activar modo desarrollador
  • Llave del cobrador
  • Cuentas de cobro en modo desarrollador
  • Cálculo del parámetro HASH
  • Consultar el estado de un cobrador
  • Obtener listado de bancos
• Creando un cobro
  • Botón de pago en un formulario web
  • Creación de URL para un pago
  • Agregar cobros en portal de khipu
• Recibiendo y validando la notificación de un pago
  • Notificaciones por correo electrónico
  • Notificaciones por web service
    • Configuración manual
    • Configuración por web service
    • Notificaciones
  • Validación de pagos
    • Validación mediante token (recomendada)
    • Validación mediante web service (obsoleta)
    • Validación local (obsoleta)
• 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:

1. 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".
2. 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

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

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

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&notify_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:

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&notify_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

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&notify_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:

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:

Notificaciones versión API 1.0, 1.1 y 1.2

Cada notificación enviada por khipu trae los siguientes parámetros:

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&notification_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

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).
            '&notification_id='.urlencode($notification_id).
            '&subject='.urlencode($subject).
            '&amount='.urlencode($amount).
            '&currency='.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."&notification_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.

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.
                '&notification_id='.$notification_id.
                '&subject='.$subject.
                '&amount='.$amount.
                '&currency='.$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, si transaction_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:

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.

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:

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

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:

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:

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&notification_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

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

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

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

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