API de khipu para crear cobros y recibir pagos (v 2.0)

Ésta es la más reciente versión de la API. Quizás quieres ver la documentación de la versión anterior.

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:

El proceso de creación, pago y validación es el siguiente:

  1. El cobrador genera un cobro usando la API y despliega un botón para la compra.
  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).

Flujo de pago

¡Importante! En el tercer paso se redirecciona al pagador a una página de retorno (3a) o posible abandono del pago (3b). El éxito 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 del paso 5 antes de entregar el producto o servicio. Lo mismo ocurre con el rechazo (3b), el usuario todavía cuenta con instancias para retomar el pago y concretarlo.

Tabla de contenidos

  1. Conceptos previos
  2. Cuenta de cobro
  3. Múltiples cuentas de cobro
  4. Credenciales
  5. Seguridad
  6. Ambiente de pruebas y paso a producción
  7. Cuenta de cobro en modo desarrollador
  8. Banco de pruebas
  9. Instalación de la biblioteca adecuada
  10. Acceso a internet
  11. Caso de uso común
  12. Crear un pago
  13. Iniciar el pago
  14. El cliente es redireccionado al comercio
  15. Recibir la notificación y entregar el servicio
  16. Referencia de la API

Conceptos previos

Cuenta de cobro

Cuando una persona crea una cuenta de usuario en khipu automáticamente se le creará una “cuenta de cobro”. Esta cuenta de cobro es la cuenta a la que quedarán asociados los pagos que reciba de otras personas.

Para poder cobrar usando una cuenta de cobro esta debe tener una cuenta bancaria. La cuenta bancaria se donde, al día siguiente, se deposite la recaudación diaria. Esta cuenta bancaria puede ser cambiada y en cualquier momento y afectará a todos los pagos que no hayan sido rendidos todavía.

Al principio una cuenta de cobro no tiene una cuenta bancaria asociada. Para asociar una cuenta bancaria debes ir a tu cuenta khipu y tratar de crear un cobro. El sistema te pedirá completar un pago usando esa cuenta bancaria para asegurar que tengas acceso a ella. El monto del pago será devuelto al día siguiente.

Importante: Las cuentas de cobro, para el caso de Chile, tienen un monto máximo de $50.000. Para aumentar esta cantidad, debes contactarte con nosotros a soporte@khipu.com.

Múltiples cuentas de cobro

Una cuenta de usuario en khipu puede tener crear (o tener acceso) a múltiples cuentas de cobro. Eso sirve, por ejemplo, para tener distintos comercios y cada uno con su propia cuenta de cobro. Cada cuenta de cobro debe tener configurada su cuenta bancaria, pero varias cuentas de cobro pueden compartir los datos de una misma cuenta bancaria donde se rendirá el dinero.

Credenciales

Toda cuenta de cobro posee credenciales que permiten utilizar la API REST. Estas credenciales se generan al momento de crear la cuenta de cobro.

Las credenciales consisten en dos parámetros:

  • receiverId: Es el identificador único de esta cuenta de cobro y no puede ser cambiado.
  • secret: Es una llave secreta y única de la cuenta de cobro.

Lo más importante de las credenciales es “secret”. Esta llave sirve para firmar los requerimientos de la API y no debe ser compartida con nadie. Siempre se puede crear una llave nueva que invalidará la antigua en caso de que quieras cambiarla.

Seguridad

Para asegurar que ambas partes involucradas en creacion y validacion de un pago puedan asegurar sean las que dicen ser, se usan dos mecanismos de seguridad distintos. Por una parte khipu utiliza un certificado de validacion extendida que permite al cobrador siempre saber que se está comunicando efectivamente con los servidores oficiales de khipu. Por otra parte, el comercio debe firmar todos los llamados a la API usando las credenciales únicas de la cuenta.

Para aprender el proceso de la firma en detalle revisa la documentación sobre la firma.

Ambiente de pruebas y paso a producción

En esta sección te mostramos los pasos necesarios para comezar la integración con tu sitio. Lo más importante es notar que durante el periodo de desarrollo y de pruebas debes usar credenciales de cuentas de cobro de desarrollo. Solo cuando el sitio esté listo y la integración preparada para hacer pagos reales, debes cambiar las credenciales por las de la cuenta de cobro de producción.

Cuenta de cobro en modo desarrollador

