Kit php

Integra Flow

Si tienes una página de comercio electrónico desarrollada en PHP, puedes integrar Flow mediante el Kit PHP y comenzar a operar con pagos online:

  • Pagos con tarjetas de crédito/débito bancarias, mediante Webpay.
  • Pagos con tarjetas del retail (Cencosud, CMR, Ripley) y bancos, mediante Servipag.
  • Pago en efectivo en locales adheridos a Multicaja.

Antes de comenzar a operar con Flow, es importante haber seleccionado los medios de pagos que desees utilizar (Webpay, Servipag y/o Multicaja) y su respectiva comisión. Si deseas revisar o editar tus medios de pago hazlo en la sección Mis datos.

Modelo de Integración

Toda la comunicación entre el comercio y Flow viaja firmada electrónicamente con certificados digitales, las firmas digitales son verificadas en cada punto de comunicación, asegurando la confiabilidad entre el emisor y el receptor.

Existen dos modelos de integración con Flow:

  • Modo indirecto. Con este modo de integración, antes de enviar la transacción a Webpay, Servipag o Multicaja, se presenta una página de Flow con los datos de la transacción. Además, en dicha página se muestran los medios de pago habilitados por el vendedor, permitiendo al pagador elegir el deseado.
  • Modo directo. Con este modo de integración Flow envía la transacción directo a Webpay, Servipag o Multicaja según corresponda, sin presentar una página de Flow con los datos de la transacción.

Modo indirecto

Modo indirecto

Descripción de acciones:

  1. El comercio, utilizando el Kit, envía a Flow una Orden de Pago firmada electrónicamente.
  2. Flow recibe la Orden y verifica que provenga de un comercio registrado. En este paso presenta una página para que el pagador confirme la orden y seleccione el medio de pago deseado: Webpay, Servipag o Multicaja.
  3. Flow deriva al pagador a la página del medio de pago (Webpay, Servipag o Multicaja) seleccionado.
  4. El medio de pago envía a Flow el resultado de la transacción y solicita confirmarla.
  5. Flow envía el resultado del pago a la página de confirmación del comercio.
  6. El comercio recibe la confirmación del pago. La página del comercio tiene 15 segundos para responder la recepción de la confirmación. Si su página de confirmación no responde en ese tiempo y la transacción había sido aprobada por el medio de pago, la transacción se dará por aprobada.
  7. Flow envía al medio de pago la confirmación de la transacción.
  8. Si el pago es exitoso Flow deriva el control a la página de éxito del comercio. Además, se envía un email notificado del pago al vendedor y al pagador.
  9. Si el pago es rechazado Flow despliega su página de fracaso.
  10. Desde la página de fracaso de Flow si el cliente hace click en el botón (Volver al comercio) se invoca la página de fracaso del comercio.

Modo directo

Modo directo

Descripción de acciones:

  1. El comercio, utilizando el Kit, envía a Flow una Orden de Pago firmada electrónicamente.
  2. Flow deriva al pagador a la página del medio de pago (Webpay, Servipag o Multicaja) informado desde el Kit.
  3. El medio de pago envía a Flow el resultado de la transacción y solicita confirmarla.
  4. Flow envía el resultado del pago a la página de confirmación del comercio.
  5. El comercio recibe la confirmación del pago. La página del comercio tiene 15 segundos para responder la recepción de la confirmación. Si su página de confirmación no responde en ese tiempo y la transacción había sido aprobada por el medio de pago, la transacción se dará por aprobada.
  6. Flow envía al medio de pago la confirmación de la transacción.
  7. Si el pago es exitoso Flow deriva el control a la página de éxito del comercio. Además, se envía un email notificado del pago al vendedor y al pagador.
  8. Si el pago es rechazado Flow despliega su página de fracaso.
  9. Desde la página de fracaso de Flow si el cliente hace clic en el botón (Volver al comercio) se invoca la página de fracaso del comercio.

Descarga el Kit de Pagos Flow

Descarga el Kit de pagos Flow aquí.

Descarga el Certificado Digital

El Certificado Digital es un archivo con nombre comercio.pem que contiene la clave privada de la firma electrónica con el que tu tienda firmará lo datos que envía a Flow, con esto Flow se asegura que los datos recibidos provienen sólo de tu tienda.

Desacarga el Certificado Digital aquí o ingresa a "Mis Datos" para descargarlo.

