README

Versión Biblioteca: 1.3

Versión API Khipu: 1.3

Biblioteca PHP para utilizar los servicios de Khipu.com

La documentación de Khipu.com se puede ver desde aquí: https://khipu.com/page/api

Instalación: composer

composer require freshworkstudio/khipu

Introducción

La API de Khipu cuenta con varios servicios, los cuales son:

• Ver estado de la cuenta Khipu
• Crear un botón de pago
• Crear un cobro por Mail
• Crear URL para un pago
• Expirar un cobro
• Consultar estado de un pago
• Marcar un pago como pagado
• Marcar un pago como rechazado
• Actualizar versión de la notificación
• Obtener listado de bancos

Para utilizar estos servicios se debe cargar el archivo Khipu.php

Algunos Ejemplos

1) Crear Cobros y enviarlos por Mail

Para crear cobros, necesitamos identificar al cobrador y a los destinatarios. A continuación un ejemplo

<?php
  // ...
  require_once __DIR__ . '/../vendor/autoload.php';
  $khipu = new Khipu();
  // Para usar el servicio para crear cobros y enviarlos por Mail necesitamos
  // identificar al cobrador ya que es requerido para el servicio.
  $khipu->authenticate($receiver_id, $llave);

  // Luego cargamos el servicio.
  $khipu_service = $khipu->loadService('CreateEmail');

  // Preparamos los datos que queremos enviar
  $data = array(
    'subject' => 'Título del pago',
    'body' => 'Descripción del producto',
    'transaction_id' => '1',
    'pay_directly' => 'false',
    // Decimos que envie los correos.
    'send_emails' => 'true',
    // Si contamos con algun sitio, podemos redireccionar al usuario
    // a esta URL una vez que pague.
    'return_url' => '',
    // Le damos un tiempo de expiración.
    'expires_date' => time() + 30 * 10,
    // Opcionalmente podemos asignar una URL de una imagen.
    'picture_url' => '',
  );
  // Recorremos los datos y se lo asignamos al servicio
  foreach($data as $name => $value) {
    $khipu_service->setParameter($name, $value);
  }
  /**
   * En reemplazo de setParameter se podría usar
   * $this->setParameters($data);
   */
  // Agregamos un destinatario con un monto
  $khipu_service->addRecipient('Cliente', 'cliente@gmai.com', 25000);

  // Lo enviamos
  $json = $khipu_service->send();

2) Crear Página de Pago

Crear una página de pago también se requiere identificarse, a continuación un ejemplo:

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

  $Khipu = new Khipu();
  $Khipu->authenticate($receiver_id, $llave);
  $khipu_service = $Khipu->loadService('CreatePaymentPage');

  $data = array(
    'subject' => 'Título del pago',
    'body' => 'Descripción del producto',
    'amount' => 10000,
    // Página de exito
    'return_url' => $return_url,
    // Página de fracaso
    'cancel_url' => $cancel_url,
    'transaction_id' => 1,
    // Dejar por defecto un correo para recibir el comprobante
    'payer_email' => 'cliente@gmail.com',
    // url de la imagen del producto o servicio
    'picture_url' => $picture_url,
    // Opcional
    'custom' => 'Custom Variable',
    // definimos una url en donde se notificará del pago
    'notify_url' => $notify_url,
  );
  // Recorremos los datos y se lo asignamos al servicio.
  foreach ($data as $name => $value) {
    $khipu_service->setParameter($name, $value);
  }
  // Luego imprimimos el formulario html
  echo $khipu_service->renderForm();

3) Recibiendo y validando la notificación de un pago

Este servicio debe ser utilizado en la página que recibirá el POST desde Khipu y no require identificar al cobrador. A continuación un ejemplo:

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

  $Khipu = new Khipu();
  // No necesitamos identificar al cobrador para usar este servicio.

  $api_version = $_POST['api_version'];

  if($api_version == '1.2') {
	$khipu_service = $Khipu->loadService('VerifyPaymentNotification');
  	$khipu_service->setDataFromPost();
	$response = $khipu_service->verify();
	if($response['response'] == 'VERIFIED'){
		//el pago esta verificado, hacemos algo al respecto
	}

  } else if ($api_version == '1.3') {
	$Khipu->authenticate($receiver_id, $llave);
	$khipu_service = $Khipu->loadService('GetPaymentNotification');
  	$khipu_service->setDataFromPost();
	$response = json_decode($khipu_service->consult());
	
	// validamos que la notificacion de pago corresponda con una solicitud de pago esperada
	if($response->transaction_id == $mi_transaction_id &&  $response->receiver_id == $receiver_id, $response->amount == $mi_amount) {
		// la notificacion esta ok, la estaba esperando y debo procesar el pedido
	} else {
		// la notificacion no es para mi o no la estaba esperando, la ignoro
	}
	

  } else {
	// api de notificacion no soportada
  }

4) Verificar Estado de una cuenta Khipu

Este servicio permite consultar el estado de una cuenta khipu, la cual retorna un json mencionando el ambiente en que se encuentra y si puede recibir pagos. A continuación un ejemplo:

<?php
  // ...
  require_once __DIR__ . '/../vendor/autoload.php';
  $Khipu = new Khipu();
  $Khipu->authenticate($receiver_id, $llave);
  $khipu_service = $Khipu->loadService('ReceiverStatus');

  // Aquí se hace la consulta a khipu sobre la cuenta.
  $json = $khipu_service->consult();

En la carpeta examples existen otros ejemplos.

Extra

La clase Khipu cuenta con dos funciones estáticas, las cuales son:

getUrlService()

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

  // Imprime https://khipu.com/api/1.3/verifyPaymentNotification
  echo Khipu::getUrlService('VerifyPaymentNotification');
?>

Esta función recibe el nombre del servicio y retorna la URL de Khipu que corresponde.

getButtonsKhipu()

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

  $buttons = Khipu::getButtonsKhipu();
?>

Esta función retorna la lista de links de los botones de Khipu.com, la pueden ver aquí: https://khipu.com/page/botones-de-pago

Testing

phpunit src/KhipuTest.php