▷ Botón de pagos - Pasarela de pagos - API2Datafast

Manual de Integración del Botón de Pagos para Desarrolladores Versión 1.1

PayAgile le permite conectarse a través de lenguaje HTML y APIREST a la funcionalidad del botón. Para la integración se describe los siguientes procesos:

Se debe enviar mediante APIREST lo siguientes datos:

Tipo: GET
Url de envío: https://portal.botonpagos.com/api/datafast/setOrder
1.1 Parámetros Obligatorios:
1.1.1 Código del Establecimiento	code => texto (30) (Se envía como cabecera de la petición y este código es proporcionado por Botón Pagos)
1.1.2 Primer Nombre del Comprador	first_name => texto (30)
1.1.4 Apellidos del Comprador	last_name => texto (30)
1.1.5 Documento del Identidad del Comprador	document => texto (30)
1.1.6 Teléfono del Comprador	phone => texto (100)
1.1.7 Email del Comprador	email => texto (100)
1.1.8 Dirección del Comprador	address => texto (200)
1.1.9 Dirección IP del Comprador	ip_address => texto (30)
1.1.10 ID de la Orden	order_id => texto (30)
1.1.11 Total de la Orden	total => double (10,2)
1.1.12 Subtotal IVA 0	subtotal0 => double (10,2)
1.1.13 Subtotal IVA 12	subtotal12 => double (10,2)
1.1.14 Impuestos	tax => double (10,2)
1.1.15 Costo de envío sin IVA	shipping => double (10,2)
1.1.16 Costo de Impuesto de Envío	shipping_tax => double(10,2)
1.1.17 Productos (Enviar en formato Json)	products => array ( 0 => array ( id => texto (30) nombre => texto (100) isbn => texto (45) (Opcional) sku => texto (45) (Opcional) subtotal => double (10,2) tax => double (10,2) total => double (10,2) cantidad => int ) )
1.1.18 Estado de la Orden	status => text (30) Posibles opciones: – on-hold – processing – completed – cancelled – pending
1.1.19 Dirección de Retorno de la Transacción (Solo en páginas o sistemas web, no válido para app movil)	url_response => texto (200)
RECURRENCIAS
1.1.20 Si la orden es recurrente	recurrent => boolean(o entero 1)
1.1.21 Periodo de la recurrencia en días	recurrent_period => int Con la siguiente tabla: 1 => Diario 2 => Semanal 3 => Quincenal 4 => Mensual 5=> Bimensual 6 => Trimestral 7 => Semestral 8 => Anual
1.1.22 Número de cuotas que se van a cobrar en la recurrencia (opcional)	recurrent_cuotas => int (0 es sin límite)
1.1.23 Día específico de cobro si el periodo de la recurrencia es mayor a 4 (Opcional)	recurrent_day => int
1.2 Parámetros Opcionales:
1.2.1 Teléfono Celular del Comprador	cellphone => texto (100)
1.2.2 Cupones (Enviar en formato Json)	coupons => array ( [ code => texto (30) (Código del Cupón) amount => double (10,2) (Monto de descuento) ] )

Ejemplo de uso con PHP

<?php
//Obtengo lo valores totales de la orden
//Subtotal 0 es la suma de los subtototales de los productos que no gravan IVA
$subtotal_order_0 = number_format(0, 2, '.', '');
//Subtotal 0 es la suma de los subtototales de los productos que si gravan IVA + el valor del Envio (si aplica)
$subtotal_order_12 = number_format(8.93, 2, '.', '');
//Tax es el valor del impuesto a partir del Subtotal
$tax_order = number_format($subtotal_order_12*0.12, 2, '.', '');
//Total es la suma del Subtotal + Tax
$total_order = number_format($subtotal_order_0+$subtotal_order_12+$tax_order, 2, '.', '');

//Armo los productos de mi orden
//ID del Producto en la Tienda
$products[0]['id'] = 01;
//Nombre del Producto
$products[0]['nombre'] = 'Nombre del Producto';
//Valor sin TAX del producto
$products[0]['subtotal'] = 8.93;
// Impuesto del producto
$products[0]['tax'] = 1.07;
//Valor total del producto
$products[0]['total'] = 10.00;
//Cantidad del producto
$products[0]['cantidad'] = 1;

//Id de la orden interna de la tienda puede ser alfajumérico
$order = "001";

//Armo el array a enviar
$datos = array(
        'products' => json_encode($products),
        'total' => $total_order,
        'tax' => $tax_order,
        'subtotal12' => $subtotal_order_12,
        'subtotal0' => $subtotal_order_0, //Subtotal de los productos que no gravan IVA
        'email' => "[email protected]",
        'first_name' => "Primer Nombre Cliente"
        'last_name' => "Apellidos Cliente",
        'document' => "1717272354", //Cédulo o RUC del cliente
        'phone' => "2238930",//Teléfono del cliente
        'address' => "Dirección del cliente",
        'ip_address' => get_client_ip(),//Función con la IP del cliente
        'order_id' => $order,
        'shipping' => 1.00, //Valor del envío sin impuestos
        'shipping_tax' => 0.12,//Valor del impuesto del envío, si existe valor de envío el impuesto es obligatorio por los Bancos
        'gateway' => 'botonpagos',
        'status' => 'pending',
        'date' => date('Y-m-d'),
        'url_response' => 'https://prueba.com/resultado.php?order='.$order //Este campo es opcional en el caso de APPS Móviles
    );

