checkout

PayPal Checkout Integration Guide

A client integration is the quickest way to integrate PayPal Checkout. It doesn't require a web server to set up and execute payments. Instead, the PayPal Checkout button sets up and executes payments directly from your browser.

Note: For advanced payment options, such as authorization and capture, recurring billing, and issuing refunds, complete the steps in this guide and then see Implement a Server Integration.

To create the best checkout process for your customers and increase your conversion rates, consider where you will place the PayPal Checkout button on your site. See Choose the optimal button location to learn more.

How a client integration works

A client integration works like this:

create client

  1. Your buyer clicks on a PayPal button.
  2. The PayPal button calls the PayPal API to set up the payment.
  3. The button starts the checkout flow in the browser.

Developer video

How to integrate PayPal Checkout in a typical eCommerce website

1. Get the code

Before you begin your PayPal Checkout integration, make sure you meet the prerequisites.

You'll use this fully annotated version of the script to build upon the code snippet from the Quick Start. Take a moment to familiarize yourself with the commented sections, which we'll walk you through one section at a time. Click the button in the upper right corner of the sample to grab the script and place it on your web page.

<div id="paypal-button"></div>
<script src="https://www.paypalobjects.com/api/checkout.js"></script>
<script>
  paypal.Button.render({
    // Configure environment
    env: 'sandbox',
    client: {
      sandbox: 'demo_sandbox_client_id',
      production: 'demo_production_client_id'
    },
    // Customize button (optional)
    locale: 'en_US',
    style: {
      size: 'small',
      color: 'gold',
      shape: 'pill',
    },

    // Enable Pay Now checkout flow (optional)
    commit: true,

    // Set up a payment
    payment: function(data, actions) {
      return actions.payment.create({
        transactions: [{
          amount: {
            total: '0.01',
            currency: 'USD'
          }
        }]
      });
    },
    // Execute the payment
    onAuthorize: function(data, actions) {
      return actions.payment.execute().then(function() {
        // Show a confirmation message to the buyer
        window.alert('Thank you for your purchase!');
      });
    }
  }, '#paypal-button');

</script>

2. Set up a payment

In this first step, you'll work with the // Set up a payment section of the script.

The payment method is called when your buyer clicks the PayPal button. In the returned actions.payment.create() function, pass in payment options to customize the payment. Start with the basics, such as the total and currency:

// Set up a payment
payment: function(data, actions) {
  return actions.payment.create({
    transactions: [{
      amount: {
        total: '0.01',
        currency: 'USD'
      }
    }]
  });
}

Tip: As a best practice, add line item details, such as shipping, tax, handling fees, insurance, and so on. Your buyer sees the individual charges when they complete their purchase. For example:

// Set up a payment
payment: function(data, actions) {
  return actions.payment.create({
    transactions: [{
      amount: {
        total: '30.11',
        currency: 'USD',
        details: {
          subtotal: '30.00',
          tax: '0.07',
          shipping: '0.03',
          handling_fee: '1.00',
          shipping_discount: '-1.00',
          insurance: '0.01'
        }
      },
      description: 'The payment transaction description.',
      custom: '90048630024435',
      //invoice_number: '12345', Insert a unique invoice number
      payment_options: {
        allowed_payment_method: 'INSTANT_FUNDING_SOURCE'
      },
      soft_descriptor: 'ECHI5786786',
      item_list: {
        items: [
        {
          name: 'hat',
          description: 'Brown hat.',
          quantity: '5',
          price: '3',
          tax: '0.01',
          sku: '1',
          currency: 'USD'
        },
        {
          name: 'handbag',
          description: 'Black handbag.',
          quantity: '1',
          price: '15',
          tax: '0.02',
          sku: 'product34',
          currency: 'USD'
        }],
        shipping_address: {
          recipient_name: 'Brian Robinson',
          line1: '4th Floor',
          line2: 'Unit #34',
          city: 'San Jose',
          country_code: 'US',
          postal_code: '95131',
          phone: '011862212345678',
          state: 'CA'
        }
      }
    }],
    note_to_payer: 'Contact us for any questions on your order.'
  });
},

A successful call to the Payments API returns confirmation of the transaction, with the created state and a payment ID that you can use in subsequent calls. For a complete list of payment options and returned values, see Create payment in the Payments API Reference.

Tip Try it in the interactive code demo.

3. Execute the payment

In the second step, you work with the // Execute the payment section of the script.

The onAuthorize method is called after your buyer logs in and authorizes the payment. After the returned action.payment.execute() function, customize the script to show your buyer a confirmation message, such as "Thank you for your purchase!", or redirect the buyer to a confirmation web page.

// Execute the payment
onAuthorize: function(data, actions)
{
  return actions.payment.execute().then(function()
  {
    // Show a confirmation message to the buyer
    window.alert('Thank you for your purchase!');
  });
}
Tip: Try an example confirmation message in the interactive code demo.

A successful response returns confirmation of the transaction, with the approved state and a transaction ID. See the complete list of response values in the Payments API Reference.

For information on setting up payment notifications, see Add Webhook Notifications.

Next, test your button in the sandbox.

4. Test it

To test your new button, you'll complete these steps. Be sure you've first met the prerequisites.

Run test transactions

  1. Click your PayPal Checkout button.
  2. Log in to PayPal using the test buyer account you created earlier.
  3. Complete a transaction.

Verify test transactions

Verify your test transactions from both the merchant's and buyer's perspective:

  1. Log in to the sandbox using your sandbox merchant account to confirm that the funds have been received (minus any processing fees).
  2. Log in to the sandbox using your sandbox buyer account to confirm that the funds have been sent.

When your test is complete and you're satisfied with the results, you can launch your new button into production.

5. Go live

To launch your button into production, complete these steps:

  1. Create a PayPal business account.
  2. Replace sandbox credentials with live credentials.
  3. Test a live transaction.

Create a PayPal business account

Note: If you already have a PayPal business account, skip this section.

  1. Go to the PayPal home page and click Sign Up.
  2. Select Business Account and follow the on-screen instructions.

Replace sandbox credentials with live credentials

  1. From the Developer Portal, click Log into Dashboard and enter your PayPal business account email and password.

  2. Under Dashboard, click My Apps & Credentials.

  3. Click the name of the app you created earlier and select the Live tab to copy your live client ID.

  4. In the // Configure environment section of the script, set env to production and type the live client ID that you copied earlier:

    // Configure environment
    env: 'production',
      client:
        {
          production: 'LIVE_CLIENT_ID' //Enter your live client ID here
        }
    

Test a live transaction

  1. Click your PayPal Checkout button.
  2. Log in to the PayPal window using a real buyer account. If you don’t have a real PayPal buyer account, go to the PayPal website and click Sign Up.
  3. Complete a transaction.

Verify live transactions

Verify your live transactions from both the merchant's and buyer's perspective:

  1. Log in to PayPal using your real PayPal business account to confirm that the funds have been received (minus any processing fees).
  2. Log in to PayPal using a real PayPal buyer account to confirm that the funds have been sent.

Congratulations. You have completed the PayPal Checkout integration. Your new button sets up and executes simple one-time payments, all from your web page.

Next

To set up and execute advanced payments, such as authorization and capture, recurring billing, and refunds, see:

If you don't need advanced payment options, you can visit these topics to optionally customize your new button or the checkout flow:

Feedback