PayPal Checkout Integration Guide

Important: PayPal supports these Checkout integrations:

• Smart Payment Buttons, which use the PayPal JavaScript SDK. Valid from February 2019 for new integrations.
• Checkout with checkout.js. Valid before February 2019. Customers who use checkout.js can access reference and support material in this Checkout guide. However, PayPal does not update checkout.js with new features and enhancements.

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.

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.

How a client integration works

A client integration works like this:

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.

Before you begin your Checkout integration, you must set up your development environment.

Set up your development environment

Before you can integrate Checkout, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Checkout.

1. Get the code

Use this fully-annotated script to begin your integration. Take a moment to familiarize yourself with the commented sections, which we'll walk you through one section at a time.

<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>

Tip: 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.

2. Set up a payment

In this 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

This step references 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 button, complete these steps. First, set up your development environment.

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. Log into your Developer Dashboard with your PayPal account credentials.
2. On My Apps & Credentials, click the Live toggle.

3. In the REST API apps section, click Create App.

   Note: You must have a business account to create or access live apps.

4. Click Create App.
5. Configure your live app to match the configuration of your sandbox app.
6. Copy your live client ID.

7. 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:

• Implement a Server Integration

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

• Customize the look and feel of the Checkout button
• Add more options to the Checkout flow