Integrate Checkout

Integrate PayPal Checkout for online payments

SDKCurrentStandardLast updated: April 6th 2022, @ 4:06:12 pm


Know before you code

  • This integration sets up online payment options using the PayPal JavaScript SDK, which presents relevant payment options to your buyers.

  • Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:

    • Email ID and password of a sandbox Personal account, to log in and test a checkout purchase.

    • Sandbox client ID of a REST app.

      Tip: Note the sandbox Business account the app corresponds to. You'll need the email ID and password for that account when you test the integration.

  • PayPal handles 3D Secure card holder authentication for standard payments integrations.

  • (UK merchants) Credit is a regulated activity in the UK. Before integrating a PayPal Credit button, you must be authorized to act as a credit broker and have a credit agreement with PayPal. For more information, contact business customer support through paypal.com or by calling 0800 358 7929.

  • Use Postman to explore and test PayPal APIs.

Technical flow

PayPal Checkout integration technical flow

  1. You add the payment buttons to your web page.
  2. Your buyer clicks a button.
  3. The button calls the PayPal Orders API to set up a transaction.
  4. The button launches the PayPal Checkout experience.
  5. The buyer approves the payment.
  6. The button calls the PayPal Orders API to finalize the transaction.
  7. You show a confirmation message to your buyer.

1. Add payment buttons

To accept payments on your website, add the PayPal JavaScript SDK code to your checkout page.

Sample JavaScript code

The client-side sample code adds payment buttons to your website that capture the payment immediately. If you need to store the resulting transaction details in a database or want to fulfill orders automatically, use the included full-stack example code instead.

You can find a complete, full-stack implementation in the GitHub repo.

  1. Client-side example
  2. Full-stack example (HTML)
  3. Full-stack example (node.js)
1<!DOCTYPE html>
2<html>
3 <head>
4 <meta name="viewport" content="width=device-width, initial-scale=1">
5 </head>
6 <body>
7 <!-- Replace "test" with your own sandbox Business account app client ID -->
8 <script src="https://www.paypal.com/sdk/js?client-id=test&currency=USD"></script>
9 <!-- Set up a container element for the button -->
10 <div id="paypal-button-container"></div>
11 <script>
12 paypal.Buttons({
13 // Sets up the transaction when a payment button is clicked
14 createOrder: (data, actions) => {
15 return actions.order.create({
16 purchase_units: [{
17 amount: {
18 value: '77.44' // Can also reference a variable or function
19 }
20 }]
21 });
22 },
23 // Finalize the transaction after payer approval
24 onApprove: (data, actions) => {
25 return actions.order.capture().then(function(orderData) {
26 // Successful capture! For dev/demo purposes:
27 console.log('Capture result', orderData, JSON.stringify(orderData, null, 2));
28 const transaction = orderData.purchase_units[0].payments.captures[0];
29 alert(`Transaction ${transaction.status}: ${transaction.id}\n\nSee console for all available details`);
30 // When ready to go live, remove the alert and show a success message within this page. For example:
31 // const element = document.getElementById('paypal-button-container');
32 // element.innerHTML = '<h3>Thank you for your payment!</h3>';
33 // Or go to another URL: actions.redirect('thank_you.html');
34 });
35 }
36 }).render('#paypal-button-container');
37 </script>
38 </body>
39</html>

Add and modify the code

  1. For a client-side only implementation, copy the client-side example code and paste it into your checkout page.
  2. For the full-stack example, follow the instructions in the GitHub repo. You'll need to install several dependencies and set up environment variables before it works.
  3. Replace test in the SDK <script src> with your own sandbox client ID from one of your REST apps. This ensures the payments will be sent to the correct account. Note which sandbox Business account corresponds to the REST app you are using.
  4. (Optional) You can include additional query string parameters to override the default values the PayPal JavaScript SDK uses. Review the JavaScript SDK reference to learn more. Example: currency defaults to USD.
  5. (Optional) You can include additional parameters during order creation. See the Orders v2 API reference request body for additional parameters. For example, extend purchase_units to include item descriptions and quantities that are part of this transaction:
    1createOrder: (data, actions) => {
    2 return actions.order.create({
    3 "purchase_units": [{
    4 "amount": {
    5 "currency_code": "USD",
    6 "value": "100",
    7 "breakdown": {
    8 "item_total": { /* Required when including the items array */
    9 "currency_code": "USD",
    10 "value": "100"
    11 }
    12 }
    13 },
    14 "items": [
    15 {
    16 "name": "First Product Name", /* Shows within upper-right dropdown during payment approval */
    17 "description": "Optional descriptive text..", /* Item details will also be in the completed paypal.com transaction view */
    18 "unit_amount": {
    19 "currency_code": "USD",
    20 "value": "50"
    21 },
    22 "quantity": "2"
    23 },
    24 ]
    25 }]
    26 });
    27 },

Other useful purchase unit parameters include:

  • A unique invoice_id that hasn't been used for a previously-completed transaction to identify the order for accounting purposes and to prevent duplicate payments.
  • A custom_id value of your choice for your system or own reference. This value is not indexed or visible to the buyer.
  1. (Optional) Style your buttons.

Step result

The payment buttons display on your website. You can now test purchases.

2. Test purchases

Test a PayPal purchase in the sandbox to see the checkout user experience and confirm money reaches the receiving Business account.

Test a purchase as a buyer

  1. On your checkout page, click the PayPal button.
  2. Log in using one of your sandbox Personal accounts.
  3. Within the PayPal checkout window, note the purchase amount.
  4. Click through and approve the purchase with the final Pay Now button. This should close the PayPal window and return to your page, where a message indicates the transaction completed.

Confirm the money entered the merchant account

  1. Log in to https://www.sandbox.paypal.com/ using the sandbox Business account that received the payment. Remember that the SDK src now uses a sandbox client ID from one of your own REST apps, and not the default test ID.
  2. In Recent Activity, confirm that the money, minus any fees, was received by this sandbox Business account.
  3. Log out of the account.

Best practices

  • Feature the PayPal button on all pages that initiate checkout.

  • Show PayPal alongside all other acceptance marks (including cards, split tender, and buy online, pickup in-store) giving it equal prominence and function for your buyers.

  • When your buyer returns to your site from PayPal, they should be able to pay and complete their order in no more than two steps.

  • Allow room on your checkout page for the Debit or Credit Card button to expand. There is a drop-down form for buyers to complete and if you place the payment buttons too low on the page, buyers might not be able to access all of the credit card fields.

    PayPal-branded credit and debit button example

  • If the Debit or Credit Card drop-down form isn't available when your buyers check out, they are presented with the PayPal guest checkout experience in a pop-up window.

Next steps

Test in PayPal sandbox, then go live in PayPal's production environment.

See also

Integration options

Reference