Cajita de Pagos Payphone

📎¿Qué es la cajita de pagos de Payphone?

La Cajita de Pagos de Payphone es una solución de pago digital diseñada para facilitar transacciones seguras y ágiles entre negocios y clientes. Esta herramienta permite aceptar pagos con tarjetas de crédito y débito (Visa y MasterCard) y con saldo Payphone, brindando una experiencia de pago versátil y práctica para cualquier tipo de negocio o proyecto en línea.

Desde e-commerce hasta freelancers o pequeños emprendimientos, cualquier negocio puede beneficiarse de esta solución.

Payphone transforma los cobros en un proceso fácil de implementar utilizando tecnologías como HTML y JavaScript, solicitudes POST, ideales para integrar en páginas web de forma rápida y sin complicaciones. ¡En pocos minutos puedes activar una pasarela de pago funcional y confiable!

¿Listo para comenzar?

Flujo de cajita de pagos 💳 Payphone

La Cajita de Pagos de Payphone es una solución ágil y segura para integrar pagos en línea directamente en tu sitio web. Con esta herramienta, tus clientes podrán pagar con tarjetas Visa, MasterCard o saldo Payphone, sin salir de tu página.

🚀¿Cómo funciona? La integración se realiza en dos fases clave:

1. 🧩 Preparación

En esta etapa se incorpora el botón de pago a tu sitio utilizando los recursos proporcionados por Payphone:

1. Script JS, fuente CSS y etiqueta HTML.
2. Permite que controles totalmente las acciones de pago, registrando los montos, impuestos y demás detalles de la transacción.
3. Acepta pagos con tarjetas Visa, MasterCard, o saldo Payphone, brindando una experiencia de pago completa y flexible.

2. ✅ Confirmación

Una vez que el usuario completa el pago, Payphone redirige a tu sitio con parámetros en la URL que representan el resultado de la operación.

Tu sistema debe:

1. Capturar los parámetros de respuesta.
2. Realizar una solicitud POST a la API de Confirmación de Payphone.
3. Obtener el detalle completo de la transacción (estado, monto, autorización, etc.)

🔙 Importante: Reverso Automático

Si tu sistema no ejecuta la fase de confirmación dentro de los primeros 5 minutos después del pago, Payphone reversará automáticamente la transacción. Esto se hace para proteger tanto al comercio como al cliente, evitando:

• Cobros indebidos
• Procesos incompletos por falta de datos
• Conflictos o reclamos por parte del cliente

📖 En resumen: Si no confirmas el pago, Payphone lo cancela automáticamente, ya que no puede garantizar que el comercio haya registrado correctamente la transacción.

⚠️ Consideraciones previas:

Antes de comenzar con la implementación de la Cajita de Pagos de Payphone, asegúrate de cumplir con los siguientes requisitos técnicos y administrativos:

🌐 Plataforma

• La Cajita de Pagos está diseñada exclusivamente para entornos WEB. No está disponible para aplicaciones móviles directamente.

🔒 Dominio y entorno seguro

