How to Integrate PayPal Payment Gateway in Your Website

Very often web developers have to integrate PayPal or another payment gateway in their websites. PayPal is one of the most popular online payment gateway today. That’s why every web development professional have to know how to integrate PayPal payments. However, a PayPal integration can be tricky enough to miss some important things.

We’d like to share our experience of PayPal integration. You will learn how to set up and track payments from any user to a PayPal account and how to provide money transfers to system users.

How to Integrate PayPal Payments

For PayPal integration, you can use a standard button made in your PayPal account. By pushing the button, a user links to the PayPal website automatically to finish the payment. In most cases, adding the button is enough. Although, this option doesn’t guarantee that a user makes a payment. You can track the operation result only by a PayPal account. It is absolutely inconvenient.

A worthwhile alternative to the PayPal button is an HTML-form that contains all the necessary data for making payments:

<form action="https://www.sandbox.paypal.com/cgi-bin/webscr" method="post"> 
 <div> 
 <label for="amount">Amount for transfer</label> 
 <input id="amount" type="text" /> 
 </div> 
 <input type="hidden" name="cmd" value="_donations" /> 
 <input type="hidden" name="charset" value="utf-8" /> 
 <input type="hidden" name="bussiness" value="business@paypal.acc" /> 
 <input type="hidden" name="item_name" value="Item short name" /> 
 <input type="hidden" name="currency_code" value="USD" /> 
 <input type="hidden" name="undefined_quantity" value="1" /> 
 <input type="hidden" name="return" value="https://site.com/" /> 
 <input type="hidden" name="cancel_return" value="https://site.com/" /> 
 <input type="hidden" name="notify_url" value="https://site.com/paypal/result" /> 
 <input type="hidden" name="custom" value="userId:1|orderId:25" /> 
 <input type="hidden" name="button_subtype" value="services" /> 
 <input type="hidden" name="no_note" value="1" /> 
 <input type="hidden" name="no_shipping" value="1" /> 
 <input type="hidden" name="rm" value="" /> 
 <div> 
 <input type="submit" value="Transfer" /> 
 </div> 
</form>

Let’s create a simple HTML-form with a variety of fields. All the fields can be type “hidden” with strictly defined values. In particular, take into account their specific names:

Required fields:

• amount — the transfer amount;
• cmd — the transfer type;
• charset — coding between a system and PayPal. Fixed utf-8;
• business — email from a seller PayPal account;
• currency_code — a code of the currency in international format. PayPal supports some currencies;
• return — absolute URL, where a user is redirected while pushing the return button after making a payment;
• cancel_return — absolute URL, where a user is redirected while pushing the return button after canceling the payment.

Non-required fields (recommended but not mandatory):

• undefined_quantity — a number of acquired goods;
• item_name — a transaction name;
• notify_url — absolute URL, where PayPal sends a notification about the operation result. It’s not a mandatory field, but the operation result is unavailable without it;
• custom — a simple field, that can contain up to 100 symbols of service data. It returns the same notification to the notify_url. For instance, you may use this field for transmitting the internal ID of a user who made an operation;
• rn — it is responsible for the method that a user will be returned to the website (POST or GET).

You can find more detailed information about the required fields of the HTML-form at the official website for PayPal developers. It is essential to keep in mind that PayPal charges its own commission on the payment that is paid by the recipient.

In order to track incoming payment acceptance from any user to a PayPal account, you need to configure the function of the account recharge and fix the receiving IPN notifications.

Account recharge

You can set up the function of account recharge easily. The form of payment at your website should send data as a POST-mass to the strictly fixed address:

• For Sandbox mode: https://www.sandbox.paypal.com/cgi-bin/webscr
• For Live mode: https://paypal.com/cgi-bin/webscr

IPN notifications

Let’s suppose that your website user made a payment. If your website uses the field notify_url, the PayPal server will send to the script the IPN notification with the results of the completed operation after some delay — literally in a few seconds. In other words, the mentioned URL will receive the data about the performed payment as an associative POST-mass. If a message was not delivered (the server request is not 200), then sending the message continues until the request will be 200. After every unsuccessful sending, the time between repeat attempts doubles. The maximum number of attempts is 15.

When you make a transfer via PayPal there is a mandatory field in HTML-form — currency_code. The account of a transfer recipient can use a different currency. In this case, a recipient has to choose how to deal with the transfer:

1. To accept, converting the foreign cash flows into domestic currency at the current exchange rate.

2. To accept, creating an additional account with transferred currency.

3. To decline a transfer.

For this reason, the IPN notification has the status Pending instead of Completed and the transaction will freeze up till the recipient chooses one of the options in the PayPal account. When the decision is the second option, all following similar transactions, including the earliest transfer, complete without complications.

The one important feature related to the choice of the transfer currency is that PayPal doesn’t send an IPN notification about the finished transaction. To overcome this obstacle you can save the IDs of all transactions in the website and check their status via an API.

The next step you should take is to set up the sending of money to system users. It can be implemented in different ways.

Money Transfer to System Users

Payout

One of the ways to transfer money to system users is through a Payout service. In fact, this is a mass money transfer from a system account to other accounts. It’s Mostly used for money transfer to several accounts simultaneously (up to 500 per operation).