Atención: Para integrar tu página de comercio electrónico con Flow debes estar registrado como vendedor, es decir, en el registro, debes chequear la opción ¿Desea recibir pagos?. Una vez registrado podrás descargar tu Certificado Digital.


Advertencia: El Certificado Digital que descargues del Sitio de Pruebas no te servirá para el Sitio de Producción y viceversa. Para cada ambiente deberás descargar su propio Certificado Digital.

El Kit de Flow

El Kit de Pagos está hecho para sitios de ecommerce que utilicen PHP. Se compone de las siguientes partes:

  • Archivo de Configuracion (config.php): En este archivo se deben configurar las direcciones de sus páginas de confirmación, éxito y fracaso. Además, deberá indicar las rutas de los certificados digitales y archivos de logs, así como también, el o los medios de pago que usarás, el tipo de integración y el email con que está registrado en Flow.
  • Página de Confirmación (confirma.php): Corresponde a una página que será llamada por Flow con el resultado de la transacción. Para esto Flow le entregará los datos de la transacción.
  • Página de Éxito (exito.php): Esta página será llamada por Flow una vez que se aceptó la transacción y le enviará los datos de la transacción exitosa.
  • Página de Fracaso (fracaso.php): Esta página será llamada por Flow cuando la transacción fué rechazada.
  • Página de retorno (retorno.php): Corresponde a la página de retorno que será llamada por Flow cuando un pagador emita un cupón de pago.
  • API de Flow: (flowAPI.php) El archivo flowAPI.php contiene la clase con las funcionalidades necesarias para integrarse con Flow.
  • Certificados digitales (keys): La carpeta keys contiene la llave pública de Flow flow.pubkey. En esta carpeta debe dejar la llave privada comercio.pem. Esta llave deberá bajarla desde Flow.
  • Logs (logs): Corresponde a la carpeta donde el Flow registrará los pasos de una transacción. Flow generará un archivo de log por día. El nombre del archivo será: flowLog_fecha.txt.

Configurando el ambiente

Sitio de Pruebas

Antes de integrarse tu comercio al sitio de producción de Flow, es conveniente probar la integración sobre nuestro sitio de pruebas. Aquí podrás hacer pruebas completas simulando el pago de tus clientes contra el sitio de certificación de WebPay y/o un sitio de pruebas para Servipag y Multicaja.

Para utilizar el sitio de pruebas deberás acceder a Certificación Flow y registrarte de la misma forma en que estás registrado en Flow. Una vez registrado, debes descargar el certificado digital, este certificado sólo servirá para el sitio de pruebas, para producción deberás descargar el certificado desde el sitio de producción Producción Flow.

Para conectar tu comercio al sitio de certificación debes configurar en el archivo config.php del Kit el valor de $flow_url_pago = 'http://flow.tuxpan.com/app/kpf/pago.php'.

Para probar utiliza los siguientes datos al realizar un pago mediante WebPay:

  • Pago Exitoso:
    N° Tarjeta de Crédito: 4051885600446623
    Año de Expiración: Cualquiera
    Mes de Expiración: Cualquiera
    CVV: 123
    En la simulación del banco ingresar:
    Rut: 11.111.111-1
    Clave: 123
  • Pago Rechazado:
    N° Tarjeta de Crédito: 5186059559590568
    Año de Expiración: Cualquiera
    Mes de Expiración: Cualquiera
    CVV: 123
    En la simulación del banco ingresar:
    Rut: 11.111.111-1
    Clave: 123

Sitio de Producción

Una vez que hayas probado la integración en el sitio de pruebas, deberás descargar desde flow.cl el certificado digital, reemplazando el obtenido desde el sitio de pruebas, además deberás modificar en el archivo config.php del Kit el valor de $flow_url_pago = 'https://www.flow.cl/app/kpf/pago.php'.

OpenSSL

El API de Flow trabaja con certificados electrónicos para asegurar que la información proviene del comercio registrado, así como también, las respuestas de Flow vienen firmadas y el API se encarga de verificar que la firma corresponda.

Para utilizar firmas electrónicas es necesario que esté habilitado en su servidor PHP la extensión php_openssl.

Para verificar si su servidor PHP tiene habilitado open_ssl busque la sección correspondiente en phpinfo y verifique que OpenSSL support esté enabled.

Si su servidor es Windows y no tiene habiltado open_ssl, descomente la línea extension=php_openssl.dll en el archivo php.ini de su servidor.

Permisos de carpetas

Para que el Kit de Flow funcione correctamente se deben configurar correctamente los permisos de las carpetas keys y logs:

