Did you know that...

We have plugins for different platforms, they can be integrated in minutes.

Visit payphone.app

Redirection payment button

What is the payment button Payphone?

Welcome! in a few minutes and following this tutorial you will be able to have active and functional the payment button of Payphone. The payment button is composed of two REST web services that you can call with Json structure using the programming language of your choice. The payment button Payphone allows you to receive payments with Visa and Mastercard credit and debit cards, as well as gift cards and balance Payphone from your customers using our app.

Payment Button Flow

To receive payments with our gateway just follow these simple steps:

  1. You prepare the transaction (you indicate to Payphone the customer's data, the amount to be charged, taxes and general data of the transaction).
  2. Payphone gives you a URL where your payment button will be ready. You must redirect your customer to this url.
  3. The customer makes the payment by credit card, debit card, gift card or credit card.
  4. Payphone calls your server where you should consult the result of the transaction.

Video Tutorial

In the following video you can see how in a few minutes you can integrate our payment button.

Environment configuration

To implement the payment button you must meet certain requirements that we divide into two categories: Business Requirements and Development Requirements.

Business Requirements:

  • The establishment that is going to receive the payments must be registered in Payphone Business. To start the registration you can click here.
  • With the store active and ready to transact, you must create a "developer"type user, which we will explain later.

Development Requirements:

  • You must configure in our website for developers "Payphone Developer" your development environment where you can obtain all your authentication token with which you identify yourself in the services of Payphone.

Create developer user

Go to Payphone Business, and log in with your ruc, email and password, (if you do not have access, the company administrator can log in and create your user) and go to the "Users" section and then select "Create User":

Click on users

Enter all the developer's data in the form, don't forget that in the "Roles" field you must enter "Developer". (The administrator must provide the e-mail address and password entered).

With this process ready, the user developer can start the implementation.

Page Payphone Developer

Configuring the development environment allows you to have full control over the transactions made through Payphone. Please follow the steps below:

1. Login as a developer

Go to https://appdeveloper.payphonetodoesposible.com/ and log in with your developer user credentials (Ruc, email and password).

Developer

2. Create Application Payphone:

The development applications Payphone allows you to configure your test environment, connection parameters or test users, and helps you to obtain your authentication credentials such as the token.

To create your application click on the "+" at the top:

A form will open where you must enter the fields of your application, and complete mainly:

  • Web domain: The url of your website that will connect to the Payphone button. ONLY THE WEB DOMAIN HAS ACCESS TO THE PAYMENT BUTTON, if you try to call the payment button from an address other than your web domain, it will not give you access.
  • Response Url: This is the url where the transaction status will be notified.

Finally select your application type as WEB

Press Save

Obtain authentication token

With the application configured you must click the top menu on the credentials tab, and you will have the button to copy your token...

Prepare transaction

To implement the payment button you must consume two web services through POST calls by sending a Json object. Consuming the two methods, your payment button will be ready in a few minutes. The first method is the "PREPARE" where the payment button is prepared, indicating the amount to charge, user data, and additional fields. In response to that call, our web service will deliver a URL where the payment button is ready.

Prepare Method

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

with an object of type Json with the following parameters:

Name Description Data type Optional
amount
Total value of the invoice receivable, is the sum of amountWithTax, amountWithoutTax, Tax, service and tip.
Int
amountWithoutTax
Value not taxed.
Int
X - only if VAT is charged, it is mandatory if no VAT is charged
amountWithTax
Taxable value, without tax included.
Int
X - only if values are charged without VAT, mandatory if values are charged with VAT.
tax
Value of the tax.
Int
X - only if values are charged without VAT, mandatory if values are charged with VAT.
service
Value of the service.
Int
X
tip
Value of the tip.
Int
X
currency
Currency receivable /e.g. USD
String
X
clientTransactionId
Transaction identifier, you must generate it, it is a unique identifier.
String
storeId
This parameter can be obtained in the "Company Request" section of the PayPhone Developer page, in the list button.
String
X
reference
Payment reference that you can send.
String
X
phoneNumber
Customer's phone number, if you don't send it, the button will request it to the customer.
String
X
email
Customer's email, if you do not send it the button will request it to the customer.
String
X
documentId
Customer identification number, if you do not send it the button will request it to the customer.
String
X

The values to be charged are integers and must be multiplied by 100, for example $1 dollar = 100. Below you can see an example of charging $1 dollar with tax.

				
					{
"responseUrl": "http://localhost/",
"amount": 112,
"amountWithTax": 100,
"tax": 12,
"clientTransactionId": "identificadorUnico002"
}
  • Charge of $1 dollar without taxes:
				
					{
"responseUrl":"http://localhost/",
"amount": 100,
"amountWithoutTax": 100,
"clientTransactionId": "identificadorUnico001"
}

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:

				
					<?php
$transaccion = $_GET["id"];
$client = $_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.

The method confirms to the service Payphone that you received the response from the payment button and also queries the result of the transaction. You must make a POST call to the following address: https://pay.payphonetodoesposible.com/api/button/V2/Confirm with the ID and ClientTransactionID parameter. Do not forget to attach your authentication token in the header.

 

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

 

The response parameters you will receive are as follows:

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:

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

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.

Testing and production

As we have already told you in Payphone all the control is yours, and you are the one who decides how to run the tests and go to production. You don't need any certification process and you can publish yourself without any problem. Here we give you a guide.

Your application created on the Payphone Developer site has two pre-established environments which are "TESTING" and "PRODUCTION". When you enter the configuration of your application from our Developers site you can select the environment you need.

In testing all your transactions will be approved but no transactions will be connected to any bank processor, so you can use your cards and no charge will be made, or any valid Visa or Mastercard.

In production environment the behavior is the same, but if the bank connection is made, the transactions are already real and you have your payment button active.

With your application in production the process is complete, congratulations for integrating your Express Checkout.