Redirection payment button | PayPhone implementation

Welcome! In a few minutes and following this tutorial you can have your PayPhone payment button active and functional. You can receive credit and debit card payments and expand your options by processing gift cards and customer credit from our app.

The payment button is composed of two REST web services that you can call with a Json structure using your preferred programming language.

The payment button flow is as follows:

  1. You prepare the transaction (you tell PayPhone the customer's details, the amount to be charged, taxes and general details of the transaction).
  2. PayPhone provides you with a URL where your payment button is ready.
  3. You redirect your customer to the payment button on your website.
  4. The customer pays by credit card, debit card, gift card or credit card.
  5. PayPhone sends the result of the transaction and returns to its origin page.

Preliminary configurations

To implement the payment button you must meet the following requirements: Commercial Requirements y Development Requirements.

Business Requirements:

  • The merchant that will receive the payments must be registered with PayPhone as a PayPhone-enabled shop. To initiate registration as a PayPhone Business you can do the following 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 website "PayPhone Developer". your development environment where you can obtain all your credentials, tokens and keys with which you can identify yourself in our services and add the respective security to the process.

Create developer user

Log in to your page PayPhone Businessand 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 section of "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 developer with the e-mail address and password entered.)

Select the shop or branch that will receive the payments and press the Save button:

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

Environment configuration

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 and log in with your developer user credentials (Ruc, email and password).

2. Create PayPhone Application:

PayPhone development applications allow you to configure deployment parameters, such as platform, permissions 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 must enter the informative fields, and mainly complete them:

  • Web domainThe url of your website that will connect to the PayPhone button. ONLY THE WEB DOMAIN HAS ACCESS TO THE PAYPAL BUTTON, if you do not redirect from your web domain it will not give you authorisation.
  • Response URL: This is the url where the payment button will redirect the user and where you will receive the status of the transaction. Here you must show the customer whether the transaction was approved or rejected.

Finally select your application type as WEB

Press Save

With the application configured you can get your authentication token. In the top menu click on credentials, and you will have the button to copy your token.

Implementation of the payment button

To implement the payment button you must consume two web services via POST calls sending a Json object, nothing fancy. 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:  with an object of type Json with the following parameters:

Name Type Optional Description
amount Integer Total value receivable from customer
amountWithoutTax Integer X Subtotal value of products that do not charge tax. Only used with billing type 0% rate or mixed rate.
amountWithTax Integer X Subtotal value of taxable products without adding the tax value. Only used with VAT or mixed invoicing type.
tax Integer X Total value of taxes. Only used with VAT or mixed invoicing type.
service Integer X Value of the service
tip Integer X Value of the tip
currency String X Currency in which payment is made, e.g. "USD".
clientTransactionId String Identifier of the transaction in the client application (String assigned by your company or platform). It is a parameter that serves as identification for consultation or reverse of the transaction.
responseUrl String Response URL where PayPhone will send the customer after the transaction is completed.
cancellationUrl String X Return URL when the customer cancels the payment process.
phoneNumber String X Telephone number of the user making the payment.
email String X E-mail address of the user making the payment.
documentId String X Identity document of the user making the payment. (Identity card or passport number)
StoreId String X Id of the Store to be charged, This value is only sent when different shops or branches are managed, if different shops are not used it can be omitted. To specify which shop is doing the charging, the storeID is obtained from the PayPhone Developer websitein the company application section, column Actions, List of shops.
Reference String X Transaction reference, e.g. "Sale Blue Shoes".
AdditionalData String X Additional data you want to save from the transaction.
OptionalParameter String X Optional parameter at your disposal.
transferTo String X Parameter for shared payments. In the following link you can check how to make shared payments.

All monetary values to be sent must be multiplied by 100, e.g. $1 dollar = 100; $1.50 dollars = 150.

Examples of Json prepare method:

  • Charge of $1 dollar without tax:

"responseUrl": "http://localhost/",
"amount: 100,
"amountWithoutTax": 100,
clientTransactionId": "identifierUnique001": "clientTransactionId": "identifierUnique001".

  • I charge $1.12, where $1 dollar is the subtotal and $0.12 is the tax:

"responseUrl": "http://localhost/",
"amount: 112,
"amountWithTax": 100,
"tax: 12,
"clientTransactionId": "identifierUnique002".

These are the basic objects but we recommend you always send the user's data (ID, email and telephone) 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.

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 they must make the payment (Remember, you must redirect the user from your configured web domain, otherwise they 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.

Confirm Method

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:

$transaction = $_GET["id"];
$client = $_GET["clientTransactionId"];

//Check that the parameters are enclosed in double quotes, and not "

The confirm method helps you to confirm to PayPhone that you received the response from the payment button and to check the result of the transaction with the customer. You must make a POST call to the following address: with the ID parameter and ClientTransactionID in Json type. 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 Deferred code used by the user. Here you can find out 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.
taxes Arrangement with all taxes paid, with the fields: ("name", "amount", "value", "tax")
recap Bank identification parameter.
optionalParameter1 Optional parameter

And that's it! With those two methods your payment button is ready, enjoy PayPhone.

Video Tutorial

If you prefer to follow a more visual example, we leave you our video tutorial with all the instructions 🙂



  1. Kenet

    Hello, I have a problem, after making the whole transaction, when I wait for the confirmation I get an error alert, I always get a "Bad request", the json that returns me has the errors and says that the problem is in the identification code (clientTransactionID), I changed the identification many times and I still get the same error. Could you help me?

Leave A Comment?