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:

Prepare the transaction: Provide Payphone with the details of the payment (amount to be collected, taxes and general transaction details).
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.
Payment: The customer can pay using their credit card, debit card, or balance from Payphone.
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".

Complete the form by entering all the required data and make sure to select the "Developer" role.

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

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.

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.

Prepare transaction

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

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

id An integer (int) representing the unique transaction identifier assigned by PayPhone.
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.

In the test environment, all your transactions will be approved, but will not be connected to any bank processor. This means that you can use your cards (valid Visa or Mastercard) without any actual charges being made.

Production Environment:
The actual environment where your customers will make payments. Make sure you have performed all the necessary tests before activating this environment.

In the production environment, transactions are effectively connected to the banking system, which means that the transactions are real and your payment button will be active.

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

Congratulations on integrating the payment button of Payphone!

Did you know that...