Integra Flow como sistema de pago

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.

¿No eres parte de Flow?

Antes de continuar debes registrarte en Flow y seleccionar la opción Deseo utilizar Flow para recibir pagos. Si aún no estas registrado puedes hacerlo aquí:

Regístrate

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.

A continuación te explicamos los dos modelos de integración con Flow el indirecto y directo.

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 indirecto
Método de integración indirecto

Descripción de acciones

Descripción
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

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 directo
Método de integración directo

Descripción de acciones

Descripción
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.

Descargar Kit

Kit de pagos Flow

Descargar

Descargar 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á los datos que envía a Flow, con esto Flow se asegura que los datos recibidos provienen sólo de tu tienda.

Descargalo a continuación en el botón Obtener el Certificado Digital o ingresa a Mis Datos en el menú principal.

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

Certificado digital

Descargar

Descargar certificado digital desde el menú de Flow

Ingresa a la opción Mis Datos, ubicado en el menú principal.

Ingresar a mis datos
Ingresar a mis datos

Dirígete al final de la página y haz clic en Descargar Certificado

Ir a descargar certificado
Ir a descargar certificado

Haz clic en Descargar Certificado Digital y obtendrás el archivo comercio.pem

Descargar certificado
Descargar certificado

El Kit de Flow

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

Parte Nombre archivo/carpeta Descripción
Archivo de Configuración config.php En este archivo se configuran las direcciones de sus páginas de confirmación, éxito y fracaso. Deberás indicar las rutas de los certificados digitales y archivos de logs. También, él 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. 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 fue 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 integrar tu comercio al sitio de producción de Flow, es conveniente probar la integración sobre el sitio de pruebas. Donde 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 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

Dato Valor
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 usar:
Rut 11.111.111-1
Clave 123

Pago Rechazado

Dato Valor
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 usar:
Rut 11.111.111-1
Clave 123

Sitio de Producción

Una vez que hayas probado la integración en el sitio de pruebas, debes descargar desde flow.cl el certificado digital, reemplazando el obtenido desde el sitio de pruebas. Además debes 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, 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.

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

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

OpenSSL
OpenSSL

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:

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:

Descripción
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 a 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í podrás 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:

Descripción
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. Podrá recibir la información con el resultado de la transacción.

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

Descripción
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_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. Podrá recibir la información con el resultado de la transacción.

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

Descripción
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_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>