freshworkstudio/khipu

Composer package for Tifon's Khipu Library (https://github.com/khipu/lib-php)

Khipu

Versión Biblioteca: 1.3, _(*1)

Versión API Khipu: 1.3, _(*2)

Biblioteca PHP para utilizar los servicios de Khipu.com, _(*3)

La documentación de Khipu.com se puede ver desde aquí: https://khipu.com/page/api, _(*4)

Instalación: composer

composer require freshworkstudio/khipu, _(*5)

Introducción

La API de Khipu cuenta con varios servicios, los cuales son:, _(*6)

• 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, _(*7)

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, _(*8)

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

Esta función recibe el nombre del servicio y retorna la URL de Khipu que corresponde., _(*9)

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, _(*10)

Testing

phpunit src/KhipuTest.php, _(*11)