Redirection payment button

What is the Payphone payment button?

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

Payment Button Flow

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

You prepare the transaction (you tell Payphone the customer's details, the amount to be charged, taxes and general details of the transaction).
Payphone gives you a URL where your payment button will be ready. You must redirect your customer to this url.
The customer pays by credit card, debit card, gift card or credit card.
Payphone calls your server where you must 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, which we divide into two categories: Commercial Requirements y Development Requirements.

Business Requirements:

The establishment that is to receive the payments must be registered with Payphone Business. To start the registration you can do click here.
With the shop active and ready to transact, you must create a user of type "developer"which we will explain below.

Development Requirements:

You must configure on our developer website "Payphone Developer". your development environment where you can obtain all your authentication tokens with which you identify yourself in the Payphone services.

Create developer user

Log in to your page Payphone Businessand log in with your ruc, email and password, (if you don't have access, the company administrator can log in and create your user) and go to the "Users". then select "Create User":

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

With this process in place, the user developer can start the implementation.

Payphone Developer Page

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

1. Log in as a developer

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

2. Create Payphone Application:

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

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

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

Web domain: The url of your website that will connect to the Payphone button. ONLY THE WEB DOMAIN HAS ACCESS TO THE PAYPHONE 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 status of the transaction will be notified.

Finally select your application type as WEB

Press Save

Get Authentication Token

With the application configured you must click on 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. By 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 be charged, user data, and additional fields. In the 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:

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

with an object of type Json with the following parameters:

Name	Description	Data type	Optional
amount	Total value of the invoice to be collected, is the sum of amountWithTax, amountWithoutTax, Tax, service and tip.	Int
amountWithoutTax	Value not taxed.	Int	X - only in case VAT is charged, mandatory if no VAT is charged
amountWithTax	Taxable value, excluding tax.	Int	X - only in case values are charged without VAT, mandatory if values are charged with VAT.
tax	Value of the tax.	Int	X - only in case 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 to be collected /e.g. USD	String	X
clientTransactionId	Transaction identifier, you must generate it, it is a unique identifier.	String
storeId	Identifier of the branch that performs the collection, this parameter can be obtained in the "Company request" section of the PayPhone Developer page, in the list button.	String	X
reference	Payment reference you can send.	String	X
phoneNumber	Customer's phone number, if you don't send it the button will ask the customer for it.	String	X
email	Customer's email address, if you do not send it the button will request it from the customer.	String	X
documentId	Customer ID number, if you do not send it the button will request it from the customer.	String	X

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

				
					{
"responseUrl": "http://localhost/",
"amount": 112,
"amountWithTax": 100,
"tax": 12,
"clientTransactionId": "identificadorUnico002"
}

Charge of $1 dollar without tax:

				
					{
"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, in case you have them (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.

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

paymentIdPayment identifier.
payWithPayPhoneURL to which you must redirect the user to make the payment using the PayPhone app.
payWithCardURL to which you must redirect the user to make the payment directly with their credit or debit card.

Customers can pay with their Visa and Mastercard credit and debit cards, gift cards or their Payphone balance. 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 authorised).

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

Consult transaction response

Once the customer completes the transaction, the system will redirect them to your REPLY 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 get the Id and ClientTransactionID with php:

				
					<?php
$transaccion = $_GET["id"];
$client = $_GET["clientTransactionId"];
?>

To check the status of the transaction, 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 Payphone service that you have received the response from the payment button and also checks 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 parameter and ClientTransactionID. Don't 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 authorisation 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 marking.
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 the deferrals.
deferredMessage	Deferred message.
deferred	Boolean variable indicating whether a deferral is used or not.
message	In case of an error, the error is displayed in this parameter. You can consult the error catalogue by clicking here.
messageCode	Message code.
currency	Currency used for payment.
optionalParameter1	Optional parameter

Here 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've reached this point, congratulations, your integration is complete, in the next section we'll tell you how to test and move to production.

Testing and production

As we have already mentioned, you have full control over Payphone, and it is you who decides how to run the tests and go into 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 "TESTS" y "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 behaviour 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 on integrating your Express Checkout.

Did you know that...