Cajita de pagos payphone

¿Qué es la cajita de pagos de payphone?

La cajita de pagos de payphone brinda a tus clientes la flexibilidad de pagar como prefieran. Aceptamos tarjetas de crédito, débito y saldo payphone en una solución única, segura y confiable. ¡Simplifica tus procesos de pago y aumenta tus ventas de forma efectiva!

Sigue nuestro tutorial y, en pocos minutos, tendrás tu pasarela de pago activa y lista para usar. La Cajita utiliza HTML y JavaScript, permitiéndote recibir pagos con tarjetas Visa y MasterCard, así como con saldo payphone.

¡Facilita las transacciones y mejora la experiencia de tus usuarios con payphone!

¿Cómo recibir pagos con payphone?

Impulsa tus ventas con payphone. Sigue estos simples pasos:

  1. Integra payphone a tu sitio: Copia y pega nuestro código en tu página web. ¡Es rápido y sencillo!
  2. Configura la transacción: Define el precio, impuestos y cualquier detalle adicional.
  3. Realizar el pago: El cliente podrá pagar utilizando su tarjeta de crédito, débito, o saldo de payphone.
  4. Consultar el resultado de la transacción: payphone enviará parámetros a la URL de tu servidor, lo que te permitirá verificar el estado de la transacción de manera eficiente.

Configuración del ambiente

Credenciales de Autenticación (Token, StoreID)


Para comenzar a utilizar payphone y recibir pagos de forma segura, es fundamental que configures tu ambiente de desarrollo. En esta sección encontrarás todos los pasos necesarios para obtener las credenciales y realizar la integración correctamente.  
Asegúrate de seguir todos los pasos antes de continuar. Clic sobre el botón.


Configuración de Ambiente y Obtención de Credenciales


NOTA: Recuerda que sin esta configuración, no podrás procesar pagos a través de nuestra plataforma.

Insertar cajita de pagos payphone

Insertar la cajita de pagos en tu sitio web es muy sencillo, debes agregar dos scripts, una fuente CSS y un tag html para que la cajita de pagos aparezca.

Agrega las siguiente etiquetas en la cabecera en tu página web

  • La referencia a la hoja de estilos CSS: payphone-payment-box.css
  • La referencia el SDK JavaScript: payphone-payment-box.js
<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>
  • El segundo script es el que te permitirá controlar las acciones de petición y configuración de la cajita, lo puedes insertar en el cuerpo o en la cabecera de tu pagina.
<script>
	//Ejemplo completo 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',	//credenciales de acceso, se genera en payphone developer
                //Identificador único asignado por el comercio a cada transacción para su seguimiento.
                clientTransactionId: 'ID_UNICO_X_TRANSACCION-001', 	
                amount: 315, 	// Valor total de la factura a cobrar
                amountWithoutTax: 200, 	//Monto que no está sujeto a impuestos.
                amountWithTax:100, 	//Monto que incluye el valor sujeto a impuestos, excluyendo el propio impuesto.
                tax: 15,	//Monto del impuesto aplicado a la transacción.
                service: 0,	//Monto asociado al servicio proporcionado.
                tip:0,	//Monto de la propina otorgada por el cliente.
                currency: "USD",	//Código de moneda ISO 4217. (ej:USD)
                storeId:"TU_STOREID", //Identificador único asignado a la transacción para su seguimiento.
                reference:"Pago por venta Fact#001", 	//Motivo o referencia específica del pago.   
                lang: "es", //Idioma de Formulario
                defaultMethod:"card", //El método por defecto a mostrar: *Tarjeta = "card" *Payphone = "payphone"
                timeZone: -5,   //Zona horaria
                lat: "-1.831239",   //latitud en formato decimal
                lng: "-78.183406",  //longitud en formato decimal
                //Se usan solo si se registran datos del titular de la tarjeta 
                phoneNumber:"+593999999999",//Número de teléfono del titular; se solicitará si no se proporciona.
                email: "aloy@mail.com",//Correo electrónico del titular; se solicitará si no se proporciona.
                documentId:"1234567890",//Número de identificación del titular; se solicitará si no se proporciona.
                identificationType: 1 //Tipo de identificación: *Cédula: 1 *RUC: 2 *Pasaporte: 3 *Por defecto 1.
            }).render('pp-button');
        })
</script>
  • El tercer elemento que debes agregar es una etiqueta DIV que debes ubicar en la sección donde quieras que aparezca el botón de pago.
<div id="pp-button"></div>

Importante:


*Cálculo del amount:

Recuerda que el campo amount (valor a cobrar) debe ser la suma de los campos amountWithTax, amountWithoutTax, tax, service y tip.

amount = amountWithoutTax + amountWithTax  + tax + service + tip

Aunque los montos individuales son opcionales, al menos uno debe estar presente para respaldar el campo amount


*Valores Monetarios:

Todos los valores monetarios deben expresarse en enteros. Es decir, se multiplica el valor en dólares por 100. Por ejemplo:

