Did you know that...

Payphone allows you 0 cost, i.e., the same as cash.

Visit payphone.app

Redirection payment button

What is the payment button Payphone?

Integrate the payment button Payphone and simplify your transactions! In a few minutes you will have an active payment button that will allow you to receive payments securely and efficiently, either with credit and debit cards (Visa, Mastercard) or balance Payphone. Fast and flexible integration with any programming language thanks to our REST API!

Payment Button Flow

To receive payments through our gateway, you only need to follow these simple steps:

  1. Prepare the transaction: Provide Payphone with the details of the payment (amount to be collected, taxes and general transaction details).
  2. Get the URL of the payment form: Payphone will provide you with a URL where the form will be available to complete the transaction data. Simply redirect your customer to this URL.
  3. Payment: The customer can pay using their credit card, debit card, or balance from Payphone.
  4. Query the result of the transaction: Payphone will send parameters to your server URL, allowing you to check the status of the transaction efficiently.

Environment configuration

To implement the payment button, it is necessary to meet certain requirements, which are divided into two categories: Business Requirements and Development Requirements.

Business Requirements:

  • The establishment that will receive the payments must be registered in Payphone Business. To start the registration process, you can click here.
  • Once your store is active, you will need to create a "developer" type user, of which we will provide more details later.

Development Requirements:

  • It is necessary to configure your development environment in our portal "Payphone Developer". Here you can obtain all the authentication tokens needed to identify yourself in the services of Payphone.

Create developer user

  • Log in to your Payphone Business account with your RUC, email and password.
  • 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. Log in to Payphone Developer

Enter the platform https://appdeveloper.payphonetodoesposible.com/ and log in with the credentials of your developer user (Ruc, email and password).

img-3

2. Create Application Payphone:

The development applications of Payphone allow you to configure connection parameters, test users and manage your environment(test and production). In addition, they provide you with the necessary credentials for authentication, such as token and StoreID.

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

img-4

Complete the Creation Form A form will open in which you must enter your application information. Below are the fields you must complete:

  • Name: Define a name that clearly identifies your application.
  • Description: Add a brief description of the functionality or purpose of your application.
  • Category: Select the category that best matches your business profile.
  • Development Platform: Choose the platform where your application is developed. If the exact option does not appear, select the most similar one.
  • Application Type: To integrate the payment button, be sure to select the WEB type.
  • Web Domain: Enter the URL of your website. It is important that only the registered domain can access the payment button of Payphone. If you try to open the "payment box" from another domain, access will be blocked.
  • Response URL: Provides the URL to which the user will be redirected once the transaction is completed. This URL will contain the necessary parameters to obtain the complete details of the transaction.

After completing all the fields, press the Save button.

Obtain Authentication Credentials (Token, StoreID)

Once your application is created, you will get the necessary credentials to access our APIs.

  • Go to the top menu and select the Credentials tab.
  • You will see the token and the button that takes you to the list of stores, where you will find your StoreID. Both have a button to copy them easily.
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

Prepare transaction

To integrate a functional payment button, it is essential to make two JSON-formatted REST API service calls:

  1. Preparation: Send a POST request to buttom/prepare to set up the transaction details, including amounts, unique identifier and other relevant data. This will return links to our form

  2. Confirmation: Once the payment has been processed, make a second POST request to buttom/confirm to obtain the transaction detail, including the ID of Payphone, customer data and the final status.

By following this flow, you will be able to implement a secure and efficient payment process in your web application. Next, we will go deeper into each of these steps.

API Buttom Prepare

To use the Prepare method, you must make a POST call to the following address:

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

The body of the request must be a JSON object with the following fields :

Name Description Data type Optional
amount
Total value to be charged, must be equal to the sum of all individual amounts ( amountWithoutTax, amountWithTax, Tax, service and tip ).
Int
amountWithoutTax
Amount not subject to tax.
Int
amountWithTax
Amount that includes the taxable value, excluding the tax itself.
Int
Yes
tax
Amount of tax applied to the transaction.
Int
Yes
service
Amount associated with the service provided.
Int
Yes
tip
Amount of the tip given by the customer.
Int
Yes
currency
ISO 4217 currency code (e.g.: USD)
String
Yes
clientTransactionId
Unique identifier assigned to the transaction for tracking purposes.
String
storeId
Identifier of the branch that makes the payment (obtained in PayPhone Developer).
String
Yes
reference
Reason or specific reference for payment.
String
Yes
phoneNumber
Customer's telephone number; will be requested if not provided.
String
Yes
email
Customer's e-mail address; will be requested if not provided.
String
Yes
documentId
Customer identification number; will be requested if not provided.
String
Yes
responseUrl
Url of response where you are redirected to after payment
String
cancellationUrl
Url to be redirected to if the transaction is cancelled from the X icon on the form
String
Yes
optionalParameter
Additional transaction information
String
Yes
order
Arrangement with invoicing data and item details
String
Yes

Considerations:

It is essential to include the following headers in the application:

  • Authorization: bearer tu_token (This header must contain the authentication token of your application, preceded by the word "Bearer").
  • Content-Type: application/json (Indicates that the format of the data sent in the request body is JSON).

Remember that the amount must be the sum of the fields amountWithTax, amountWithoutTax, tax, service and tip.

  • amount = amountWithoutTax + amountWithTax  + tax + service + tip