Carpeta keys: permisos 755

Carpeta logs: permisos 777

Configurando el Kit

Lo primero que debe hacer es configurar el kit de Flow. Esto se hace en el archivo config.php del kit.

Usted debe configurar:
  • Su página de Éxito
  • Su página de Fracaso
  • Su página de Confirmación
  • Su página de Retorno
  • La página de pago Flow
  • La ruta (path) donde tendrá los certificados digitales
  • La ruta (path) donde estarán los logs
  • El email con el que está registrado en Flow
  • El medio de pago (Webpay, Servipag, Multicaja o todos)
  • El tipo de integración (directa o indirecta)

Importante:
La página de Retorno sólo aplica al medio de pago Multicaja. Corresponde a la página donde volverá el cliente una vez que generó el cupón de pago. Recomendamos que dicha url sea la página principal de tu tienda virtual.

config.php

<?php
/*******************************************************************************
* config                                                                      	*
* Página de configuración del comercio                                          *
* Version: 1.4                                                                 	*
* Date:    2016-08-17                                                         	*
* Author:  flow.cl                                                     			*
********************************************************************************/


/**
 * Ingrese aquí la URL de su página de éxito
 * Ejemplo: http://www.comercio.cl/kpf/exito.php
 * 
 * @var string
 */
$flow_url_exito = 'http://www.comercio.cl/kpf/exito.php';

/**
 * Ingrese aquí la URL de su página de fracaso
 * Ejemplo: http://www.comercio.cl/kpf/fracaso.php
 * 
 * @var string
 */
$flow_url_fracaso = 'http://www.comercio.cl/kpf/fracaso.php';

/**
 * Ingrese aquí la URL de su página de confirmación
 * Ejemplo: http://www.comercio.cl/kpf/confirmacion.php
 * 
 * @var string
 */
$flow_url_confirmacion = 'http://www.comercio.cl/kpf/confirma.php';

/**
 * Ingrese aquí la URL de su página de retorno
 * Ejemplo: http://www.comercio.cl
 * 
 * @var string
 */
$flow_url_retorno = 'http://www.comercio.cl';

/**
 * Ingrese aquí la página de pago de Flow
 * Ejemplo:
 * Sitio de pruebas = http://flow.tuxpan.com/app/kpf/pago.php
 * Sitio de produccion = https://www.flow.cl/app/kpf/pago.php
 * 
 * @var string
 */
$flow_url_pago = 'http://flow.tuxpan.com/app/kpf/pago.php';

# Commerce specific config

/**
 * Ingrese aquí la ruta (path) en su sitio donde están las llaves
 * 
 * @var string
 */
$flow_keys = 'c:\wamp\www\flowComercio\web\kpf\keys';

/**
 * Ingrese aquí la ruta (path) en su sitio donde estarán los archivos de logs
 * 
 * @var string
 */
$flow_logPath = 'c:\wamp\www\flowComercio\web\kpf\logs';

/**
 * Ingrese aquí el email con el que está registrado en Flow
 * 
 * @var string
 */
$flow_comercio = 'emailFlow@comercio.com';

/**
 * Ingrese aquí el medio de pago
 * Valores posibles:
 * Solo Webpay = 1
 * Solo Servipag = 2
 * Solo Multicaja = 3
 * Todos los medios de pago = 9
 * 
 * @var string
 */
$flow_medioPago = '9';

/**
 * Ingrese aquí el modo de acceso
 * Valores posibles:
 * Mostrar pasarela Flow = f 
 * Ingresar directamente al medio de pago = d
 * 
 * @var string
 */
$flow_tipo_integracion = 'f';
?>

Creando una nueva Orden