$1 dólar = 100
$1.50 dólares = 150
$10 dólares = 1000
$12.68 dólares = 1268


Ejemplos de configuraciones basicas

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

Montos Con Impuestos
Montos Sin Impuestos
Montos Mixtos
<script>
	//Ejemplo de cobro de 1 USD con impuesto del 15%
       window.addEventListener('DOMContentLoaded',()=>{
            ppb = new PPaymentButtonBox({
                token: 'ACA TU TOKEN',	//credenciales de acceso, se genera en payphone developer
                //Identificador único asignado por el comercio a cada transacción para su seguimiento.
                clientTransactionId: 'ID_UNICO_X_TRANSACCION-001', 	
                amount: 115, 	// Valor total de la factura a cobrar
                amountWithTax:100, 	//Monto que incluye el valor sujeto a impuestos, excluyendo el propio impuesto.
                tax: 15,	//Monto del impuesto aplicado a la transacción.
                currency: "USD",	//Código de moneda ISO 4217. (ej:USD)
                storeId:"TU_STOREID", //Identificador único asignado a la transacción para su seguimiento.
                reference:"Pago por venta Fact#001" 	//Motivo o referencia específica del pago.           
            }).render('pp-button');
        })
</script>
<script>
	//Ejemplo de cobro de 2 USD sin impuesto
       window.addEventListener('DOMContentLoaded',()=>{
            ppb = new PPaymentButtonBox({
                token: 'ACA TU TOKEN',	//credenciales de acceso, se genera en payphone developer
                //Identificador único asignado por el comercio a cada transacción para su seguimiento.
                clientTransactionId: 'ID_UNICO_X_TRANSACCION-001', 	
                amount: 200, 	// Valor total de la factura a cobrar
                amountWithoutTax: 200, 	//Monto que no está sujeto a impuestos.
                currency: "USD",	//Código de moneda ISO 4217. (ej:USD)
                storeId:"TU_STOREID", //Identificador único asignado a la transacción para su seguimiento.
                reference:"Pago por venta Fact#001" 	//Motivo o referencia específica del pago.           
            }).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',	//credenciales de acceso, se genera en payphone developer
                //Identificador único asignado por el comercio a cada transacción para su seguimiento.
                clientTransactionId: 'ID_UNICO_X_TRANSACCION-001', 	
                amount: 315, 	// Valor total de la factura a cobrar
                amountWithoutTax: 200, 	//Monto que no está sujeto a impuestos.
                amountWithTax:100, 	//Monto que incluye el valor sujeto a impuestos, excluyendo el propio impuesto.
                tax: 15,	//Monto del impuesto aplicado a la transacción.
                currency: "USD",	//Código de moneda ISO 4217. (ej:USD)
                storeId:"TU_STOREID", //Identificador único asignado a la transacción para su seguimiento.
                reference:"Pago por venta Fact#001" 	//Motivo o referencia específica del pago.           
            }).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.

Nombre

Descripción

Tipo de Dato

Opcional

token

Credencial que se genera en la configuración de payphone developer.

String

amount

Valor total de la factura a cobrar, es la suma de amountWithTax, amountWithoutTax, Tax, service y tip.

Int

amountWithoutTax

Monto que no está sujeto a impuestos.

Int

amountWithTax

Monto que incluye el valor sujeto a impuestos, excluyendo el propio impuesto.

Int

Si

tax

Monto del impuesto aplicado a la transacción.

Int

Si

service

Monto asociado al servicio proporcionado.

Int

Si

tip

Monto de la propina otorgada por el cliente.

Int

Si

currency

Código de moneda ISO 4217. (ej:USD)

String

Si

clientTransactionId

Identificador único asignado por el comercio a cada transacción para su seguimiento. Máximo 50 caracteres

String

storeId

Identificador de la sucursal que efectúa el cobro (se obtiene en payphone developer).

String

Si

reference

Motivo o referencia específica del pago. Máximo 100 caracteres

String

Si

phoneNumber

Número de teléfono del titular; se solicitará si no se proporciona.
Formato: Símbolo(+) + Código País + numero telefónico.
Ej. +593984111222

String

Si

email

Correo electrónico del titular; se solicitará si no se proporciona.

String

Si

documentId

Número de identificación del titular; se solicitará si no se proporciona.

String

Si

identificationType

Tipo de identificación:
*Cédula: 1
*RUC: 2
*Pasaporte: 3
Por defecto 1.

Int

Si

lang

Idioma de Formulario:
inglés (en),
español (es).
Por defecto en español.

String

Si

defaultMethod

El método por defecto a mostrar:
*Tarjeta = "card"
*Payphone = "payphone"

String

Si

timeZone

Zona horaria, (ej: -5)

Int

Si

lat

latitud en formato decimal: -1.831239

String

Si

lng

longitud en formato decimal: -78.183406

String

Si

