Bienvenido a la documentación de referencia del API REST de Flow! REST es un protocolo de servicio web que se presta para un desarrollo rápido mediante el uso de la tecnología HTTP y JSON.

La API REST de Flow proporciona un amplio conjunto de operaciones y recursos para:

• Payments (Pagos)

• Customer (Clientes, cobros, cargos automáticos)

• Refunds (Reembolsos)

• Subscriptions (Suscripciones, cobros recurrentes)

• Coupons (Cupones de descuento para subscripciones)

• Settlement (Liquidaciones de pagos, reembolsos y comisiones,)

• Merchants (Gestión de comercios asociados)

La API se encuentra en constante crecimiento, añadiendo nuevos servicios y/o mejorando funcionalidades existentes para que nuestros clientes puedan sacar el mayor provecho posible a sus integraciones. Por lo mismo, cada vez que se hacen cambios en la API se considera que son compatibles con la versiones anteriores.

Ahora bien, FLOW considera los siguientes cambios como compatibles con versiones anteriores:

• Añadir nuevos servicios
• Añadir nuevos parámetros opcionales a servicios existentes
• Añadir nuevas propiedades a respuestas de servicios existentes
• Modificar el orden de las propiedades en respuestas existentes

Debido a lo anterior es que instamos a nuestros clientes a que consideren estos aspectos en sus integraciones, para evitar inconvenientes con nuevas versiones.

Para más información en relación a los cambios pueden revisar el API changelog y suscribirse a nuestra lista de correos para enterarse de anuncios de la API.

SI tienes una cuenta en Flow, puedes acceder al API REST mediante los siguientes endpoints:

El endpoint de Producción proporciona acceso directo para generar transacciones reales. El endpoint Sandbox permite probar su integración sin afectar los datos reales.

El API soporta como método de autenticación el APIKey y como seguridad, los datos que usted envíe siempre deberían estar firmado con su SecretKey. De esta forma, Flow verifica que los datos enviados le pertenecen y que no fueron adulterados durante la transmisión de red. Además, los datos viajan encriptados con un canal seguro mediante SSL.

Tanto su ApiKey como su SecretKey se obtienen desde su cuenta de Flow:

Se deben firmar todos los parámetros menos el parámetro s que es donde va la firma. Primero se deben ordenar los parámetros de forma alfabética ascendente en base al nombre del parámetro.

Una vez ordenados, se deben concatenar en un string los parámetros de la siguiente forma:

Nombre_del_parametro valor nombre_del_parametro valor.

Ejemplo:

Si sus parámetros son:

• "apiKey" = "XXXX-XXXX-XXXX"
• "currency" = "CLP"
• "amount" = 5000

El string ordenado para firmar deberia ser:

"amount5000apiKeyXXXX-XXXX-XXXXcurrencyCLP"

El string concatenado se debe firmar con la función hmac utilizando el algoritmo sha256 y su secretKey como llave.

Ejemplo PHP

Ordenando los parámetros:

$params = array( 
  "apiKey" => "1F90971E-8276-4715-97FF-2BLG5030EE3B,
  "token" = "AJ089FF5467367"
); 
$keys = array_keys($params);
sort($keys);

Concatenando:

$toSign = "";
foreach($keys as $key) {
  $toSign .= $key . $params[$key];
};

Firmando:

$signature = hash_hmac('sha256', $toSign , $secretKey);

Ejemplos de firmado:

PHP:

$sign = hash_hmac('sha256', $string_to_sign, $secretKey);

Java:

String sign = hmacSHA256(secretKey, string_to_sign);

Ruby:

OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'),secret_key,string_to_sign);

Javascript:

var sign = CryptoJS.HmacSHA256(stringToSign, secretKey);

Una vez obtenida la firma de los parámetros, agregue al resto de los parámetros el parámetro s con el valor del hash obtenido en el proceso de firma.

Ejemplo PHP:

$url = 'https://www.flow.cl/api';
// Agrega a la url el servicio a consumir
$url = $url . '/payment/getStatus';
// agrega la firma a los parámetros
$params["s"] = $signature;
//Codifica los parámetros en formato URL y los agrega a la URL
$url = $url . "?" . http_build_query($params);
try {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    $response = curl_exec($ch);
    if($response === false) {
      $error = curl_error($ch);
      throw new Exception($error, 1);
    } 
    $info = curl_getinfo($ch);
    if(!in_array($info['http_code'], array('200', '400', '401')) {
      throw new Exception('Unexpected error occurred. HTTP_CODE: '.$info['http_code'] , $info['http_code']);
    }
    echo $response;
    } catch (Exception $e) {
      echo 'Error: ' . $e->getCode() . ' - ' . $e->getMessage();
    }

Una vez obtenida la firma de los parámetros, agregue al resto de los parámetros el parámetro s con el valor del hash obtenido en el proceso de firma.

Ejemplo PHP:

$url = 'https://www.flow.cl/api';
// Agrega a la url el servicio a consumir
$url = $url . '/payment/create';
//Agrega la firma a los parámetros
$params["s"] = $signature;
try {
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
  curl_setopt($ch, CURLOPT_POST, TRUE);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
  $response = curl_exec($ch);
  if($response === false) {
    $error = curl_error($ch);
    throw new Exception($error, 1);
  } 
  $info = curl_getinfo($ch);
  if(!in_array($info['http_code'], array('200', '400', '401')) {
    throw new Exception('Unexpected error occurred. HTTP_CODE: '.$info['http_code'] , $info['http_code']);
  }
  echo $response;
} catch (Exception $e) {
  echo 'Error: ' . $e->getCode() . ' - ' . $e->getMessage();
}

Para todas las transaciones asíncronas Flow envía a su comercio notificaciones a sus páginas de callback, por medio de request via POST, content-type: application/x-www-form-urlencoded, enviando como parámetro un token, con este token el comercio debe invocar el servicio correspondiente que responde con los datos. Por ejemplo: Para crear un pago, en el servicio payment/create el comercio envía como uno de los parámetros urlConfirmation, que corresponde a la url donde Flow notificará el estado del pago. En esta página, el comercio recibirá el token y deberá invocar el servicio payment/getStatus para obtener el resultado del pago.

Transacciones asíncronas:

Al utilizar los servicios extendidos payment/getStatusExtended y payment/getStatusByFlowOrderExtended se puede obtener la información de error en el último intento de pago. Los códigos existentes son:

Todos los servicios cuyo resultado son listas Flow entrega los resultados paginados. La cantidad de registros por página y la navegación por las distintas páginas se controlan con los siguientes parámetros:

Todos los servicios de paginación retornan un objeto JSON con los siguientes datos:

{
  "total": número de registros totales,
  "hasMore": 1 Si hay más páginas, 0 si no hay,
  "data": [{}] arreglo con los registros
}

Para recorrer las páginas, si como resultado hasMore es 1, entonces suma el valor del parámetro limit al parámetro start y vuelve a invocar el servicio hasta que hasMore retorne 0

Disponemos de los siguientes clientes API Rest que facilitan la integración con Flow:

Disponemos de Collections de Postman para probar el consumo de los distintos servicios del API. Estas colecciones están agrupadas por funcionalidades y vienen con el algoritmo de firmado pre-programado.

¿Que es Postman? Postman es una herramienta que permite crear peticiones sobre APIs de una forma muy sencilla y poder, de esta manera, probar las APIs

Puede descargar Postman aquí: Postman download

Para utilizarlos, deberá crear Environment con las siguientes variables de ambiente:

• apiKey: apiKey obtenida de su cuenta Flow
• secretKey: secretKey obtenida de su cuenta Flow
• Hosting: sandbox.flow.cl para ambiente sandbox o www.flow.cl para ambiente productivo.

Puede descargar los archivos Collections para Postman aquí:

Puede realizar pruebas en nuestro ambiente Sandbox para los distintos medios de pagos.

Tarjetas de prueba Chile

En la simulación del banco usar:

Para los medios de pago:

• Servipag
• Multicaja
• Mach
• Cryptocompra

Se presentan simuladores de pago, donde sólo debe hacer clic en el botón aceptar.

Tarjetas de prueba Perú y México

Creación de transacciones de pagos y cobros por email. Utilice el servicio payment/create para crear links de pagos o payment/createEmail para crear cobros por email.

Permite generar reembolsos y obtener el estado de estos.

Permite crear clientes para efectuarles cargos recurrentes o suscribirlos a un planes de suscripción. Una vez creado un cliente, Flow lo identificará por un hash denominado customerId, ejemplo:

customerId: cus_onoolldvec

Permite crear planes de suscripción