Para enviar a Flow una nueva Orden de Pago debe seguir los siguientes pasos:

  1. Incluya el archivo flowAPI.php
  2. Cree una nueva instancia de la clase flowAPI
  3. En un bloque try/catch utilice el método ->new_orden, pasando como parámetros su número de orden de compra, el monto, el concepto de pago y el email del pagador. En nuestro ejemplo más abajo, le estamos pasando una Orden de Compra N° 1000, un monto de $20000, un concepto de "Pago de Orden N° 10000" y el email usuario@email.com. En su caso, los valores deberá obtenerlos desde su carro de compras.
    Si usted no posee el email de la persona que va realizar el pago deberá enviarlo en blanco, de esta forma el pagador tendrá que ingresarlo en la página que mostrará Flow con los datos de la transacción (pasarela Flow). Si decide utilizar el modo de integración directo y no envía el email de la persona que realizará el pago, entonces se mostrará la pasarela Flow.
    Si existe un error el bloque catch administrará el error. El resultado del método ($flow_pack) será el paquete de datos firmados que se enviarán en el post.
    Usted puede configurar el Kit para aceptar sólo uno de los medios de pago o todos. También puede enviar por cada transacción un medio de pago distinto. El método ->new_order acepta un quinto parámetro opcional (medioPago). Si no se utiliza, la orden se creará con el Medio de Pago configurado en config.php. Los valores posibles para medioPago son:
    • 1 (Sólo Webpay)
    • 2 (Sólo Servipag)
    • 3 (Sólo Multicaja)
    • 9 (Todos los medios de pago)
    Recuerde que debe configurar los medios de pago y las tarifas respectivas en su registro de Flow.
  4. En un formulario <form> envíe su orden.

orden.php

<?php
include("kpf/flowAPI.php");

//Crea una nueva instancia del API
$flowAPI = new flowAPI();

$orden_compra = "1000";
$monto = 20000;
$concepto = "Pago de Orden N° 1000";
$email_pagador = "usuario@email.com";
//Opcional el medio de pago (Webpay = 1, Servipag = 2, Multicaja = 3, Todos = 9)
$medioPago = $flow_medioPago;

try {
	// Genera una nueva Orden de Pago, Flow la firma y retorna un paquete de datos firmados
	$flow_pack = $flowAPI->new_order($orden_compra, $monto, $concepto, $email_pagador);
	// Si desea enviar el medio de pago usar la siguiente línea
	//$flow_pack = $flowAPI->new_order($orden_compra, $monto, $concepto, $email_pagador, $medioPago);
	
} catch (Exception $e) {
	header('location: error.php');
}

?>

<!--Formulario HTML que envía la Nueva Orden -->
<form method="post" action="<?php echo $flow_url_pago; ?>">
  <input type="hidden" name="parameters" value="<?php echo $flow_pack; ?>" />
  <button type="submit">Pagar en Flow</button>
</form>

Antes de enviar la orden de pago, el log deberá haber escrito las siguientes lineas:
[2014-03-05 12:41:06.000000 ::1 - new_order ] Iniciando nueva Orden
[2014-03-05 12:41:06.000000 ::1 - flow_pack ] Orden N°: 1000 -empaquetado correcto


Página de Confirmación

Esta página será invocada por Flow con el resultado del pago de la transacción, para lo cual Flow le entregará los datos de dicha transacción. Aquí usted podrá hacer validaciones respecto al N° de la Orden de Compra y el monto, además de actualizar su propia información con los datos recibidos.

Flow intentará conectarse a su página de confirmación por un tiempo de 15 segundos. Si en ese tiempo no recibe una respuesta, o la respuesta que recibe no viene en el formato esperado y esta es aprobada por el medio de pago, entonces Flow la dará como aprobada y le notificará que hubo un problema con la comunicación a su sitio.

En su página de confirmación siga los siguientes pasos:

  1. Incluya el archivo flowAPI.php
  2. Cree una nueva instancia de la clase flowAPI
  3. En un bloque try/catch utilice el método ->read_confirm() para leer el resultado de la transacción
  4. Obtenga los datos de la transacción
  5. Confirme la recepción de la confirmación con el método->build_response(true)

confirma.php

<?php
include 'flowAPI.php';

//Crea una nueva instancia del API
$flowAPI = new flowAPI();

try {
	// Lee los datos enviados por Flow
	$flowAPI->read_confirm();
	
} catch (Exception $e) {
	// Si hay un error responde false
	echo $flowAPI->build_response(false);
	return;
}

//Recupera Los valores de la Orden
$FLOW_STATUS = $flowAPI->getStatus();  //El resultado de la transacción (EXITO o FRACASO)
$ORDEN_NUMERO = $flowAPI->getOrderNumber(); // N° Orden del Comercio
$MONTO = $flowAPI->getAmount(); // Monto de la transacción
$ORDEN_FLOW = $flowAPI->getFlowNumber(); // Si $FLOW_STATUS = "EXITO" el N° de Orden de Flow
$PAGADOR = $flowAPI->getPayer(); // El email del pagador

if($FLOW_STATUS == "EXITO") {
	// La transacción fue aceptada por Flow
	// Aquí puede actualizar su información con los datos recibidos por Flow
	echo $flowAPI->build_response(true); // Comercio envía recepción de la confirmación
} else {
	// La transacción fue rechazada por Flow
	// Aquí puede actualizar su información con los datos recibidos por Flow
	echo $flowAPI->build_response(true); // Comercio envía recepción de la confirmación
}
?>

