Download the PHP package net-tools/paypal-js without Composer

net-tools/paypal-js

Client-side JS library to manage a simple e-shop with shopping cart and Paypal

Setup instructions

To install net-tools/paypal-js package, just require it through composer and insert a script tag in the HEAD section :

Please not net-tools/js-core is also required :

How to use (simple process)

If no cart handling is required, and customer data is not needed, the script is rather simple :

The expressButtons method expects a title, an amount, a category ('PHYSICAL_GOODS', 'DIGITAL_GOODS', 'DONATION') and a selector to draw the Paypal buttons into. Category parameters can be omitted (null) ; a Promise object is returned, and is resolved when the payment is done (otherwise, the promise is rejected).

See below for an example about how to use Promises.

How to use (complete process, with cart support and fluent API)

For more complex situations, such as buying several products, dealing with shipping cost, etc. we have to deal with other objects. A way to do that is to use the programmatic API (see next chapter below), through creating Customer, Cart and Order objects before calling the paypalButtons method to initiate the payment.

Another way to create the required data is to use the fluent API provided

Setting up Paypal script

First, the Paypal library must be included in a script tag (replace XXXXXX with your paypal client-ID) :

Use fluent API

First, we create a Shop object with desired currency ; the Shop object which serves as a factory to build other required objects :

Then, we begin with fluent API, starting with sell method. It accepts a Product object to represent a single item purchased. If purchasing different products, with maybe some quantities for each one, the sell method can accept an array of ProductQuantity objects (associating Product and quantity). The Product object may be created in a programmatic way or rather with the fluent API provided with Shop.product method (having title, cost and category parameters)

Then, we use Product fluent methods if needed :

To set an amount of units for a product, we use the fluent method setQuantity on the Product object returned by Shop.product. However, it's important to note that setQuantity does not return the Product object, but a new object of class ProductQuantity, thus preventing further chaining. In other words, setTax, withDescription and setSku must be called before :

The sell method returns a Sale object providing several fluent methods (to, withShipping, withDescription, withCustom_id) making it possible to chain calls to specify customer, shipping cost, description and client-side id.

Here, the Sale object is ready ; please not that all fluent API calls expect sell and its parameter are not mandatory. To prepare the Paypal buttons rendering, we call the payButtonsInside method (with target selector in DOM tree), which prepares a Payment object, on which we call its execute method to display buttons.

If some Paypal application context parameters are required, they can be set thanks to the Payment object which defines set and withApplicationContext methods :

The sell method returns a Promise which is resolved when the payment is done.

How to use (complete process, with cart support, programmatic API)

This library defines several Javasript objects to manage products, customer details, shopping cart, order and makes it possible to launch a Paypal payment window.

Setting up Paypal script

First, the Paypal library must be included in a script tag (replace XXXXXX with your paypal client-ID) :

If desired, the Paypal library loading can be differed until displaying the Paypal "buy" buttons (see below).

Create objects

First, we create a Shop object with desired currency ; the Shop object which serves as a factory to build other required objects :

Then we create the Customer and Product objects. Please not that mandatory values are passed as regular parameters to constructors, whereas not required ones are passed through an other object litteral parameter.

We create a shopping cart filled with the items (here, a product with an amount of 5 units) and proper quantities.

Finally, we create the order binding all thoses objects together

Up to now, there's no Paypal button displayed yet. We can still update the shopping cart, with relevant Cart objects methods (add, remove, setQuantity, contains, count, empty).

Then, to show the Paypal "buy now" buttons, we call the appropriate function from Shop object :

The second parameter is a selector to identify the DOM tag that will hold the paypal buttons (usually, a DIV tag) ; replace #paypal_buttons_container with any relevant selector. Upon completion of the method call, the Paypal buttons are rendered in the container, and the user can initiate the payment.

There's also a third parameter, which makes it possible to pass the application_context parameter to the Paypal API. Mainly, this is used to set it with { shipping_preference : 'NO_SHIPPING' }, thus removing some customer address text fields not needed (only when clicking on 'Pay by card' black button).

Capturing data

The above Javascript line makes it possible for the client to do it's payment, however we have no callbacks yet to catch any relevant data (such as transaction ID) or send a "thanks" email.

The paypalButton returns a Promise, that when resolved will pass data about the transaction :

Saving/restoring cart and cart items to browser storage

Since the user may browse several pages to create his order, putting several products in the shopping cart, it's required to save the current cart content between page loads, reloads etc.

The NTPaypal client library provides 3 storage strategies : cookies (cart content lost when browser is closed), localStorage (cart content never lost), sessionStorage (cart content lost when page, not browser is closed).

To save the cart content to browser storage, a Session object must be created with appropriate parameters ; then the save method is called. To restore data, restore method should be called.

Managing store (stock) and cart

Loading script

Store-related functions are in a separate javascript file :

Creating store

For a simple payment flow, creating a cart from scratch (like the example above) is enough. However, when creating an online shop, it's mandatory to deal with product stock ; it prevents user from putting in the shopping cart more units of a product than those available in the store.

Creating a Store object, with products and their quantities, is much like creating a Cart :

Since the quantities of each products may come from server-side database, creating the javascript Store object may be done with Json data :

Adding items to cart

To move items from a Store object to a previously created Cart object :

If the product with given SKU doesn't exist, an Error exception is thrown. If there's no more unit available in store, we can't move one to cart, the method addToCart return false.

Moving back items from cart to store

To remove all units of a product in the cart and put them back to store :

Dealing with quantities in cart

To update quantities of a product in the cart, there are 2 methods : one to set the amount, the other to add / remove units from current quantity in cart.

Loading cart from storage with stock management

If managing store quantities, store must be updated when loading a cart from storage, so that available quantities in store match total quantities minus quantities in cart.

To do so, Session object must be created with a Store object parameter, and a SessionStoreInterface object implementing callbacks to deal with specific cases must be passed to restore method.

Using UI

Basic knowledge

A Javascript simple cart/shipping/confirm UI is provided. It makes it possible, in 3 consecutive screens, to :

• show cart content (increment/decrement quantities of items already in cart)
• ask for shipping details
• prompt user for carrier selection (not mandatory), require Terms of Sales agreement and show Paypal buttons

Default UI language is English, but translations can be easily implemented (see provided French translations in i18n-fr.js file).

Although the UI script is quite big (in separate ui.js file), the use is rather simple, with few mandatory parameters.

Advanced use : asking user choice for carriers

With the above example, the onShippingCost callback returns a float with a defined shipping cost (may be 0) ; we can ask the user to choose its carrier. A carrier is defined by a name, a cost, a shipping_time, an image ; last 2 parameters are not mandatory.

With the above code, the user will choose the carrier through a list box.

If preferred, the user can choose the carrier by clicking on radio buttons linked to carrier icons :

To replace the list box with radio buttons and images, we add a property image (may link to an URL or can be a base64 encoded data string).

Some base64-encoded images are provided inside the carriers.json file ; it's advised to copy/paste the required images inside your code, there's no point including that big file with multiple carriers icons whereas you may only need one or two icons.

Advanced use : implement asynchronous onPaymentReceived handler

In the above example, onPaymentReceived handler is called, executed, and upon its completion, control returns to ui.js script, that will chain on cart and session cleaning.

If some asynchronous tasks must be done client side inside onPaymentReceived, cleaning cart and session before completion of this async task may be wrong.

In that case, onPaymentReceived must return a Promise that will be resolved when the ui.js can chain on cleaning (in other words, when client-side task is completed). For example, if calling some server-side script with Fetch API inside onPaymentReceived, we may call the resolve method of Promise construction as the then argument when chaining on fetch() :