Sabias que...

Inicia tu integración hoy, y termínala hoy, así de simple es

Visita payphone.app

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: 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».
img-1
  • Completa el formulario ingresando todos los datos requeridos y asegúrate de seleccionar el rol «Desarrollador».
img-2

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

img-3

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.

img-4

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

Probadores

La sección de probadores está diseñada para usuarios de Payphone Personal y permite probar pagos desde la aplicación de Payphone. Su configuración es opcional.
Mas detalles en la sección Pruebas y paso a producción

Preparar transacción

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.

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:

  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 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 o puedes usar datos ficticios que cumplan con los requisitos de cada campo.

  • Probadores:
    Esta sección está diseñada específicamente para usuarios de Payphone Personal y te permite simular pagos directamente desde la aplicación de Payphone.
  • ¿Cómo funciona?
  1. Invita a un usuario de Payphone Personal: Accede al menú «Probadores» > «Clientes» y registra los números de teléfono de usuarios Payphone.
  2. Confirmación: Recibirán una invitación por correo electrónico a la dirección asociada a su cuenta de Payphone Personal.
  3. ¡Probar! Una vez aceptada la invitación, podrán simular pagos desde la app y tú podrás ver cómo se procesan.

Ambiente de Producción:
Este es el entorno donde tus clientes realizarán sus pagos de manera real. Todas las transacciones que se lleven a cabo en este ambiente se conectarán directamente al sistema bancario, lo que significa que el dinero se transferirá de forma efectiva

Recomendaciones:

  • Antes de activar el ambiente de producción, te recomendamos realizar todas las pruebas necesarias en el ambiente de pruebas para garantizar que todo funcione correctamente.
  • Utiliza únicamente datos reales (números de tarjeta, datos del cliente vinculado con su banco emisor, etc.) para evitar cualquier inconveniente.
  • Nuestro sistema cuenta con altos niveles de seguridad, por eso es importante utilizar datos correctos para evitar posibles bloqueos.

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

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