Una vez pasado por la página de confirmación el log debería agregar las siguientes líneas:
[2014-03-05 12:05:54.000000 127.0.0.1 - read_confirm ] Lee Status: EXITO
[2014-03-05 12:05:54.000000 127.0.0.1 - read_confirm ] Firma verificada
[2014-03-05 12:05:54.000000 127.0.0.1 - read_confirm ] Lee Numero Orden: 1000
[2014-03-05 12:05:54.000000 127.0.0.1 - read_confirm ] Lee Monto: 20000.00
[2014-03-05 12:05:54.000000 127.0.0.1 - read_confirm ] Lee Orden Flow: 757
[2014-03-05 12:05:54.000000 127.0.0.1 - flow_build_response ] Orden N°: 1000 - Status: ACEPTADO


Página de Exito

Su página de éxito será invocada por Flow al concretarse un pago en forma satisfactoria.

Su página de éxito podrá recibir la información desde Flow con el resultado de la transacción.

En su página de éxito siga los siguientes pasos:

  1. Incluya el archivo flowAPI.php
  2. Crea una nueva instancia de la clase flowAPI
  3. En un bloque try/catch utilice el método ->read_result() para leer el resultado de la transacción
  4. Obtenga los datos de la transacción
  5. Si lo desea presente los datos en su página

exito.php

<?php
include 'flowAPI.php';

//Crea una nueva instancia del API
$flowAPI = new flowAPI();

try {
	// Lee los datos enviados por Flow
	$flowAPI->read_result();
} catch (Exception $e) {
	header($_SERVER['SERVER_PROTOCOL'] . ' 500 Ha ocurrido un error interno', true, 500);
}

//Recupera los datos enviados por Flow
$ordenCompra = $flowAPI->getOrderNumber();
$monto = $flowAPI->getAmount();
$concepto = $flowAPI->getConcept();
$pagador = $flowAPI->getPayer();
$flowOrden = $flowAPI->getFlowNumber();
?>

<html>
<head>
	<title>Página de éxito de comercio</title>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
</head>
<body>
	<h1>Página de éxito de Comercio</h1>
	Su pago se ha realizado exitosamente<br><br>
	Orden de Compra: <?php echo $ordenCompra?><br>
	Monto: <?php echo $monto?><br>
	Descripción: <?php echo $concepto?><br>
	Pagador: <?php echo $pagador?><br>
	Flow Orden N°: <?php echo $flowOrden?><br>
	<br>
	Gracias por su compra
</body>
</html>

Si de ejecuta la página de éxito el log debería agregar la siguiente línea:
[2014-03-05 13:55:17.000000 192.168.85.76 - read_result ] Datos recuperados Orden de Compra N°: 1000


Página de Fracaso

Su página de fracaso será invocada por Flow sólo si el pagador hace clic en el botón "Volver al Comercio" de la página de fracaso de Flow.

Su página de fracaso podrá recibir la información desde Flow con el resultado de la transacción.

En su página de fracaso siga los siguientes pasos:

  1. Incluya el archivo flowAPI.php
  2. Crea una nueva instancia de la clase flowAPI
  3. En un bloque try/catch utilice el método ->read_result() para leer el resultado de la transacción
  4. Obtenga los datos de la transacción
  5. Si lo desea presente los datos en su página

fracaso.php

<?php
include 'flowAPI.php';

//Crea una nueva instancia del API
$flowAPI = new flowAPI();

try {
	// Lee los datos enviados por Flow
	$flowAPI->read_result();
} catch (Exception $e) {
	header($_SERVER['SERVER_PROTOCOL'] . ' 500 Ha ocurrido un error interno', true, 500);
}

//Recupera los datos enviados por Flow
$ordenCompra = $flowAPI->getOrderNumber();
$monto = $flowAPI->getAmount();
$concepto = $flowAPI->getConcept();
?>

<html>
<head>
	<title>Página de fracaso de comercio</title>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
</head>
<body>
	<h1>Página de fracaso de Comercio</h1>
	Su pago se ha sido rechazado<br><br>
	Orden de Compra: <?php echo $ordenCompra?><br>
	Monto: <?php echo $monto?><br>
	Descripción: <?php echo $concepto?><br>
	<br>
	Si lo desea intente nuevamente
</body>
</html>