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:

Preparar la transacción: Proporciona a Payphone los detalles del pago (monto a cobrar, impuestos y detalles generales de la transacción).
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.
Realizar el pago: El cliente podrá pagar utilizando su tarjeta de crédito, débito, o saldo de Payphone.
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 de ambiente

Para implementar el botón de pagos, es necesario cumplir con ciertos requisitos, que se dividen en dos categorías: Requisitos Comerciales y Requisitos de Desarrollo.

Requisitos Comerciales:

El establecimiento que recibirá los pagos debe estar registrado en Payphone Business. Para iniciar el proceso de registro, puedes hacer click aquí.
Una vez que tu tienda esté activa, deberás crear un usuario de tipo «desarrollador«, del cual te proporcionaremos más detalles más adelante.

Requisitos de Desarrollo:

Es necesario configurar tu entorno de desarrollo en nuestro portal «Payphone Developer«. Aquí podrás obtener todos los tokens de autenticación necesarios para identificarte en los servicios de Payphone.

Crear usuario desarrollador

Inicia sesión en tu cuenta de Payphone Business con tu RUC, correo y contraseña.
Dirígete a la sección «Usuarios» y selecciona «Crear Usuario».

Completa el formulario ingresando todos los datos requeridos y asegúrate de seleccionar el rol «Desarrollador».

Con el usuario desarrollador creado, estarás listo para iniciar la implementación.

Página Payphone Developer

Configurar el ambiente de desarrollo en Payphone te permite gestionar y supervisar todas las transacciones realizadas a través de la plataforma de manera eficiente. Sigue estos pasos para comenzar:

1. Iniciar sesión en Payphone Developer

Ingresa a la plataforma https://appdeveloper.payphonetodoesposible.com/ e inicia sesión con las credenciales de tu usuario desarrollador (Ruc, correo y contraseña).

2. Crear Aplicación Payphone:

Las aplicaciones de desarrollo de Payphone te permiten configurar parámetros de conexión, usuarios de prueba y gestionar tu entorno (pruebas y producción). Además, te proporcionan las credenciales necesarias para la autenticación, como el token y el StoreID.

Inicia la Creación de la Aplicación
Para comenzar, haz clic en el botón “+ Agregar” ubicado en la parte superior de la página.

Completa el Formulario de Creación Se abrirá un formulario en el que deberás ingresar la información de tu aplicación. A continuación, se detallan los campos que debes completar:

Nombre: Define un nombre que identifique claramente tu aplicación.
Descripción: Añade una breve descripción de la funcionalidad o propósito de tu aplicación.
Categoría: Selecciona la categoría que mejor corresponda a tu perfil de negocio.
Plataforma de Desarrollo: Elige la plataforma donde está desarrollada tu aplicación. Si no aparece la opción exacta, selecciona la más similar.
Tipo de Aplicación: Para integrar el botón de pagos, asegúrate de seleccionar el tipo WEB.
Dominio Web: Introduce la URL de tu sitio web. Es importante solo el dominio registrado puede acceder al botón de pago de Payphone. Si intentas abrir la «cajita de pagos» desde otro dominio, el acceso será bloqueado.
URL de Respuesta: Proporciona la URL a la que se redirigirá al usuario una vez finalizada la transacción. En esta URL se adjuntarán los parámetros necesarios para obtener el detalle completo de la transacción realizada.

Después de completar todos los campos, presiona el botón Guardar.

Obtener Credenciales de Autenticación (Token, StoreID)

Una vez creada tu aplicación, obtendrás las credenciales necesarias para acceder a nuestras APIs.

Dirígete al menú superior y selecciona la pestaña Credenciales.
Podrás ver el Token y el botón que te lleva al listado de tiendas, donde encontrarás tu StoreID. Ambos cuentan con un botón para copiarlos fácilmente.

Preparar transacción

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

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

API Buttom Prepare

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

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

El cuerpo de la solicitud debe ser un objeto JSON con los siguientes campos :

Nombre	Descripción	Tipo de dato	Opcional
amount	Valor total a cobrar, debe ser igual a la suma de todos los montos individuales ( amountWithoutTax, amountWithTax, 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 a la transacción para su seguimiento.	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.	String	Si
phoneNumber	Número de teléfono del cliente; se solicitará si no se proporciona.	String	Si
email	Correo electrónico del cliente; se solicitará si no se proporciona.	String	Si
documentId	Número de identificación del cliente; se solicitará si no se proporciona.	String	Si
responseUrl	Url de respuesta a donde se redirecciona luego del pago	String
cancellationUrl	Url a donde se redirecciona si se cancela la transacción desde el icono X en el formulario	String	Si
optionalParameter	Información adicional para la transacción	String	Si
order	Arreglo con datos de facturación y detalle de artículos	String	Si

Consideraciones:

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

Recuerda que el 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 amount

Importante: 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

Ejemplo: Para cobrar $3.15, divididos en $1 con un impuesto del 15% y $2 sin impuesto, enviarías 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"
}