Although the individual amounts are optional, at least one must be present to support the amount

Important: Monetary values must be expressed in integers. That is, the dollar value is multiplied by 100, for example:

    • 1 dollar = 100
    • $1.50 = $150
    • 10 dollars = 1000
    • $12.68 = 1268

Example: To collect $3.15, divided into $1 with a 15% tax and $2 without tax, you would send the following structure:

				
					{
    "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"
}
The following are basic examples of JSON objects that you can use to prepare a collection:
  • Charge of $1 dollar without taxes:
				
					{
    "responseUrl":"https://tu-dominio.com/ConfirmacionPago",
    "amount": 100,
    "amountWithoutTax": 100,
    "clientTransactionId": "ID_UNICO_X_TRANSACCION-002"
}
  • Charge of $1 dollar with 15% tax:
				
					{
    "responseUrl":"https://tu-dominio.com/ConfirmacionPago",
    "amount": 115,
    "amountWithTax": 100,
    "tax": 15,
    "clientTransactionId": "ID_UNICO_X_TRANSACCION-003"
}

These are the basic objects, but it is always recommended to include any additional data that your system requires.

JavaScript Buttom/Prepare Service Call Example

To make a POST call using AJAX in JavaScript, you first need to include the jQuery library in the header of your HTML document. Here's how to do it with the latest version of jQuery:

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

Below is an example script of how to make a POST call:

				
					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));
    }
});

Service Response

When you make the POST call, you will receive a JSON object that includes the following parameters:

  • paymentId: Payment identifier.
  • payWithPayPhone: URL to redirect the user to make the payment through the PayPhone app.
  • payWithCard: URL for the user to pay directly with his credit or debit card.

Considerations: It is important to keep in mind that the links generated by the service have a time window of 10 minutes to be used. After this period, the link will expire and it will be necessary to generate a new one.

Note: Be sure to redirect the user to the payment URL from your configured web domain, otherwise authorization will not be granted.

Customers can pay with Visa and Mastercard credit and debit cards, as well as with Payphone. Regardless of the payment method, you will receive the same transaction response, either approved or declined.

Consult transaction response

Upon completion of the payment process, the system will automatically redirect the user to the web page you have configured as the response URL. This page will receive two important parameters in its URL:

  1. id An integer (int) representing the unique transaction identifier assigned by PayPhone.
  2. clientTransactionId A string corresponding to the transaction identifier you defined when initiating the payment process.

It is crucial to capture these parameters in order to make a request to the Confirm method. This method will provide you with detailed information about the transaction, including whether it was successful or not. With this information, you will be able to display a message to the user confirming the result of the operation.

PHP Example to Retrieve ID and ClientTransactionID 

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

API Buttom Confirm

To use the Confirm method, you must make a POST request to the following URL:

  • https://pay.payphonetodoesposible.com/api/button/V2/Confirm

The body of the request must be a JSON object containing the following parameters, which are received in the response URL:

				
					{
    "id": int,
    "clientTxId": "string"
}

It is essential to include the following headers in the application:

  • Authorization: Bearer TU_TOKEN (This header must contain the authentication token of your application, preceded by the word "Bearer". This token is the same token you used when initially preparing the transaction).
  • Content-Type: application/json (Indicates that the format of the data sent in the request body is JSON).

Response Parameters

You will receive a JSON response with the transaction details, including:

Name Description
statusCode
Transaction status code (2=Canceled, 3=Approved).
transactionStatus
Transaction status (Approved or Canceled).
clientTransactionId
Transaction identifier that you sent in the request.
transactionId
Transaction identifier assigned by Payphone.
authorizationCode
Bank authorization code.
email
The e-mail address registered in the payment form.
phoneNumber
Telephone number registered in the form for payment.
document
ID number registered in the form for payment.
amount
Total amount paid.
cardType
Type of card used (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
Deferred code used by the user.
deferredMessage
Deferred message.
deferred
Indicates whether a deferral (Boolean) was used.
message
Error message, if applicable
messageCode
Message code.
currency
Currency used for payment.
reference
Reason for transaction
optionalParameter3
Optional parameter
optionalParameter4
Name of cardholder if paying by credit card
storeName
Name of the store I charge
date
Collection date in ISO 8601 format
regionIso
Country codes in ISO 3166-1
transactionType
Transaction Type

Example: When you make a payment of $3.15, you will receive the following structure:

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

Example of Buttom/Confirm Service Call in PHP

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

				
					//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;

And that's it! If you have reached this point, congratulations! Your integration is complete. In the next section, we will explain how to test and move to production.

Video Tutorial

Below, you will find a video where you can see how to integrate our Payment Button in just a few minutes.

Testing and production

As mentioned above, at Payphone you have full control over the process. You are the one who decides how to run the tests and when to go to production. You don't need any certification process, and you can publish your application independently. Here is a guide to make this process easier for you.

Your application, created on the Payphone Developer site, has two preset environments: "TEST" and "PRODUCTION". By accessing the configuration of your application on our Developers site, you will be able to select the environment you wish to use.

Test Environment:
A secure environment to develop and test your application without affecting your users. 

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.

Once your application is in production, the process is complete.

Congratulations on integrating the payment button of Payphone!