Saltar al contenido

Manual de Integración

Manual de Integración del Botón de Pagos para Desarrolladores Versión 1.1
BotónPagos 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:

  1. 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.3 Segundo Nombre del Comprador second_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 => 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",
        'second_name' => "Segundo 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' => 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>BotónPagos</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/boton/<?= $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/boton/<?= $responseData[‘code’] ?>” width=”100%” style=”height: 766px; border: none;”></iframe>

El resultado debería ser el siguiente:

PayAgile
3. Una vez que el cliente presiona Pagar la página se redirecciona a la url_response enviada en el primer paso y esta contiene la variable de tipo get $_GET[“id”] que identifica la operación.
Con dicha variable se debe proceder a consultar el estado de la operación realizada mediante el APIREST siguiente:

<?php
$url = "https://portal.botonpagos.com/api/datafast/tienda/checkPayment/5eed292e12e42/".$_GET['order']."/".$_GET['id'];

$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>BotónPagos</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:
Url en caso de sistemas o páginas web:
https://portal.botonpagos.com/api/datafast/tienda/checkPayment/”.$code.”/”.$order.”/”.$id

Url en caso de App móviles:
https://portal.botonpagos.com/api/datafast/tienda/getOrder/”.$code.”/”.$order

En donde se tiene 3 variables:

  1. code => es el código del establecimiento
  2. order => código de la orden de la tienda (order_id enviado en el primer paso)
  3. id => $_GET[“id”] (Solo para sistemas o páginas web)
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
Con eso se termina el proceso de implementación del botón de pagos.