Khipu no tiene una versión de pruebas separada de la versión de producción como otras plataformas. En vez de esto, se usa la API y los servidores de la plataforma principal. Para efectuar pruebas de desarrollo se usa una “cuenta de cobro de desarrollador”. Estas cuentas de cobro son idénticas a las cuentas normales pero tienen algunas diferencias:

Las cuentas corrientes asociadas no son reales pues no se rinde dinero real. Se crean solo para hacer pruebas. Los cobros generados con ellas solo pueden ser pagados usando bancos de prueba.

Para crear una cuenta de desarrollo debes seguir los siguientes pasos:

  • Ir a tu perfil de usuario en khipu
  • En “Opciones de desarrollador” activar el modo desarrollador.
  • Luego ir a configurar y elegir “Cuentas de cobro”
  • Ahora aparecerá un botón “Crear cuenta en modo desarrollador”

Ahora que tienes una cuenta de desarrollo, lo único que necesitas de ella son las credenciales de la cuenta. Estas se obtienen en las “Opciones de la cuenta” en la opción de “Para integrar khipu a tu sitio web”.

Banco de pruebas

Las cuentas de cobro de desarrollo solo pueden recibir pagos desde Bancos de pruebas. Estos bancos son bancos creados por khipu para hacer estas pruebas.

El banco de prueba permite que probar el proceso de pago sea completo, incluyendo ir al banco y depositar a khipu o utilizar la transferencia simplificada. Como estos bancos no operan con dinero real, puedes hacer todas las transferencias que desees pues nunca se acaba el saldo.

Estos bancos, además, tienen instrucciones en pantalla para poder entrar, llenar claves y hacer transferencias.

Instalación de la biblioteca adecuada

Hemos generado una cantidad de bibliotecas para varios lenguages de programación populares. El siguiente código te enseña a instalar estás bibliotecas.

PHP

En PHP para las bibliotecas y las dependencias usamos “composer“. Debemos agregar khipu a las dependencias del archivo “composer.json”.

{
    "require": {
        "khipu/khipu-api-client": "2.7.7"
    }
}

Y luego ejecutar:

$ composer install
Installing dependencies (including require-dev)
  - Installing khipu/khipu-api-client (2.7.0)
    Downloading: 100%

Writing lock file
Generating autoload files

Luego, en nuestros archivos de php debemos agregar la siguiente línea para tener disponible la biblioteca:

require __DIR__ . '/vendor/autoload.php';

Java

En Java, usando Maven para resolver las dependencias, debemos agregar las siguientes líneas a nuestro archivo “pom.xml”.

<dependency>
    <groupId>com.khipu</groupId>
    <artifactId>khipu-api-client</artifactId>
    <version>2.7.0</version>
</dependency>

Si quieres agregar las dependenciás para groovy, gradle u otras plataformas puedes buscar el cliente de khipu en maven

Java 1.6

La biblioteca de khipu está pensada para ser usada con una máquina virtual 1.7 o superior. Aun así, es posible utilizarla con java 1.6. Para esto es necesario agregar los siguientes cambios.

Primero, es necesario agregar un proveedor criptográfico más reciente. Para eso es necesario agregar esta nueva dependencia:

<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk15on</artifactId>
    <version>1.54</version>
</dependency>

Luego, para que este proveedor criptográfico esté disponible es necesario agregarlo a los disponibles de la máquina virtual. En el código fuente de la aplicación es necesario agregar las siguientes líneas:

import org.bouncycastle.jce.provider.BouncyCastleProvider;
...
Security.addProvider(new BouncyCastleProvider());

