Sabias que...

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

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

¡Bienvenido! en pocos minutos y siguiendo este tutorial podrás tener activo y funcional el botón de pago de Payphone. 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 botón de pago Payphone te permite recibir pagos con tarjetas de crédito y débito Visa y Mastercard , además de tarjetas de regalo y saldo Payphone de tus clientes usando nuestra app.

Flujo del Botón de pago

Para recibir pagos con nuestro gateway solo debes seguir estos sencillos pasos:

  1. Preparas la transacción (indicas a Payphone los datos del cliente, el valor a cobrar, impuestos y datos generales de la transacción).
  2. Payphone te entrega una URL en donde estará listo tu botón de pago. Debes redirigir a tu cliente a esta url.
  3. El cliente realiza el pago con su tarjeta de crédito, débito, tarjeta de regalo o saldo.
  4. Payphone llama a tu servidor en donde debes consultar el resultado la transacción.

Video Tutorial

En el siguiente video puedes ver como en pocos minutos se puede integrar nuestro Botón de pago

Configuración de ambiente

Para implementar el botón de pagos debes cumplir ciertos requisitos que dividimos en dos categorías: Requisitos Comerciales y Requisitos de Desarrollo.

Requisitos Comerciales:

  • El establecimiento que va a recibir los pagos tiene que estar registrado en Payphone Business. Para iniciar el registro 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 para desarrolladores «Payphone Developer» tu ambiente de desarrollo en donde podrás obtener todas tu token de autenticación con el que te identificas en los servicios de Payphone..

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

Haz click en usuarios

Ingresa todos los datos del desarrollador en el formulario, no olvides que en el campo «Roles» debes ingresar «Desarrollador». (El administrador debe entregarel correo electrónico y la contraseña ingresadas)

Con este proceso listo, el usuario desarrollador puede iniciar la implementación.

Página Payphone Developer

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

Developer

2. Crear Aplicación Payphone:

Las aplicaciones de desarrollo Payphone te permiten configurar tu ambiente de pruebas, parámetros de conexión o usuarios de test, 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 de tu aplicación, 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 intentas llamar al botón de pago desde una dirección distinta a tu dominio web, no te dará acceso.
  • Url de respuesta: Es la url donde se notificará el estado de la transacción.

Por último selecciona tu tipo de aplicación como WEB

Presiona Guardar

Obtener Token de autenticación

Con la aplicación configurada debes hacer click el menú superior en la pestaña credenciales, y tendrás el botón para copiar tu token..

Preparar transacción

Para implementar el botón de pago debes consumir dos servicios web mediante llamadas POST enviando un objeto tipo Json. 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: 

con un objeto del tipo Json que cuente con los siguientes parámetros:

Nombre Descripción Tipo de dato Opcional
amount
Valor total de la factura a cobrar, es la suma de amountWithTax, amountWithoutTax, Tax, service y tip.
Int
amountWithoutTax
Valor que no graba impuesto.
Int
X - solo en caso de que se cobre valores con Iva, es obligatorio si no se cobran valores con Iva
amountWithTax
Valor que si graba impuesto, sin el impuesto incluido.
Int
X - solo en caso de que se cobre valores sin Iva, es obligatorio si se cobran valores con Iva
tax
Valor del impuesto.
Int
X - solo en caso de que se cobre valores sin Iva, es obligatorio si se cobran valores con Iva
service
Valor del servicio.
Int
X
tip
Valor de la propina.
Int
X
currency
Moneda a cobrar. /ej USD
String
X
clientTransactionId
Identificador de transacción, debes generarlo, es un identificador único.
String
storeId
Identificador de sucursalr que realiza el cobro, este parámetro se puede obtener en el apartado "Solicitud de compañia" de la página de PayPhone Developer, en el botón lista.
String
X
reference
Referencia del pago que puedes enviar.
String
X
phoneNumber
Número de Teléfono del cliente, si no lo envías el botón lo solicitará al cliente.
String
X
email
Correo electrónico del cliente, si no lo envías el botón lo solicitará al cliente.
String
X
documentId
Número de identificación del cliente, si no lo envías el botón lo solicitará al cliente.
String
X