Advertencia:
‍
Al utilizar los campos phoneNumber, email y documentId en las solicitudes a los servicios de payphone, es crucial que se ingresen los datos del titular de la tarjeta para cada transacción individual.
No se permite el uso de datos "quemados" o estáticos, ya que esto puede resultar en el rechazo de sus transacciones y el bloqueo de sus usuarios. El uso de datos falsos o repetitivos puede generar sospechas de fraude.

Payphone se compromete a proteger la seguridad y privacidad de los datos, por lo que es fundamental cumplir con esta política para garantizar un proceso de pago seguro y confiable.


Al final tu código debe estar estructurado de la siguiente forma:

<!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: Es importante tener en cuenta que el servicio de cajita de pago tienen una ventana de tiempo de 10 minutos para ser utilizados. Pasado este lapso, el formulario expirará y será necesario generar uno nuevo.

Nota: Para garantizar la autorización de pagos, es esencial que redirijas al usuario al formulario de pago desde tu dominio web configurado en el entorno de desarrollo. Si la redirección se realiza desde otro dominio o si la identidad del sitio se oculta, la autorización será denegada.
Este mensaje se mostrará si tu plataforma no cumple con esta condición.

Consultar respuesta de la transacción

Al completar el proceso de pago, el sistema redireccionará automáticamente al usuario a la página web que hayas configurado como URL de respuesta. Esta página recibirá dos parámetros importantes en su URL:

  • id Un número entero (int) que representa el identificador único de la transacción asignado por payphone.
  • clientTransactionId Una cadena de texto (string) que corresponde al identificador de la transacción que tu plataforma definió al iniciar el proceso de pago.

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

Ejemplo en PHP para recuperar los parametros ID y ClientTransactionID de una url
$id = isset($_GET["id"])?$_GET["id"]:0;
$clientTransactionId = isset($_GET["clientTransactionId"])?$_GET["clientTransactionId"]:"";
Detalle de Transacción:

API Buttom Confirm
Este método te proporcionará información detallada sobre la transacción, incluyendo si fue exitosa o no. Con esta información, podrás mostrar un mensaje al usuario confirmando el resultado de la operación.

Para utilizar el método Confirm, debes realizar una solicitud POST a la siguiente URL:

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

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).
Descripción de parámetros de respuesta

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

Nombre

Descripción

statusCode

Código de estado de la transacción.
2 = Cancelado.
3 = Aprobada

transactionStatus

Estado de la transacción (Approved o Canceled).

clientTransactionId

Identificador de transacción que enviaste en la petición.

authorizationCode

Código de autorización bancario.

transactionId

Identificador de transacción asignado por payphone.

email

El correo electrónico registrado en el formulario para el pago.

phoneNumber

Número de teléfono registrado en el formulario para el pago.

document

Número de cédula registrado en el formulario para el pago.

amount

Monto total pagado.

cardType

Tipo de tarjeta utilizada (crédito o débito).

cardBrandCode

Código de la marca de la tarjeta.

cardBrand

Marca de la tarjeta. VISA o Mastercard y Banco Emisor

bin

Primeros 6 dígitos de la tarjeta utilizada.

lastDigits

Últimos dígitos de la tarjeta utilizada.

deferredCode

Código de diferido empleado por el usuario.

deferredMessage

Mensaje del diferido.

deferred

Indica si se usó un diferido (booleano).

message

Mesaje de error, si corresponde

messageCode

Código de mensaje.

currency

Moneda utilizada para el pago.

reference

Motivo de la transacción

optionalParameter3

Parámetro opcional

optionalParameter4

Nombre del titular si el pago es con tarjeta

storeName

Nombre de la tienda que cobro

date

Fecha de cobro en formato ISO 8601

regionIso

Códigos de país en ISO 3166-1

transactionType

Tipo de Transacción

Ejemplo:

Método y Endpoint:
POST: https://pay.payphonetodoesposible.com/api/button/V2/Confirm

Cabeceras:
Content-Type: application/json
Authorization: bearer SU_TOKEN

Cuerpo de la solicitud (JSON):
{
    "id": 23178284,
    "clientTxId": "ID_UNICO_X_TRANSACCION-001"
}

Respuesta:

{
    "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"
}
Solicitudes POST al Servicio Buttom/Confirm

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

PHP
JQUERY
FETCH
<?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>

¡Y eso es todo! Si has llegado a este punto, ¡felicidades! Tu integración está completada. En la siguiente sección, te explicaremos cómo realizar pruebas y pasar a producción.

Probar transacciones y empezar a cobrar con cajita de pagos payphone

En payphone tienes el control total sobre el proceso. Eres tú quien decide cómo ejecutar las PRUEBAS y cuándo pasar a PRODUCCIÓN.
A continuación, te ofrecemos una guía para facilitarte este proceso.
‍

Entorno de Pruebas y Produccion

‍
‍No necesitas ningún proceso de certificación, y puedes publicar tu aplicación de manera independiente.

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