Did you know that...

Payphone te permite el costo 0, es decir, igual que el efectivo.

Visit payphone.app

Redirection payment button

What is the payment button 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!

Payment Button Flow

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.

Environment configuration

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.

Create developer user

  • Inicia sesión en tu cuenta de Payphone Business con tu RUC, correo y contraseña.
  • Go to the "Users" section and select "Create User".
img-1
  • Complete the form by entering all the required data and make sure to select the "Developer" role.
img-2

With the developer user created, you are ready to start the implementation.

Page Payphone Developer

Setting up the development environment at Payphone allows you to manage and monitor all transactions made through the platform efficiently. Follow these steps to get started:

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

Developer
img-3

2. Create Application 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.

Start Creating the Application
To begin, click on the "+ Add" button located at the top of the page.

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.

Obtain Authentication Credentials (Token, StoreID)

Once your application is created, you will get the necessary credentials to access our 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

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 :

Name Description Data type Optional
amount
Valor total a cobrar, es la suma de los montos: 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

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

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"
}
  • Charge of $1 dollar without taxes:
				
					{
    "responseUrl":"https://tu-dominio.com/ConfirmacionPago",
    "amount": 100,
    "amountWithoutTax": 100,
    "clientTransactionId": "ID_UNICO_X_TRANSACCION-002"
}

These are the basic objects but we recommend you to always send the card holder's data, if available (ID, mail and phone number) and use the optional data required by your system.

Do not forget that in the POST call you must add a header of type "Authorization" indicating the authentication token previously generated, you must put before the token the word "Bearer". Remember that the Amount is the sum of the detail of the fields amountWithTax, amountWithoutTax, tax, service and tip, all these are optional, but there must be at least one for the amount to be supported.

The following is an example of a web service call in 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);
                }
            });
        }

When you make the POST call, you will receive a Json object with the following parameters:

  • paymentId: Payment identifier.
  • payWithPayPhone: URL to which you must redirect the user to make the payment using the PayPhone app.
  • payWithCard: URL to which you must redirect the user to make the payment directly with his credit or debit card.

The customer can pay with their Visa and Mastercard credit and debit cards, gift cards or their balance Payphone. Regardless of the payment method you receive the same transaction response, approved or declined.

Your platform must redirect the user to this url where he/she must make the payment (Remember to redirect the user from your configured web domain, otherwise he/she will not be authorized).

Once the payment is completed, the payment button will return to the origin web page (configured in the response URL) indicating the transaction details. Finally you must execute the Confirm method to verify the result of the transaction and confirm the response from the web page.

Consult transaction response

When the client completes the transaction, the system will redirect him/her to your RESPONSE URL with two attributes "ID" and "ClientTransactionID" that you must retrieve by executing a GET on your URL.

These fields will help you to call the Confirm method and get all the transaction data.

Example to obtain the Id and ClientTransactionID with php:

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

 

To query the transaction status, you must create a file in your response URL (configured in your Payphone Developer page). With those parameters you must call our CONFIRM web service to get the transaction response parameters.

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:

Name Description
statusCode
Transaction status code. 2=Canceled.03=Approved
transactionStatus
Transaction status.
clientTransactionId
Transaction identifier that you sent in the request.
authorizationCode
Bank authorization code.
transactionId
Transaction identifier assigned by PayPhone.
email
The e-mail address used by the user for payment.
phoneNumber
Telephone number used by the user for payment.
document
ID number used by the user for payment.
amount
Total amount paid.
cardType
Type of card used, either credit or debit.
cardBrandCode
Card brand code.
cardBrand
Card brand.
bin
First 6 digits of the card used.
lastDigits
Last digits of the card used.
deferredCode
Deferral code used by the user. Here you can learn more about deferrals.
deferredMessage
Deferred message.
deferred
Boolean variable indicating whether a deferral was used or not.
message
In case of error, the error is displayed in this parameter. You can consult the error catalog by clicking here.
messageCode
Message code.
currency
Currency used for payment.
optionalParameter1
Optional parameter

The following is an example of a PHP web service call:

				
					    
    //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();
    $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;

That's it, if you have reached this point, congratulations, your integration is complete, in the next section we will tell you how to test and move to production.

Video Tutorial

En el siguiente video, podrás ver cómo integrar nuestro Botón de Pago en pocos minutos.

Testing and production

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!