Botón de pago por redirección

¿Qué es el botón de pago Payphone?

¡Integra el botón de pago Payphone y simplifica tus transacciones! En pocos minutos tendrás activo un botón de pago que te permitirá recibir pagos de forma segura y eficiente , ya sea con tarjetas de crédito y débito (Visa , Mastercard) o saldo Payphone. ¡Integración rápida y flexible con cualquier lenguaje de programación gracias a nuestros API REST!

Flujo del Botón de pago

Para recibir pagos a través de nuestro gateway, solo necesitas seguir estos sencillos pasos:

1. Preparar la transacción: Proporciona a Payphone los detalles del pago (monto a cobrar, impuestos y detalles generales de la transacción).
2. Obtener la URL del formulario de pago: Payphone te proporcionará una URL donde estará disponible el formulario para completar los datos de la transacción. Simplemente redirige a tu cliente a esta URL.
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: Después de que el cliente haya realizado el pago, payphone enviará parámetros a la URL de tu servidor. Estos parámetros te permitirá verificar el estado de la transacción de manera eficiente.
   

Para integrar un botón de pago funcional, es fundamental realizar dos llamadas a servicios API REST con formato JSON:

1. Preparación: Envía una solicitud POST a buttom/prepare para configurar los detalles de la transacción, incluyendo montos, identificador único y demás datos relevantes. Esto devolverá enlaces a nuestro formulario.
2. Confirmación: Una vez procesado el pago, realiza una segunda solicitud POST a buttom/confirm para obtener el detalle de la transacción, que incluye el ID de Payphone, datos del cliente y el estado final.

Siguiendo este flujo, podrás implementar un proceso de pago seguro y eficiente en tu aplicación web.
A continuación, profundizaremos en cada uno de estos pasos.

Configuración del ambiente

Preparar la transacción

API Button/Prepare

Este método te permite preparar los montos que se va a cobrar en una transacción, así como información adicional que se necesite.

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

• https://pay.payphonetodoesposible.com/api/button/Prepare

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”).
• Content-type: application/json (Indica que el formato de los datos enviados en el cuerpo de la solicitud es JSON).

El cuerpo de la solicitud debe ser un objeto JSON con la siguiente estructura:

{
    "amount": 315,
    "amountWithoutTax": 200,
    "amountWithTax": 100,
    "tax": 15,
    "service": 0,
    "tip": 0,
    "clientTransactionId": "ID_UNICO_X_TRANSACCION-001",
    "responseUrl": "https://tu-dominio.com/ConfirmacionPago",
    "cancellationUrl": "https://tu-dominio.com/",
    "currency": "USD",
    "storeId": "Your_StoreId",
    "reference": "Motivo de Pago",
    "order": {
        "billTo": {
            "address1": "Horizon",
            "address2": "Zero Down",
            "country": "EC",
            "state": "Azuay",
            "locality": "Cuenca",
            "firstName": "Elisabeth",
            "lastName": "Sobeck",
            "phoneNumber": "+593999999999",
            "email": "aloy@mail.com",
            "postalCode": "EC090108",
            "customerId": "3",
            "ipAddress": "127.0.0.1"
        },
        "lineItems": [
            {
                "productName": "Producto Vendido",
                "unitPrice": 100,
                "quantity": 1,
                "totalAmount": 115,
                "taxAmount": 15,
                "productSKU": "3342.0004",
                "productDescription": "Descripción Producto"
            },
            {
                "productName": "Servicio Entregado",
                "unitPrice": 100,
                "quantity": 2,
                "totalAmount": 200,
                "taxAmount": 0,
                "productSKU": "5342.0054",
                "productDescription": "Descripción Servicio"
            }
        ]
    },
    "documentId": null,
    "phoneNumber": null,
    "email": null,
    "optionalParameter": "Descripción Extra"
}

El objeto JSON mostrado define el cobro de $3.15, divididos en $1 con un impuesto del 15% y $2 sin impuesto.

A continuación, se presentan una configuración de objetos JSON con los campos mínimos que puedes utilizar para preparar un cobro:

• Cobro de $1 dólar sin impuestos:

{
    "responseUrl":"https://tu-dominio.com/ConfirmacionPago",
    "amount": 100,
    "amountWithoutTax": 100,
    "currency": "USD",
    "clientTransactionId": "ID_UNICO_X_TRANSACCION-002"
}

