¡Bienvenido! en pocos minutos y siguiendo este tutorial podrás tener activo y funcional el botón de pago de PayPhone. Puedes recibir pagos con tarjeta de crédito y débito y ampliar tus opciones, procesando desde nuestra app, tarjetas de regalo y saldo de tus clientes.
El botón de pago se compone de dos servicios web REST que puedes llamar con estructura Json usando el lenguaje de programación que prefieras.
El flujo de botón de pago es el siguiente:
- Preparas la transacción (indicas a PayPhone los datos del cliente, el valor a cobrar, impuestos y datos generales de la transacción).
- PayPhone te entrega una URL en donde estará listo tu botón de pago.
- Rediriges a tu cliente al botón de pago desde tu página web.
- El cliente realiza el pago con su tarjeta de crédito, débito, tarjeta de regalo o saldo.
- PayPhone envía el resultado de la transacción y regresa a su página de origen.
Configuraciones preliminares
Para implementar el botón de pagos debes cumplir los siguientes requisitos: Requisitos Comerciales y Requisitos de Desarrollo.
Requisitos Comerciales:
- El establecimiento que va a recibir los pagos tiene que estar registrado en PayPhone como una tienda habilitada. Para iniciar el registro como PayPhone Business puedes hacer click aquí.
- Con la tienda activa y lista para transaccionar, debes crear un usuario de tipo “desarrollador“, el cual te explicaremos más adelante.
Requisitos de Desarrollo:
- Debes configurar en nuestro sitio web «PayPhone Developer» tu ambiente de desarrollo en donde podrás obtener todas tus credenciales, tokens y llaves con las que podrás identificarte en nuestros servicios y añadir la seguridad respectiva al proceso.
Crear usuario desarrollador
Ingresa en tu página PayPhone Business, e inicia sesión con el ruc, correo y contraseña, (si no tienes acceso el administrador de la empresa puede entrar y crear tu usuario) y dirígete a la sección de «Usuarios» a continuación selecciona «Crear Usuario»:
Ingresa todos los datos del desarrollador en el formulario, no olvides que en el campo «Roles» debes ingresar «Desarrollador». (El administrador debe entregar al desarrollador el correo electrónico y la contraseña ingresadas)
Selecciona la tienda o sucursal que recibirá los pagos y presiona el botón Guardar:
Con este proceso listo, el usuario desarrollador puede iniciar la implementación.
Configuración de ambiente
Configurar el ambiente de desarrollo te permite tener un control total sobre las transacciones efectuadas a través de PayPhone. Por favor sigue los siguientes pasos:
1. Iniciar sesión como desarrollador
Ingresa en la página 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 PayPhone te permiten configurar los parámetros de implementación, como la plataforma, permisos o usuarios de prueba, y te ayuda a obtener tus credenciales de autenticación como el token.
Para crear tu aplicación haz click en el “+” de la parte superior:
Se abrirá un formulario donde debes ingresar los campos informativos, y completar principalmente:
- Dominio web: La url de tu página web que se conectará al botón de PayPhone. SOLO EL DOMINIO WEB TIENE ACCESO AL BOTÓN DE PAGO, si no rediriges desde tu dominio web no te dará autorización.
- Url de respuesta: Es la url donde el botón de pago redirigirá al usuario y donde recibirás el estado de la transacción. En ella debes mostrar al cliente si se aprobó o rechazo la misma.
Por último selecciona tu tipo de aplicación como WEB
Presiona Guardar
Con la aplicación configurada puedes obtener tu token de autenticación. En el menú superior haz click en credenciales, y tendrás el botón para copiar tu token.
Implementación del botón de pago
Para implementar el botón de pago debes consumir dos servicios web mediante llamadas POST enviando un objeto tipo Json, nada del otro mundo. Consumiendo los dos métodos, tu botón de pago estará listo en pocos minutos. El primer método es el «PREPARE» en donde se prepara el botón de pago, indicando monto a cobrar, datos de usuario, y campos adicionales. En la respuesta de esa llamada, nuestro servicio web entregará una URL donde se encuentra el botón de pago listo.
Método Prepare
Para consumir el método Prepare debes hacer una llamada POST a la siguiente dirección: https://pay.payphonetodoesposible.com/api/button/Prepare con un objeto del tipo Json que cuente con los siguientes parámetros:
Nombre | Tipo | Opcional | Descripción |
---|---|---|---|
amount | Integer | Valor total por cobrar al cliente | |
amountWithoutTax | Integer | X | Valor del subtotal de los productos que no cobran impuestos. Solo se usa con tipo de facturación tarifa 0% o mixta. |
amountWithTax | Integer | X | Valor del subtotal de los productos que cobran impuestos sin sumar el valor de los impuestos. Solo se usa con tipo de facturación con IVA o mixta. |
tax | Integer | X | Valor total de los impuestos. Solo se usa con tipo de facturación con IVA o mixta. |
service | Integer | X | Valor del servicio |
tip | Integer | X | Valor de la propina |
currency | String | X | Moneda con la que se cobra, ejemplo “USD”. |
clientTransactionId | String | Identificador de la transacción en la aplicación del cliente (String asignado por tu empresa tu plataforma). Es un parámetro que sirve de identificación para consulta o reverso de la transacción. | |
responseUrl | String | Url de respuesta donde PayPhone enviara al cliente después de finalizada la transacción | |
cancellationUrl | String | X | Url de retorno cuando el cliente cancela el proceso de pago. |
phoneNumber | String | X | Número de teléfono del usuario que realiza el pago. |
String | X | Correo electrónico del usuario que realiza el pago. | |
documentId | String | X | Documento de identidad del usuario que realiza el pago. (Número de cédula o pasaporte) |
StoreId | String | X | Id del Store que va a cobrar, Este valor solo se envía cuando se manejan diferentes tiendas o sucursales, si no se usan diferentes tiendas se puede omitir. Para especificar que tienda hace el cobro, el storeID se obtiene desde la página web de PayPhone Developer, en la sección solicitud de compañía, columna Acciones, Listado de tiendas. |
Reference | String | X | Referencia de la transacción, por ejemplo “Venta Zapatos Azules” |
AditionalData | String | X | Datos adicionales que quieras guardar de la transacción. |
OptionalParameter | String | X | Parámetro opcional a tu disposición. |
transferTo | String | X | Parámetro para pagos compartidos. En el siguiente enlace puedes revisar como hacer pagos compartidos. |
Todos los valores monetarios a enviar deben ir multiplicados por 100, por ejemplo, $1 dólar = 100; $1.50 dólares = 150.
Ejemplos de Json método prepare:
- Cobro de $1 dólar sin impuestos:
{
«responseUrl»: «http://localhost/»,
«amount»: 100,
«amountWithoutTax»: 100,
«clientTransactionId»: «identificadorUnico001»
}
- Cobro de $1.12, donde $1 dólar es el subtotal y $0.12 los impuestos:
{
«responseUrl»: «http://localhost/»,
«amount»: 112,
«amountWithTax»: 100,
«tax»: 12,
«clientTransactionId»: «identificadorUnico002»
}
Estos son los objetos base pero te recomendamos siempre enviar los datos del usuario (cédula, correo y teléfono) y usar los datos opcionales que requiera tu sistema.
No olvides que en la llamada POST debes agregar una cabecera (header) de tipo “Authorization” indicando el token de autenticación generado previamente, debes poner antes del token la palabra “Bearer “. Recuerda que el Amount (Valor a cobrar) es la suma del detalle de los campos amountWithTax, amountWithoutTax, tax, service y tip, todos estos son opcionales, pero debe haber al menos uno para que el amount se vea respaldado.
Cuando hagas la llamada POST, recibirás un objeto Json con los siguientes parámetros:
- paymentId: Identificador del pago.
- payWithPayPhone: URL a la que debes redirigir al usuario para que realice el pago utilizando el app de PayPhone.
- payWithCard: URL a la que debes redirigir al usuario para que realice el pago directamente con su tarjeta de crédito o débito.
El cliente podrá pagar con sus tarjetas de crédito y débito Visa y Mastercard, con tarjetas de regalo o su saldo PayPhone. Sin importar el método de pago tu recibes la misma respuesta de transacción, aprobada o rechazada.
Tu plataforma debe redirigir al usuario a esta url donde debe realizar el pago. (Recuerda, debes redirigir al usuario desde tu dominio web configurado, caso contrario no dará autorización)
Una vez finalizado el cobro, el botón de pagos regresara a la página web de origen (configurada en la URL de respuesta) indicando datos de la transacción. Finalmente debes ejecutar el método Confirm para verificar el resultado de la transacción y confirmar la respuesta por parte de la página web.
Método Confirm
Cuando el cliente complete la transacción, el sistema lo redirigirá a tu URL DE RESPUESTA con dos atributos «ID» y «ClientTransactionID» que debes recuperar ejecutando un GET en tu URL.
Estos campos te ayudaran para llamar al método Confirm y obtener todos los datos de la transacción.
Ejemplo para obtener el Id y ClientTransactionID con php:
<?php
$transaccion = $_GET[«id»];
$client = $_GET[«clientTransactionId»];
?>
//Verifica que los parámetros estén entre comillas dobles, y no con »
El método confirm te ayuda para confirmar a PayPhone que recibiste la respuesta del botón de pagos y consultar el resultado de la transacción con el cliente. Debes hacer una llamada POST a la siguiente dirección: https://pay.payphonetodoesposible.com/api/button/V2/Confirm con el parámetro de ID y ClientTransactionID en tipo Json. No olvides adjuntar en el header tu token de autenticación.
{
«id»: int,
«clientTxId»: «string»
}
Los parámetros de respuesta que recibirás son los siguientes:
Nombre | Descripción |
---|---|
statusCode | Código de estado de la transacción. 2=Cancelado.03=Aprobada |
transactionStatus | Estado de la transacción. |
clientTransactionId | Identificador de transacción que tu enviaste en la petición. |
authorizationCode | Código de autorización bancario. |
transactionId | Identificador de transacción asignado por PayPhone. |
El correo electrónico empleado por el usuario para el pago. | |
phoneNumber | Número de teléfono empleado por el usuario para el pago. |
document | Número de cédula empleado por el usuario para el pago. |
amount | Monto total pagado. |
cardType | Tipo de tarjeta empleada, puede ser 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 empleada. |
lastDigits | Últimos dígitos de la tarjeta empleada. |
deferredCode | Código de diferido empleado por el usuario. Aquí puedes conocer más de los diferidos. |
deferredMessage | Mensaje del diferido. |
deferred | Variable boleana que indica si se uso un diferido o no. |
message | En caso de error se muestra el error en este parámetro. Puedes consultar el catálogo de errores haciendo click aquí. |
messageCode | Código de mensaje. |
currency | Moneda empleada para el pago. |
taxes | Arreglo con todos los impuestos pagados, con los campos: («name»,»amount», «value», «tax») |
recap | Parámetro de identificación bancario. |
optionalParameter1 | Parámetro opcional |
¡Y Listo! con esos dos métodos tu botón de pago estará listo, Disfruta PayPhone.
Video Tutorial
Si prefieres seguir un ejemplo más visual te dejamos nuestro video tutorial con todas las indicaciones 🙂
Hola, tengo un inconveniente, después de realizar toda la transacción, cuando espero la confirmación me sale la alerta de error, siempre me llega un «Bad request», el json que me retorna tiene los errores y dice que el problema está en el código de identificación(clientTransactionID), le cambié muchas veces la identificación y me sigue saliendo el mismo error. ¿Podrían ayudarme?
Hola Kenet, claro que sí, por favor escribenos a swiesner@payphone.app para ayudarte con una sesión y verificar el problema.
Saludos.