• Es indispensable contar con un dominio que tenga un certificado SSL (https://) válido para producción.
• Para fines de prueba o desarrollo local, puedes utilizar http://localhost sin necesidad de certificado SSL.
• Importante: La Cajita de Pagos está vinculada directamente al dominio configurado en tu cuenta Payphone.
• Esto significa que solo funcionará en ese dominio específico. Si se intenta ejecutar desde otro dominio no autorizado, se mostrará un error de autorización y el proceso de pago no podrá completarse.

🏢 Cuenta en Payphone Business

• Debes tener una cuenta activa en Payphone Business.
• Si aún no la tienes, puedes registrarte en: Payphone Business

👨💻 Usuario con rol de Desarrollador

• Dentro de tu cuenta Payphone Business, deberás crear un usuario con el rol de Desarrollador.
• Este usuario tendrá acceso a las configuraciones técnicas y a la generación de credenciales para integración.

💻 Entorno de desarrollo

• Asegúrate de contar con un entorno de desarrollo funcional, incluyendo:
• • Editor de código (VSCode, WebStorm, etc.)
  • Navegador actualizado
  • Herramientas de prueba como Postman, Insomnia o cURL
  • Conocimientos básicos de HTML, JavaScript y consumo de APIs REST

🔑 Obtención de credenciales

• Desde la plataforma para desarrolladores de Payphone, deberás:
• • Crear una nueva configuración de aplicación.
  • Obtener las credenciales necesarias para la integración: TOKEN de autenticación (Bearer Token) y STOREID asociado a tu comercio

Próximos pasos

En las siguientes secciones te guiaremos paso a paso para implementar correctamente cada una de estas fases, con ejemplos prácticos y buenas prácticas.

🔑Configuración del Ambiente y Obtención de Credenciales

🛠️Insertar cajita de pagos Payphone

La integración de la Cajita de Pagos en tu sitio web es rápida y sencilla. Solo necesitas agregar dos scripts, una fuente CSS, un fragmento de JavaScript de configuración, y un contenedor HTML donde aparecerá el botón de pago.

🧷 Agrega las dependencias en la cabecera de tu página

• payphone-payment-box.css: La hoja de estilos CSS aplica el diseño visual del botón de pago.
  
• payphone-payment-box.js: El SDK JavaScript habilita el control y la lógica de la Cajita.
  

<head>
      <link rel="stylesheet" href="https://cdn.payphonetodoesposible.com/box/v1.1/payphone-payment-box.css"> 
      <script type="module" src="https://cdn.payphonetodoesposible.com/box/v1.1/payphone-payment-box.js"></script> 
</head>

⚙️ Inserta el script de configuración

• Este script es el núcleo de la integración. Define los datos de la transacción, credenciales, impuestos, y comportamiento del formulario. Puedes colocarlo al final del <body> o también en el <head>
  

<script>
	//Cobro mixto: 1 USD con impuesto del 15% y 2 USD sin impuesto
       window.addEventListener('DOMContentLoaded',()=>{
            ppb = new PPaymentButtonBox({
                token: 'ACA TU TOKEN',	//credenciales de acceso
                clientTransactionId: 'ID_UNICO_X_TRANSACCION-001', 	
                amount: 315, 	// Valor total 
                amountWithoutTax: 200, 	
                amountWithTax:100, 	
                tax: 15,	
                service: 0,	
                tip:0,	
                currency: "USD",	
                storeId:"TU_STOREID", 
                reference:"Pago por venta Fact#001", 	   
                lang: "es", 
                defaultMethod:"card", // *Tarjeta = "card" - *Payphone = "payphone"
                timeZone: -5,   
                lat: "-1.831239",   
                lng: "-78.183406",  
                //Solo si se registran datos del titular de la tarjeta 
                phoneNumber:"+593999999999",
                email: "aloy@mail.com",
                documentId:"1234567890",
                identificationType: 1 //Tipo de identificación: *Cédula: 1 *RUC: 2 *Pasaporte: 3 *Por defecto 1.
            }).render('pp-button');
        })
</script>

📦 Inserta el contenedor del botón

• Debes agregar un contenedor <div id="pp-button"> en la ubicación donde desees que aparezca el botón de pago:
  

<div id="pp-button"></div>

amount = amountWithoutTax + amountWithTax  + tax + service + tip

📈 Ejemplo básico de configuración

A continuación, se muestran ejemplos de configuraciones con los campos mínimos para diferentes tipos de cobro:

<script>
	//Ejemplo de cobro de 1 USD con impuesto del 15%
       window.addEventListener('DOMContentLoaded',()=>{
            ppb = new PPaymentButtonBox({
                token: 'ACA TU TOKEN',	
                clientTransactionId: 'ID_UNICO_X_TRANSACCION-001', 	
                amount: 115, 	
                amountWithTax:100, 	
                tax: 15,	
                currency: "USD",	
                storeId:"TU_STOREID", 
                reference:"Pago por venta Fact#001" 	          
            }).render('pp-button');
        })
</script>

<script>
	//Ejemplo de cobro de 2 USD sin impuesto
       window.addEventListener('DOMContentLoaded',()=>{
            ppb = new PPaymentButtonBox({
                token: 'ACA TU TOKEN',	
                clientTransactionId: 'ID_UNICO_X_TRANSACCION-001', 	
                amount: 200, 	
                amountWithoutTax: 200, 	
                currency: "USD",	
                storeId:"TU_STOREID", 
                reference:"Pago por venta Fact#001" 	        
            }).render('pp-button');
        })
</script>

<script>
	//Ejemplo de un cobro mixto: 1 USD con impuesto del 15% y 2 USD sin impuesto
       window.addEventListener('DOMContentLoaded',()=>{
            ppb = new PPaymentButtonBox({
                token: 'ACA TU TOKEN',	
                clientTransactionId: 'ID_UNICO_X_TRANSACCION-001', 	
                amount: 315, 	
                amountWithoutTax: 200, 	
                amountWithTax:100, 	
                tax: 15,	
                currency: "USD",	
                storeId:"TU_STOREID", 
                reference:"Pago por venta Fact#001" 	         
            }).render('pp-button');
        })
</script>

🧾 Descripción de parámetros en la petición

A continuación se detallan todos los parámetros que se pueden usar para una transacción como montos a cobra, la moneda, datos del cliente y otros campos que necesites enviar.

🧱 Estructura final del código:

<!DOCTYPE html>
<html lang="es">
<head>
    <script src="https://cdn.payphonetodoesposible.com/box/v1.1/payphone-payment-box.js" type="module" ></script>
    <link href="https://cdn.payphonetodoesposible.com/box/v1.1/payphone-payment-box.css" rel="stylesheet" >
</head>
<body>
    <script>
       window.addEventListener('DOMContentLoaded',()=>{
            ppb = new PPaymentButtonBox({
                token: 'ACA TU TOKEN',	
                clientTransactionId: 'ID_UNICO_X_TRANSACCION-001', 	
                amount: 315, 	
                amountWithoutTax: 200, 	
                amountWithTax:100, 	
                tax: 15,	
                currency: "USD",	
                storeId:"TU_STOREID", 
                reference:"Pago por venta Fact#001" 	           
            }).render('pp-button');
        })
    </script>
    <div id="pp-button"></div>
</body>
</html>

Una vez terminada la configuración de tu página con los campos requeridos se mostrara la cajita de pagos de la siguiente forma:

📌 Consideraciones

⏱️ Tiempo de vida del formulario

• Cada formulario de la Cajita de Pagos tiene una vigencia de 10 minutos desde su carga.
  
• Si el usuario no completa el pago en ese tiempo, el formulario expirará y se deberá generar uno nuevo.
  

🚫 Error de "Acceso denegado" en Cajita de Pagos

¿Por qué ocurre este error?

El mensaje de “Acceso denegado o dominio no permitido” al intentar cargar o ejecutar la Cajita de Pagos puede deberse a una de las siguientes razones:

1. 🌐 Dominio no autorizado

• La Cajita de Pagos solo funciona en el dominio registrado en tu configuración de desarrollador en Payphone Developer.
• Si intentas ejecutarla desde otro dominio o mediante una redirección no autorizada, se bloqueará por motivos de seguridad.
  
• ✅ Solución: Asegúrate de que la redirección hacia el formulario de pago se realice desde el mismo dominio que configuraste en tu cuenta de Payphone.

2. 🛡️ Falta de identidad del sitio (Referrer-Policy)

En algunos frameworks o servidores, existe una configuración por defecto que no comparte la identidad del sitio web desde donde se hace la redirección al formulario de pago.

Esto impide que Payphone verifique el origen de la solicitud y provoca el error de acceso denegado.

La configuración detectada que puede causar el error: ‍

• Referrer-Policy: en las plataformas mas comunes como C# / ASP.NET, WordPress, entre otras
• SECURE_REFERRER_POLICY: Desde Django 3.1 en adelante
  

📘 ¿Qué es la Referrer-Policy?

La Referrer-Policy es una política de seguridad del navegador que define qué información del origen (referencia) se envía al hacer peticiones a otros recursos.‍

A continuación, se muestran las opciones más comunes:‍

• no-referrer: No se envía ninguna referencia. Máxima privacidad, pero puede romper funcionalidades.
  
• no-referrer-when-downgrade: Envía la referencia solo si ambos sitios usan HTTPS.
  
• origin: Envía solo el esquema y host del sitio (sin ruta). Nivel medio de privacidad.
  
• origin-when-cross-origin: Como origin, pero solo en solicitudes entre sitios distintos.
  
• strict-origin: Similar a origin, pero restringido a HTTPS..
  
• strict-origin-when-cross-origin: Mayor control sobre envíos entre orígenes cruzados.
  
• no-referrer: No se envía ninguna referencia. Máxima privacidad, pero puede romper funcionalidades.
  

✅ Recomendación de Payphone

Para garantizar el correcto funcionamiento de la Cajita de Pagos, recomendamos usar:‍

• origin
• origin-when-cross-origin

Esto proporciona el equilibrio ideal entre funcionalidad y privacidad, y permite a Payphone validar correctamente el origen de la solicitud.

🧾Consultar respuesta de la transacción

Una vez que el usuario completa el pago, será redirigido automáticamente a la URL de respuesta que hayas configurado previamente en la plataforma de Payphone.

Esta URL incluirá dos parámetros esenciales en la cadena:

• id Número entero que representa el identificador único de la transacción generado por Payphone.
• clientTransactionId Cadena de texto definida como identificador unico por tu plataforma al iniciar el pago.

Es crucial capturar estos parámetros para poder realizar una solicitud POST al método Confirm.

🔸 Ejemplo en PHP para obtener los parámetros de la URL:

$id = isset($_GET["id"])?$_GET["id"]:0;
$clientTransactionId = isset($_GET["clientTransactionId"])?$_GET["clientTransactionId"]:"";

✔️Confirmar el Estado de la Transacción API Buttom/Confirm :

Para verificar si una transacción fue aprobada, cancelada o fallida, debes realizar una solicitud al endpoint de confirmación.

Esto te permitirá mostrar un mensaje claro al usuario sobre el resultado.

🔗Endpoint del API Confirm

https://pay.payphonetodoesposible.com/api/button/V2/Confirm

📦 Cuerpo de la solicitud (JSON):

El cuerpo de la solicitud debe ser un objeto JSON que contenga los siguientes parámetros, los cuales son los valores que se recibió de la URL de respuesta:

{
  "id": 0,
  "clientTxId": "string"
}

🔐 Es fundamental incluir las siguientes cabeceras en la solicitud:

• Authorization: bearer TU_TOKEN (Esta cabecera debe contener el token de autenticación de tu aplicación, precedido por la palabra “Bearer”. Este token es el mismo que utilizaste al preparar la transacción inicialmente).
• Content-type: application/json (Indica que el formato de los datos enviados en el cuerpo de la solicitud es JSON).

📬Respuesta satisfactoria de solicitud POST

Si la solicitud es correcta, recibirás un objeto JSON con el detalle de la transacción. Los parámetros recibidos son:

{
    "email": "aloy@mail.com",
    "cardType": "Credit",
    "bin": "530219",
    "lastDigits": "XX17",
    "deferredCode": "00000000",
    "deferred": false,
    "cardBrandCode": "51",
    "cardBrand": "Mastercard Produbanco/Promerica",
    "amount": 315,
    "clientTransactionId": "ID_UNICO_X_TRANSACCION-001",
    "phoneNumber": "593999999999",
    "statusCode": 3,
    "transactionStatus": "Approved",
    "authorizationCode": "W23178284",
    "message": null,
    "messageCode": 0,
    "transactionId": 23178284,
    "document": "1234567890",
    "currency": "USD",
    "optionalParameter3": "Descripción Extra",
    "optionalParameter4": "ELISABETH SOBECK",
    "storeName": "Tienda Payphone",
    "date": "2023-10-10T11:57:26.367",
    "regionIso": "EC",
    "transactionType": "Classic",
    "reference": "Pago por venta Fact#001"
}

📝Descripción de parámetros de respuesta

Una vez la llamada es satisfactoria obtendrás un JSON con los siguientes parámetros:

📬Respuesta con error de solicitud POST

Si la solicitud contiene algún error, recibirás un objeto JSON con el detalle del error. Los parámetros recibidos son:

{
    "message": "La transacción no existe, verifique que el identificador enviado sea correcto.",
    "errorCode": 20
}

🔙 Importante Recordar: Reverso Automático

Si tu sistema no ejecuta la fase de confirmación dentro de los primeros 5 minutos después del pago, Payphone reversará automáticamente la transacción. Esto se hace para proteger tanto al comercio como al cliente, evitando:

• Cobros indebidos
• Procesos incompletos por falta de datos
• Conflictos o reclamos por parte del cliente

📖 En resumen: Si no confirmas el pago, Payphone lo cancela automáticamente, ya que no puede garantizar que el comercio haya registrado correctamente la transacción.

🧱 Ejemplo de Implementación API Buttom/Confirm

A continuación, se presenta varios ejemplos de cómo realizar solicitudes POST:

<?php
    //Obtener parametros enviados por payphone de la URL de respuesta
    $id = isset($_GET["id"])?$_GET["id"]:0;
    $clientTxId = isset($_GET["clientTransactionId"])?$_GET["clientTransactionId"]:"";

    //Preparar cabecera para la solicitud
    $headers[] = 'Authorization: Bearer your_token' ;//CREDENCIALES DE CONFIGURACION
    $headers[] = 'Content-Type: application/json' ;//TIPO DE APLICACION 

    //Preparar objeto JSON para solicitud
    $data = array(
        "id" => (int)$id,
        "clientTxId" => $clientTxId 
    );
    $objetoJSON = json_encode($data);

    //Iniciar solicitud curl: POST 
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, "https://pay.payphonetodoesposible.com/api/button/V2/Confirm");
    curl_setopt($curl, CURLOPT_POST, 1);

    curl_setopt($curl, CURLOPT_POSTFIELDS, $objetoJSON);    
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    //Respuesta en formato JSON
    $curl_response = curl_exec($curl);
    //Finaliza solicitud curl: POST
    curl_close($curl);


    //Mostrar Resultado en Pantalla
    echo "<h1>Prueba Confirmacion de Transaccion</h1> <br>";

    $result= json_decode($curl_response);
    echo "Respuesta : <pre>".json_encode($result,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
?>

<html lang="es">
    <head>
        <meta charset="utf-8">
        <title>Confirmacion con jQuery</title>
        <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>   
        <script>
            //---------Funcion que obtiene parametros de la url---------//
            function getQueryVariable(variable) {
                var query = window.location.search.substring(1);
                var vars = query.split("&");
                for (var i=0; i < vars.length; i++) {
                    var pair = vars[i].split("=");
                    if(pair[0] == variable) {
                        return pair[1];
                    }
                }
                return false;
            } 

            var id=getQueryVariable('id');
            var clientTxId=getQueryVariable('clientTransactionId');

            $(document).ready(function() {
                $.ajax({
                    url: "https://pay.payphonetodoesposible.com/api/button/V2/Confirm",
                    type: "POST",
                    headers: {
                    "Content-Type": "application/json",
                    "Authorization": "Bearer your_token"
                    },
                    data: JSON.stringify({ 
                        "id": id,
                        "clientTxId": clientTxId
                    }),
                    success: function(response) {
                        $("#resultado").html(
                            "Respuesta : <pre>" + JSON.stringify(response, null, 2) + "</pre>"
                        );
                    },
                    error: function(error) {
                        $("#resultado").html(
                            "Error en la solicitud : <pre>" + JSON.stringify(error, null, 2) + "</pre>"
                        );
                    }
                });
            });
        </script>
    </head>    
    <body>
        <h1>Ejemplo de Solicitud POST con jQuery</h1>
        <div id="resultado"></div>
    
    </body>
</html>

<html lang="es">
    <head>
        <meta charset="utf-8">
        <title>Confirmacion con Fetch</title> 
        <script>
            //---------Funcion que obtiene parametros de la url---------//
            function getQueryVariable(variable) {
                var query = window.location.search.substring(1);
                var vars = query.split("&");
                for (var i=0; i < vars.length; i++) {
                    var pair = vars[i].split("=");
                    if(pair[0] == variable) {
                        return pair[1];
                    }
                }
                return "0";
            } 

            const id=getQueryVariable('id');
            const clientTxId=getQueryVariable('clientTransactionId');

            const  headers = {
                "Content-Type": "application/json",
                "Authorization": "Bearer your_token",
                "Referer": document.referrer
            };

            const bodyJSON = { 
                "id": id,
                "clientTxId": clientTxId
            };

            const  url = "https://pay.payphonetodoesposible.com/api/button/V2/Confirm";

            fetch(url, {
                method: "POST",
                headers: headers,
                body: JSON.stringify(bodyJSON)
            })
            .then((res) => res.json())
            .catch((error) => {
                // Creamos la etiqueta <pre> que contiene el error
                const jsonResult = document.createElement("pre");
                jsonResult.textContent = JSON.stringify(error, null, 2);

                // Agregar etiqueta <pre> al <div>
                const container = document.createElement("div");
                container.appendChild(jsonResult);

                // Agregar la respuesta al body del documento o a un contenedor específico
                document.body.appendChild(container);
            })
            .then((data) => {

                // Creamos las etiquetas <a>
                const jsonResult = document.createElement("pre");
                jsonResult.textContent = JSON.stringify(data, null, 2);

                // Mostrar los enlaces en el documento con un salto de línea entre ellos
                const container = document.createElement("div");
                container.appendChild(jsonResult);

                // Agregar los enlaces al body del documento o a un contenedor específico
                document.body.appendChild(container);
            });  
        </script>
    </head>    
    <body>
        <h1>Confirmacion de Transaccion con Fetch</h1>   
    </body>
</html>

¡Listo! Si llegaste hasta aquí, ya tienes la lógica principal implementada. En la siguiente sección del manual podrás ver cómo hacer pruebas con datos simulados y pasar a producción.

🎞️Video Tutorial

Aprende a integrar la Cajita de Pago de Payphone en minutos con nuestro video explicativo.

🔰Pruebas y paso a producción

Una vez que tu aplicación esté en producción, el proceso estará completo.
¡Felicidades por integrar cajita de pagos de Payphone!

↩️Reverso de Transacciones

🔧Funcionalidades Adicionales