También es posible dejar este proveedor integrado en la máquina virtual. Con eso nos evitamos incluir las líneas de código y el proveedor queda disponible para otras aplicaciones. Para esto es necesario seguir las instrucciones disponibles en la página de [http://www.bouncycastle.org](
http://www.bouncycastle.org/wiki/display/JA1/Provider+Installation)

Ruby

En Ruby hemos preparado una gema. Para instalar la gema, debemos usar el comando “gem”:

$ gem install khipu-api-client

Luego en tu script debes agregar esta línea para tener disponible el cliente:

require 'khipu-api-client'

.NET

Para .NET tenemos disponible una biblioteca empaquetada en un NuGet que se instala usando el Package Manager Console

PM> Install-Package KhipuApiClient

Acceso a internet

Para poder acceder a la API REST de khipu es necesario tener una conexión a internet. Esto es necesario para poder crear y modificar pagos.

Cada vez que khipu recibe un pago se le avisa al comercio para que este pueda entregar el producto o servicio al cliente. Este aviso puede ser por correo electrónico o utilizando la API de notificaciones instantaneas. El mecanismo recomendado es la notificación instantánea pues no requiere intervención humana una vez que está bien configurada. Estas notificaciones son invocaciones que khipu debe hacer a un WEBSERVICE en el sitio web del comercio. Por eso, este web service debe ser visible desde Internet.

Caso de uso común.

Vamos a analizar el caso de uso más común de la API REST y es hacer un pago en un comercio web para obtener un producto. El flujo más común tiene los siguientes pasos:

  • El cliente elige sus productos y elige pagar
  • El comercio crea un pago usando la API REST
  • El comercio envía al cliente a pagar a khipu
  • El cliente paga
  • El cliente es redireccionado al sitio web del comercio y espera unos momentos mientras khipu verifica el pago.
  • El pago es verificado y se notifica al comercio via web service.
  • El comercio entrega el producto o servicio.

Vamos ahora los pasos donde es necesaria la integración con khipu:

Crear un pago POST /payments

Después de que el cliente elige sus productos y opta por pagar, comienza el proceso de pago. La mayoría de los software de comercio electrónico funcionan de manera similar. Todos tienen algún tipo de objeto que simboliza la orden de compra. Lo que debemos hacer es relacionar esta orden de compra con un pago en khipu. Veamos el siguiente código:

<?php

// Debemos conocer el $receiverId y el $secretKey de ante mano.
$receiverId = obtener-al-crear-una-cuenta-de-cobro;
$secretKey = 'obtener-al-crear-una-cuenta-de-cobro';

require __DIR__ . '/vendor/autoload.php';

$configuration = new Khipu\Configuration();
$configuration->setReceiverId($receiverId);
$configuration->setSecret($secretKey);
// $configuration->setDebug(true);

$client = new Khipu\ApiClient($configuration);
$payments = new Khipu\Client\PaymentsApi($client);

try {
    $opts = array(
        "transaction_id" => "MTI-100",
        "return_url" => "http://mi-ecomerce.com/backend/return",
        "cancel_url" => "http://mi-ecomerce.com/backend/cancel",
        "picture_url" => "http://mi-ecomerce.com/pictures/foto-producto.jpg",
        "notify_url" => "http://mi-ecomerce.com/backend/notify",
        "notify_api_version" => "1.3"
    );
    $response = $payments->paymentsPost("Compra de prueba de la API" //Motivo de la compra
        , "CLP" //Moneda
        , 100.0 //Monto
        , $opts //campos opcionales
);

    print_r($response);
} catch (\Khipu\ApiException $e) {
    echo print_r($e->getResponseBody(), TRUE);
}

        

int receiverId = obtener-al-crear-una-cuenta-de-cobro;
String secretKey = 'obtener-al-crear-una-cuenta-de-cobro';

ApiClient apiClient = new ApiClient();
apiClient.setKhipuCredentials(receiverId, secretKey);
apiClient.setPlatform("demo-client", "2.0");
// apiClient.setDebugging(true);
PaymentsApi paymentsApi = new PaymentsApi();
paymentsApi.setApiClient(apiClient);

Map options = new HashMap<>();
options.put("transactionId", "MTI-100");
options.put("returnUrl", "http://mi-ecomerce.com/backend/return");
options.put("cancelUrl", "http://mi-ecomerce.com/backend/cancel");
options.put("pictureUrl", "http://mi-ecomerce.com/pictures/foto-producto.jpg");
options.put("notifyUrl", "http://mi-ecomerce.com/backend/notify");
options.put("notifyApiVersion", "1.3");

PaymentsCreateResponse response = paymentsApi.paymentsPost("Compra de prueba de la API" //Motivo de la compra
        , "CLP" //Moneda
        , 100.0 //Monto
        , options //campos opcionales
);

System.out.println(response);

        
require 'khipu-api-client'

receiver_id = obtener-al-crear-una-cuenta-de-cobro
secret_key = 'obtener-al-crear-una-cuenta-de-cobro'


Khipu.configure do |c|
  c.secret = secret_key
  c.receiver_id = receiver_id
  c.platform = 'demo-client'
  c.platform_version = '2.0'
  # c.debugging = true
end
client = Khipu::PaymentsApi.new
response = client.payments_post('Motivo del cobro', 'CLP', 120000, { // Monto a cobrar
    transaction_id: 'FACT2001',
    expires_date: DateTime.new(2016, 4, 4),
    body: 'Descripción de la compra',
    picture_url: 'http://mi-ecomerce.com/pictures/foto-producto.jp',
    return_url: 'http://mi-ecomerce.com/backend/return',
    cancel_url: 'http://mi-ecomerce.com/backend/cancel',
    notify_url: 'http://mi-ecomerce.com/backend/notify',
    notify_api_version: '1.3'
})
        

Configuration.ReceiverId = obtener-al-crear-una-cuenta-de-cobro;
Configuration.Secret = "obtener-al-crear-una-cuenta-de-cobro";
PaymentsApi a = new PaymentsApi();

try
{
    DateTime dt = DateTime.Now;
    dt = dt.AddDays(5);
    PaymentsCreateResponse response = a.PaymentsPost("Compra de prueba de la API", "CLP", 100.0
                                    , transactionId: "FACT2001"
                                    , expiresDate: dt
                                    , body: "Descripción de la compra"
                                    , pictureUrl: "http://mi-ecomerce.com/pictures/foto-producto.jpg"
                                    , returnUrl: "http://mi-ecomerce.com/backend/return"
                                    , cancelUrl: "http://mi-ecomerce.com/backend/cancel"
                                    , notifyUrl: "http://mi-ecomerce.com/backend/notify"
                                    , notifyApiVersion: "1.3");
    System.Console.WriteLine(response);
}
catch (ApiException e)
{
    Console.WriteLine(e);
}
        

En el primer paso obtenemos el objeto de orden de compra. Este puede ser creado en el momento o recuperado mediante un “id”. En el siguiente paso se crea un pago en khipu usando la biblioteca asociada.

Si observas bien, en el parámetro “transaction_id” de la llamada se envía el identificador de la orden de compra. Esto es necesario para que en el momento de la conciliación podamos obtener la orden de compra y darla por pagada.

La respuesta de la llamada será un objeto con información del cobro creado. El campo “payment_id” contiene el identificador de nuestro pago y la url a la cual debemos enviar al usuario a pagar.

Ofrecer listado de bancos (Opcional) POST /banks

Este paso es opcional pero puede ser útil para algunos comercios. En la llamada anterior para crear pagos puede verse el parámetro “ID del banco para pagar”. Este ID sirve para crear un pago con un banco ya elegido (solo de los banco soportados por khipu). Para obtener este id se puede usar la llamada banksGet que entrega el listado de los bancos soportados por khipu, sus nombres, su id y otra información. Veamos el siguiente ejemplo:

<?php

// Debemos conocer el $receiverId y el $secretKey de ante mano.
$receiverId = obtener-al-crear-una-cuenta-de-cobro;
$secretKey = 'obtener-al-crear-una-cuenta-de-cobro';

require __DIR__ . '/vendor/autoload.php';

$configuration = new Khipu\Configuration();
$configuration->setReceiverId($receiverId);
$configuration->setSecret($secretKey);
// $configuration->setDebug(true);

$client = new Khipu\ApiClient($configuration);
$banksApi = new Khipu\Client\BanksApi($client);

try {
    $response = $banksApi->banksGet();
    print_r($response);
} catch (\Khipu\ApiException $e) {
    echo print_r($e->getResponseBody(), TRUE);
}


int receiverId = obtener-al-crear-una-cuenta-de-cobro;
String secretKey = 'obtener-al-crear-una-cuenta-de-cobro';

ApiClient apiClient = new ApiClient();
apiClient.setKhipuCredentials(receiverId, secretKey);
apiClient.setPlatform("demo-client", "2.0");
// apiClient.setDebugging(true);

BanksApi banksApi = new BanksApi();
banksApi.setApiClient(apiClient);
BanksResponse response = banksApi.banksGet();
System.out.println(response);

require 'khipu-api-client'

receiver_id = obtener-al-crear-una-cuenta-de-cobro
secret_key = 'obtener-al-crear-una-cuenta-de-cobro'


Khipu.configure do |c|
  c.secret = secret_key
  c.receiver_id = receiver_id
  c.platform = 'demo-client'
  c.platform_version = '2.0'
  # c.debugging = true
end

banks = Khipu::BanksApi.new
response = banks.banks_get()
print response

El resultado de la llamada contiene el valor “banks” que es un listado de bancos. Cada banco tiene un “bank_id” con el valor que podemos usar para crear pagos configurados.

Iniciar el pago

Una vez creado un pago debemos empezar el proceso de pagar. Para esto podemos hacerlo de dos manera. La manera recomendada es utilizar nuestra biblioteca javascript que se encargará de comenzar el pago. Puedes encontrar amplia documentación en el sitio web de github. Además, puedes usar nuestro ejemplo de integración de la biblioteca que simula un comercio que utiliza esta biblioteca.

La otra opción para iniciar el pago, es simplemente redirigir al cliente a la url de pago en khipu. Esta url corresponde al parámetro payment_url que devuelve la llamada de crear pago.

El cliente es redireccionado al comercio

Luego de que el cliente realiza el pago en el portal de khipu será redireccionado de vuelta al sitio web del comercio. La url del comercio a la que es redirigido el usuario debe ser configurada por cada pago en el campo “return_url”, aunque podría ser la misma para todos los pagos.
Es muy importante notar que cuando el usuario llega de vuelta a la página del comercio esto no significa que el pago esté verificado. En esta página el comercio debe decir que el pago está en proceso de verificación y que se debe esperar un momento. La página debe consultar de manera periódica al servidor del comercio para ver el estado de la orden de compra e informar al usuario cuando el pago haya sido confirmado. Para esto, existen 3 estrategias, siendo las más comunes:

  • WebSockets: El servidor del comercio informa al browser del cliente que el pago está confirmado para que lo despliegue. Es la forma más eficiente, pero la más compleja de implementar. Para más información https://es.wikipedia.org/wiki/WebSocket
  • Llamadas AJAX: La página verifica mediante una llamada AJAX al servidor del comercio acerca del estado de la orden. Cuando la respuesta es positiva la página le avisa al usuario que el pago ha sido completado.
  • Recargar la página periódicamente: Es el mecanismo más sencillo y consiste en utilizar un timer para recargar la página de manera periódica, por ejemplo cada 10 segundos. Cada vez que la página carga se verifica si la orden está completa. Si lo está, se redirige al usuario a la página de éxito. Si no, debe indicar al usuario que es necesario seguir esperando y usar un nuevo timer.

Recibir la notificación y entregar el servicio GET /payments

Si has configurado una URL para recibir una notificación entonces khipu invocará inmediatamente después de conciliar el pago. Esta notificación se recibe por la API de notificaciones instantáneas de khipu esta La versión de esta API define la manera en que khipu notifica al comercio. Existen varias versiones de la API, pero nos enfocaremos en la más reciente, la 1.3. En esta versión de la API llegarán 2 parámetros por POST, uno con la versión de la API, “api_version”, que sirve para verificar que sea la versión correcta. El segundo parámetro es “notification_token”. Usando notification_token podremos obtener la información del cobro para poder dar por pagado el producto.

Importante: khipu espera 30 segundos para recibir respuesta de la notificación. Si después de 30 segundos no se obtiene respuesta, khipu intentará notificar nuevamente más tarde. Por eso, si el proceso de recibir la notificación demora más de 30 segundos, es necesario que se efectue en segundo plano y se responda inmediatamente.

Veamos el siguiente código:

<?php
require __DIR__ . '/vendor/autoload.php';


$receiver_id = obtener-al-crear-una-cuenta-de-cobro;
$secret = 'obtener-al-crear-una-cuenta-de-cobro';

$api_version = 'obtener-desde-los-parametros';  // Parámetro api_version
$notification_token = 'obtener-desde-los-parametros'; //Parámetro notification_token
$amount = monto-original-del-cobro;

try {
    if ($api_version == '1.3') {
        $configuration = new Khipu\Configuration();
        $configuration->setSecret($secret);
        $configuration->setReceiverId($receiver_id);
        // $configuration->setDebug(true);

        $client = new Khipu\ApiClient($configuration);
        $payments = new Khipu\Client\PaymentsApi($client);

        $response = $payments->paymentsGet($notification_token);
        if ($response->getReceiverId() == $receiver_id) {
            if ($response->getStatus() == 'done' && $response->getAmount() == $amount) {
                // marcar el pago como completo y entregar el bien o servicio
            }
        } else {
            // receiver_id no coincide
        }
    } else {
        // Usar versión anterior de la API de notificación
    }
} catch (\Khipu\ApiException $exception) {
    print_r($exception->getResponseObject());
}
        
int receiverId = obtener-al-crear-una-cuenta-de-cobro;
String secret = 'obtener-al-crear-una-cuenta-de-cobro';
String apiVersion = "obtener-desde-los-parametros"; // Parámetro api_version
String notificationToken = "obtener-desde-los-parametros"; // Parámetro notification_token
double amount = monto-original-del-cobro;

if (apiVersion.equals("1.3")) {
    ApiClient apiClient = new ApiClient();
    apiClient.setKhipuCredentials(receiverId, secret);
    apiClient.setPlatform("demo-client", "2.0");
    // apiClient.setDebugging(true);
    PaymentsApi paymentsApi = new PaymentsApi();
    paymentsApi.setApiClient(apiClient);

    PaymentResponse response = paymentsApi.paymentsGet(notificationToken);
    if (response.getReceiverId().longValue() == receiverId) {
        if (response.getStatus().equals("done") && response.getAmount() == amount) {
            // marcar el pago como completo y entregar el bien o servicio
        }
    } else {
        // receiverId no coincide
    }
} else {
    // Usar versión anterior de la API de notificación
}
    
require 'khipu-api-client'
receiver_id = obtener-al-crear-una-cuenta-de-cobro
secret = 'obtener-al-crear-una-cuenta-de-cobro'
api_version = 'obtener-desde-los-parametros' # Parámetro api_version
notification_token = 'obtener-desde-los-parametros'  # Parámetro notification_token
amount = monto-original-del-pago

if api_version == '1.3'
  Khipu.configure do |c|
    c.receiver_id = receiver_id
    c.secret = secret
    c.platform = 'demo-client'
    c.platform_version = '2.0'
    # c.debugging = true
  end

  client = Khipu::PaymentsApi.new
  response = client.payments_get(notification_token)
  if response.receiver_id == receiver_id
    if response.status == 'done' && response.amount == amount
      # marcar el pago como completo y entregar el bien o servicio
    end
  else
    # receiver_id no coincide
  end
else
  # Usar versión anterior de la API de notificación
end
        
Configuration.ReceiverId = obtener-al-crear-una-cuenta-de-cobro;
Configuration.Secret = "obtener-al-crear-una-cuenta-de-cobro";
string notificationToken = "obtener-desde-los-parametros-del-request";
string apiVersion = "obtener-desde-los-parametros-del-request";
double amount = monto-original-del-cobro;

if(apiVersion.Equals("1.3")) {
    PaymentsApi a = new PaymentsApi();

    try
    {
         PaymentsResponse response = a.PaymentsGet(notificationToken);
         if(response.ReceiverId.Equals(Configuration.ReceiverId)
                && response.Status.Equals("done") && response.Amount == amount)
         {
            # marcar el pago como completo y entregar el bien o servicio
         }
         else
         {
            # ignorar la invocación
         }
    }
    catch (ApiException e)
    {
        Console.WriteLine(e);
    }
}
        

Este código debe estar disponible desde internet visible desde los servidores de khipu. khipu envía dos parámetros en esta llamada.

  • api_version: Es la versión de la API de notificación. No se debe confundir con la versión de la API Rest.
  • notification_token: Es un identificador con el cual podemos obtener la información del pago conciliado. Es importante notar que no es el código único de un pago.

Lo primero que hacemos en el código es verificar que api_version coincida con 1.3 pues el manejo de la notificación depende de la versión de la api.

Luego, usamos el parámetro notification_token para obtener el pago completo. Esto lo hacemos con la llamada GET que se hace a continuación.

Usando la información del pago debemos asegurarnos de dos cosas muy importantes: Primero, el receiverId del pago debe corresponder con el receiverId de nuestro comercio, y segundo, que el pago esté conciliado. Esto último se hace verificando que el parámetro “status” tenga el valor “done”. Además, es bueno verificar que todos los datos del pago concuerden con los de la orden original. Si algún dato no corresponde, es el punto se debe mandar a reembolsar el dinero.

El último paso es modificar la orden de compra para reflejar que está lista y enviar el producto y/o servicio al cliente.

Importante: khipu espera un código de respuesta 200 para saber que la notificación fue procesada. En el código de ejemplo no se muestra claramente pues es la respuesta por omisión. Si por ejemplo el web service arroja un error después de procesar la orden, khipu volverá a enviar la notificación. Si recibes una notificación para un pago que ya has procesado, deberás entregar un código 400. Este código indica a khipu que no debe seguir reintentando notificar ese pago en particular.

Referencia de la API

Si quieres ver la definición completa de la API REST de khipu puedes ver la documentación online