• Cobro de $1 dólar con impuestos del 15%:
  

{
    "responseUrl":"https://tu-dominio.com/ConfirmacionPago",
    "amount": 115,
    "amountWithTax": 100,
    "tax": 15,
    "currency": "USD",
    "clientTransactionId": "ID_UNICO_X_TRANSACCION-003"
}

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, moneda, datos del cliente y otros campos que puedes enviar.

Campo ORDER

El campo order se divide en dos arreglos: BillTo, LineItems

BillTo:
El campo billTo es un arreglo que contiene información de facturación

LineItems:
El campo lineItems es un conjunto de arreglos que contiene la información de los servicios o productos entregados

Ejemplo de solicitud POST a Buttom/Prepare en JavaScript

Para realizar una llamada POST utilizando AJAX en JavaScript, primero necesitas incluir la biblioteca jQuery en la cabecera de tu documento HTML.

A continuación, se presenta un script de ejemplo de cómo realizar una llamada POST:

<!DOCTYPE html>
<html>
<head>
    <title>Ejemplo de Solicitud POST con jQuery</title>  
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
</head>
<body>
    <h1>Ejemplo de Solicitud POST</h1>
    <div id="resultado"></div>

    <script>
        const  clientTraxID =Date.now(); //genera un identificador unico para cada transacción
        
        $(document).ready(function() {
            $.ajax({
                url: "https://pay.payphonetodoesposible.com/api/button/Prepare",
                type: "POST",
                headers: {
                "Content-Type": "application/json",
                "Authorization": "Bearer TU_TOKEN"
                },
                data: JSON.stringify({ 
                    "amount": 180,
                    "amountWithoutTax": 180, 
                    "amountWithTax": 0,                
                    "tax": 0, 
                    "reference": "Pago mediante Boton payphone",    
                    "currency": "USD",                 
                    "clientTransactionId": clientTraxID,
                    "storeId": "TU_STOREID",    
                    "ResponseUrl": "https://tu-dominio.com/BotonConfirmacion"
                }),
                success: function(response) {
                    $("#resultado").html(
                        "<a href='" + response.payWithPayPhone + "' target='_blank'>Pagar con PayPhone</a><br>" +
                        "<a href='" + response.payWithCard + "' target='_blank'>Pagar con Tarjeta</a>"
                    );
                },
                error: function(error) {
                    console.error("Error en la solicitud:", error);
                }
            });
        });
    </script>
</body>
</html>

Respuesta a la solicitud POST

Al realizar la solicitud POST, recibirás un objeto JSON que incluye los siguientes parámetros:

• paymentId: Identificador del pago.
  
• payWithPayPhone: URL para redirigir al usuario a realizar el pago mediante la app de payphone.
  
• payWithCard: URL para que el usuario realice el pago directamente con su tarjeta de crédito o débito.
  

Consideraciones: Es importante tener en cuenta que los enlaces generados por el servicio tienen una ventana de tiempo de 10 minutos para ser utilizados. Pasado este lapso, el enlace expirará y será necesario generar uno nuevo.

Nota: Asegúrate de redirigir al usuario a la URL de pago desde tu dominio web configurado; de lo contrario, no se otorgará autorización.

Los clientes pueden pagar con tarjetas de crédito y débito Visa y Mastercard, así como con saldo Payphone. Independientemente del método de pago, recibirás la misma respuesta de transacción, ya sea aprobada o rechazada.

Consultar respuesta de 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:

1. id Un número entero (int) que representa el identificador único de la transacción asignado por PayPhone.
2. 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"]:"";

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": int,
    "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:

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": "Prueba Boton de Pago"
}

Llamada al Servicio Buttom/Confirm en PHP

A continuación se detalla una solicitud POST en PHP:

<?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 TU_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
    $result = curl_exec($curl);
    //Finaliza solicitud curl: POST
    curl_close($curl);

    //presenta el resultado en pantalla
    echo "Respuesta : <pre>".json_encode($result,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
?>

¡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.

Video Tutorial

A continuación, encontrarás un video donde podrás ver cómo integrar nuestro Botón de Pago en pocos minutos.

Pruebas y paso a producción

Una vez que tu aplicación esté en producción, el proceso estará completo.

¡Felicidades por integrar el botón de pagos de Payphone!