Los valores a cobrar son enteros y se deben multiplicar por 100, por ejemplo $1 dólar = 100. A continuación puedes ver un ejemplo de cobrar $1 dólar con impuestos.

				
					{
"responseUrl": "http://localhost/",
"amount": 112,
"amountWithTax": 100,
"tax": 12,
"clientTransactionId": "identificadorUnico002"
}
				
			
  • Cobro de $1 dólar sin impuestos:
				
					{
"responseUrl":"http://localhost/",
"amount": 100,
"amountWithoutTax": 100,
"clientTransactionId": "identificadorUnico001"
}
				
			

Estos son los objetos base pero te recomendamos siempre enviar los datos del titular de la tarjeta, en caso de que los dispongas(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.

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

				
					var parametros ={
    amount: "100",
    amountWithoutTax: "100",
    clientTransactionID: "IdentificadorUnico",
    responseUrl: "https://tuurl.comm/response.php",
    cancellationUrl: "https://tuurl.com/response.php"};
    
    $.ajax({
        data: parametros,
        url: 'https://pay.payphonetodoesposible.com/api/button/Prepare',
        type:'POST',
        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:" + mensajeerror.Message);
                }
            });
        }
				
			

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

Consultar respuesta de transacción

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"];
?>
				
			

 

Para consultar el estado de la transacción, debes crear un archivo en tu URL de respuesta (configurada en tu página de Payphone Developer). Con esos parámetros debes llamar a nuestro servicio web CONFIRM para obtener los parámetros de respuesta de la transacción.

El método confirma al servicio Payphone que recibiste la respuesta del botón de pagos y así mismo consulta el resultado de la transacción. 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. 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.
email
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.
optionalParameter1
Parámetro opcional

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

				
					<?php
//Obtener parametros de la URL enviados por PayPhone
$transaccion = $_GET["id"];
$client = $_GET["clientTransactionId"];

//Preparar JSON de llamada
$data_array = array(
"id"=> (int)$transaccion,
"clientTxId"=>$client );

$data = json_encode($data_array);

//Iniciar Llamada
$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, $data);
curl_setopt_array($curl, array(
CURLOPT_HTTPHEADER => array(
"Authorization: Bearer TU TOKEN DE AUTENTICACIÓN", "Content-Type:application/json"),
));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($curl);
curl_close($curl);

//En la variable result obtienes todos los parámetros de respuesta
echo $result;
?>
				
			

Y ¡Listo!, Eso es todo, si llegaste a este punto, felicidades, tu integración está completada, en la siguiente sección te contaremos como hacer pruebas y pasar a producción.

Pruebas y paso a producción

Como ya te hemos comentado en Payphone todo el control lo tienes tú, y eres tú quien decide cómo ejecutar las pruebas y pasar a producción. No necesitas ningún proceso de certificación y puedes publicar tu mismo sin problema. Acá te damos una guía.

Tu aplicación creada en la página de Payphone Developer cuenta con dos ambientes pre establecidos que son «PRUEBAS» y «PRODUCCIÓN«. Cuando ingresas en la configuración de tu aplicación desde nuestro sitio de Developers puedes seleccionar el ambiente que necesites.

En pruebas todas tus transacciones serán aprobadas pero no se conectaran las transacciones a ningún procesador bancario, por lo que puedes usar tus tarjetas y no se realizará ningún cobro, o cualquier Visa o Mastercard valida.

En ambiente de producción el comportamiento es el mismo, pero si se realiza la conexión bancaria por lo que las transacciones ya son reales y cuentas con tu botón de pago activo.

Con tu aplicación en producción el proceso está completo, felicidades por integrar tu Express Checkout