//Dirección a BotónPagos con los datos de la orden
$url = 'https://portal.botonpagos.com/api/datafast/setOrder?'.http_build_query($datos);
//Consulta vía CURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'code: ID del comercio'//ID provisto por BotónPagos
));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$responseData = curl_exec($ch);
//Si existe un error de conexión
if(curl_error($ch)){
    echo curl_error($ch);
}

curl_close($ch);
//Paso a array los datos obtenidos en Json
$responseData = json_decode($responseData, true);

/**
 * Función que permite obtener la ip del cliente que realiza el pago
 * 
 * */
function get_client_ip() 
{
    $ipaddress = "";
    if (getenv("HTTP_CLIENT_IP"))
        $ipaddress = getenv("HTTP_CLIENT_IP");
    else if(getenv("HTTP_X_FORWARDED_FOR"))
        $ipaddress = getenv("HTTP_X_FORWARDED_FOR");
    else if(getenv("HTTP_X_FORWARDED"))
        $ipaddress = getenv("HTTP_X_FORWARDED");
    else if(getenv("HTTP_FORWARDED_FOR"))
        $ipaddress = getenv("HTTP_FORWARDED_FOR");
    else if(getenv("HTTP_FORWARDED"))
       $ipaddress = getenv("HTTP_FORWARDED");
    else if(getenv("REMOTE_ADDR"))
        $ipaddress = getenv("REMOTE_ADDR");
    else
        $ipaddress = "UNKNOWN";
    return $ipaddress;
}


?>
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>PayAgile</title>
  </head>
  
  <body>
     
    <div class="container">
      <div class="row">
        <div class="col-md-8 order-md-1">
            <!-- Llamo al Botón de Pagos en mi página -->
            <iframe src="https://portal.botonpagos.com/api/datafast/botonV3/<?= $responseData['code'] ?>" width="100%" style="height: 766px; border: none;"></iframe>
        </div>
      </div>
    </div>
  </body>
</html>

2. Crear el Iframe del Botón

Como resultado del paso anterior se obtiene un objeto json con código de error en caso de que no se haya podido procesar los datos enviados. (Recordar que para procesar como el ejemplo es necesario convertir el objeto json en array).

La variable $responseData[‘error_code’] será igual a 1 si existe un error y la descripción del error estará contenida en la variable $responseData[‘error_description’]

En caso de que no existe un error se puede implementar el iframe con la ruta + el código devuelto del anterior paso y está contenido en la variable $responseData[‘code’]

El iframe quedaría de la siguiente manera:
<iframe src=»https://portal.botonpagos.com/api/datafast/botonV3/<?= $responseData[‘code’] ?>» width=»100%» style=»height: 766px; border: none;»></iframe>

El resultado debería ser el siguiente:

3. Una vez que el cliente presiona Pagar la página se redirecciona a la url_response enviada en el primer paso.

Luego se procede a llamar al APIREST siguiente:

<?php
$url = "https://portal.botonpagos.com/api/datafast/tienda/getOrder/".$code."/".$order;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$responseData = curl_exec($ch);

if(curl_error($ch)){
    echo curl_error($ch);
}

curl_close($ch);

$responseData = json_decode($responseData, true);
?>
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>PayAgile</title>
  </head>
  <body class="bg-light">
    <div class="container">
      <div class="row">
            <div class="col-md-8 order-md-1">
                <?php if($responseData ["error_code"]): ?>
                <div class="alert alert-warning" role="alert">
                  Error en el pago: <?= $responseData ["error_description"] ?>
                </div>
                <?php else: ?>
                <div class="alert alert-success" role="alert">
                  Pago completado con éxito. Un correo fue generado.
                </div>
                <?php endif; ?>
            </div>    
          </div>
        </div>
    </body>
</html>

Tipo: GET
URL de envío:
https://portal.botonpagos.com/api/datafast/tienda/getOrder/».$code.»/».$order

En donde se tiene 2 variables:

code => es el código del establecimiento
order => código de la orden de la tienda (order_id enviado en el primer paso)

Como resultado de la consulta se obtiene un Objeto que tiene los siguientes elementos:

$responseData ["error_code"]	=> es 1 si existe un error en la transacción
$responseData ["error_description"]	=> descripción del error
$response ["id"]	=> id de la transacción
$response ["resultDetails"]["AuthCode"]	=> código de autorización
$response ["resultDetails"]["ReferenceNbr"]	=> número de referencia
$response ["resultDetails"]["AcquirerResponse"]	=> respuesta del banco
response ["recurring"]["numberOfInstallments"]	=> número de meses diferidos
$response["customParameters"]["SHOPPER_interes"]	=> si es con interés la operación
$response["customParameters"]["SHOPPER_gracia"]	=> si tiene meses de gracia
$response["paymentBrand"]	=> tipo de tarjeta
$response["card"]["bin"]	=> entidad bancaria
$response["card"]["binCountry"]	=> país de la entidad bancaria
$response["card"]["holder"]	=> dueño de la tarjeta
$response["cart"]	=> detalle de producto
$response["subtotal"]	=> subtotal de la orden
$response["tax"]	=> impuesto
$response["total"]	=> total de la orden

Con eso se termina el proceso de implementación del botón de pagos.