There is a fee for money withdrawal and its rate depends on the country that relates to the account owner. In addition, the sender pays a fee.

Contrary to the official service description, complete functionality is only available in the USA and for USA citizens’ accounts. This service is also built-in REST API, but again works only in the USA

REST API

Officially, PayPal offers to web developers the use of a Paypal REST API. This option is almost functional, although it works primarily for customers from the USA. You can look at its official implementation for PHP here: https://github.com/paypal/PayPal-PHP-SDK.

In order to use the REST API, you need a valid SSL certificate. Self-signed certificates are not valid.

NVP/SOAP API

If you’d like to find a decent alternative to the PayPal REST API for countries where it doesn’t work, you can use the PayPal Classic API. This API includes an Adaptive Payment method that can be applied for a money transfer from the system account to any other account and with a note who is going to pay the transfer fee.

API implementation for PHP is available here: https://github.com/paypal/adaptivepayments-sdk-php.In fact, this is the only way to make payments for all countries except the USA. Along with REST API, the PayPal Classic API also requires an SSL certificate.

After handling the settings of account recharge and money transfer, it’s important to consider the Sandbox and Live modes.

The Features of Sandbox and Live modes

Sandbox and Live modes

There is an opportunity for the PayPal account owner to use a testing mode called Sandbox. Sandbox performs all the functions of PayPal apart from the design. The testing mode is available at sandbox.paypal.com. To use it you need a real PayPal account.

The seller and customer accounts for Sandbox are created automatically. Using these accounts, you can log into the Sandbox website. It’s better to go to developer.paypal.com and to the Dashboard section after authorization.

If it’s required, you can add new accounts, just by copying the existing accounts. You can also point out what the amount of money is in the account.

The Live mode is a working mode of PayPal. Sandbox operations never cross Live operations. Live accounts cannot be the same as Sandbox accounts and vice versa.

To work with both modes you need to set up an API.

REST API Settings

You need to create an app in the part of the REST API Apps in the section My Apps & Credentials. First, you need to add a way for IPN notifications (notify_url) and choose what particular notifications will be sent there. client_id and secret are required for authorization.

For each mode, you can point out settings separately. For example, Sandbox mode can have one URL for receiving IPN whereas Live mode can have another URL.

NVP/SOAP API Settings

In the Sandbox mode, you can directly use the NVP/SOAP API. To make an authorization you need a username, a password, a signature, and an appId. This data is available in the seller account.

appID in the Sandbox mode is always the same and its value is APP-80W284485P519543T. If you use any other appId in Sandbox mode, PayPal will return an authorization error.

In the Live mode, you can receive all the credentials in the section My Apps & Credentials of the NVP/SOAP API Apps. In this section, there are the settings that indicate what services are available for the app (Adaptive Payment is mandatory), what the payment options are (credit card, PayPal account) and a brief system description.

Working in Live mode isn’t possible without confirmation from PayPal.

Testing Integration

Before starting the work we recommend you thoroughly think about your project description. If PayPal isn’t satisfied for some reason, it can decline an app.

It’s possible to test a payment system in Live mode if you cancel the transactions. However, this can lead to some conflicts. PayPal looks at testing of service in Live mode unfavorably. If PayPal decides that you use an app for testing, then it can reverse the confirmation.

After you integrate PayPal with your website you can check how the API is working in Sandbox mode. However even if you have implemented the processing of all payments and notifications as planned, this doesn’t guarantee stability in Live mode. This is because each individual country/region will have a local PayPal department which is responsible for the payment system, and which will have it’s own rules and limitations. For example, in some countries, there is no option to transfer money from a Business account to an ordinary one. The transaction will be denied without any reason or notification.

Apart from this and before you even start, your choices are limited by the requirements for currencies.

For instance, operating Japanese Yen you can use only integers as the transaction rate. If you point out a decimal number, the transaction won’t be processed. Making payments in the Russian Federation also requires choosing only Ruble as a payment currency. All other currency values show an error.

Pay attention to another important feature called payment limit. PayPal doesn’t allow transferring an amount of more than $10,000 within one transaction in the USA. The sum is different for other countries. This limitation is set by anti-terrorism legislation issued in different regions of the world. In some cases, even transactions with an amount of $1,000 or less can be blocked because of relatively new accounts. When this happens, PayPal may refer to the author of the transfer and asks for additional details about sides and the purpose of the transaction.

Another opportunity to check integration with PayPal is an IPN simulator. This mode allows you to send a test IPN notification to control the system response to different PayPal notifications. Using an IPN simulator, you can generate any type of standard IPN notifications (account recharge, transaction canceled, awaiting acknowledgment, etc.) and send it to the server.
This mode is available here: https://developer.paypal.com/developer/ipnSimulator/.

Thus, to succeed in the integration of PayPal with your website you can:

• Add an HTML-form to the website and set up the receival of IPN notifications;
• Use the appropriate API for account recharge (without notifications);
• Use the Payout service or Paypal Classic API to transfer money to other system users;
• Thoroughly test functions of payment acceptance and money transfer in Sandbox mode;
• Test how the system works in Live mode (canceling transactions is possible).

All these measures help you to set up a payment system at the website and to control the transactions every time when users decide to transfer money.