A continuación, se presentan ejemplos básicos de objetos JSON que puedes utilizar para preparar un cobro:

Cobro de $1 dólar sin impuestos:

				
					{
    "responseUrl":"https://tu-dominio.com/ConfirmacionPago",
    "amount": 100,
    "amountWithoutTax": 100,
    "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,
    "clientTransactionId": "ID_UNICO_X_TRANSACCION-003"
}

Estos son los objetos básicos, pero se recomienda siempre incluir cualquier dato adicional que tu sistema requiera.

Ejemplo de Llamada al Servicio 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 muestra cómo hacerlo con la versión más reciente de jQuery:

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

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

				
					var parametros = {
    amount: "100",
    amountWithoutTax: "100",
    clientTransactionID: "ID_UNICO_X_TRANSACCION-004",
    responseUrl: "https://tu-dominio.com/ConfirmacionPago",
    cancellationUrl: "https://tu-dominio.com/",
    reference:"Motivo de Pago"
};
    
$.ajax({
    data: parametros,
    url: 'https://pay.payphonetodoesposible.com/api/button/Prepare',
    type: 'POST',
    dataType: 'json',
    beforeSend: function(xhr) {
        xhr.setRequestHeader('Authorization', "Bearer TU_TOKEN");
    },
    success: function SolicitarPago(respuesta) {
        location.href = respuesta.payWithCard;
    },
    error: function(mensajeError) {
        alert("Error en la llamada: " + JSON.stringify(respuesta));
    }
});

Respuesta del Servicio

Al realizar la llamada 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:

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 tú definiste al iniciar el proceso de pago.

Es crucial capturar estos parámetros para poder realizar una solicitud al método 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.

Ejemplo en PHP para Recuperar ID y ClientTransactionID

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

API Buttom Confirm

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 recibidos en 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).

Parámetros de Respuesta

Recibirás una respuesta JSON con los detalles de la transacción, incluyendo:

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.
transactionId	Identificador de transacción asignado por Payphone.
authorizationCode	Código de autorización bancario.
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.
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	Mensaje 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 q 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: Al realizar un pago de $3.15, recibirás la siguiente estructura:

				
					{
    "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"
}

Ejemplo de Llamada al Servicio Buttom/Confirm en PHP

A continuación te detallo el ejemplo de llamada al servicio web en PHP:

				
					//Obtener parametros de la URL enviados por PayPhone
    $transaccion = isset($_GET["id"])?$_GET["id"]:0;
    $client = isset($_GET["clientTransactionId"])?$_GET["clientTransactionId"]:"";

//Preparar JSON de llamada
    $data_array = array(
        "id" =&gt;  (int)$transaccion,
        "clientTxId" =&gt; $client 
    );
    
    $data = json_encode($data_array);

//Iniciar Llamada
    $curl = curl_init();
    $headers = array();
    $headers[] = 'Authorization: Bearer TU TOKEN DE AUTENTICACIÓN';
    $headers[] = 'Content-Type: application/json';
    curl_setopt($curl, CURLOPT_URL, "https://pay.payphonetodoesposible.com/api/button/V2/Confirm");
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HEADER, 0);
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
    $result = curl_exec($curl);
    curl_close($curl);
    
//En la variable result obtienes todos los parámetros de respuesta
    echo $result;

¡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

Como te hemos mencionado anteriormente, 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. No necesitas ningún proceso de certificación, y puedes publicar tu aplicación de manera independiente. A continuación, te ofrecemos una guía para facilitarte este proceso.

Tu aplicación, creada en la página de Payphone Developer, cuenta con dos ambientes preestablecidos: “PRUEBAS” y “PRODUCCIÓN”. Al acceder a la configuración de tu aplicación en nuestro sitio de Developers, podrás seleccionar el ambiente que desees utilizar.

Ambiente de Pruebas:
Un entorno seguro para desarrollar y probar tu aplicación sin afectar a tus usuarios.

En el ambiente de pruebas, todas tus transacciones serán aprobadas, pero no se conectarán a ningún procesador bancario. Esto significa que puedes utilizar tus tarjetas (Visa o Mastercard válidas) sin que se realice ningún cobro real.

Ambiente de Producción:
El entorno real donde tus clientes realizarán pagos. Asegúrate de haber realizado todas las pruebas necesarias antes de activar este ambiente.

En el ambiente de producción, las transacciones se conectan efectivamente al sistema bancario, lo que implica que las operaciones son reales y tu botón de pago estará activo.

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

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

Sabias que...