Add the Buttons

SDKLegacyLast updated: September 6th 2023, @ 12:43:42 pm

Add Smart Payment Buttons to your website. This integration guide helps you:

Render the PayPal Smart Payment Buttons
Set up a one-time transaction and immediately capture the funds into your account
Test the button and take it live on your site

Notes:
This integration uses the PayPal JavaScript SDK. If you're looking for the checkout.js integration, see the archived Checkout integration guide.
(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.

1. Set Up Your Development Environment

To generate REST API credentials for the sandbox and live environments:

with your PayPal account.
Under the DASHBOARD menu, select My Apps & Credentials.
Make sure you're on the Sandbox tab to get the API credentials you'll use while you're developing code. After you test and before you go live, switch to the Live tab to get live credentials.
Under the App Name column, select Default Application, which PayPal creates with a new Developer Dashboard account. Select Create App if you don't see the default app.

Note: To get credentials for the Marketplaces and Platforms product, see that Get Started page.

Note: (US and Canada) If you need help setting up your account or environment, reach out to our Sales team. They can help you with the account set up and approval process and connecting with a PayPal integration engineer. Call 855-787-1007.

Important: Venmo is not supported in the sandbox.

2. Add the PayPal JavaScript SDK to your web page

This integration uses the PayPal JavaScript SDK to integrate the Smart Payment Buttons into your site without any server code.

<!DOCTYPE html>

<head>
  <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Ensures optimal rendering on mobile devices. -->
</head>

<body>
  <script
    src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID"> // Required. Replace YOUR_CLIENT_ID with your sandbox client ID.
  </script>
</body>

Default values for the PayPal JavaScript SDK

To streamline the integration, the PayPal JavaScript SDK uses default values for parameters you don't pass. Depending on how you want your integration to work, you might want to override these default values by explicitly passing a different value. A few common parameters you might override:

currency - The PayPal JavaScript SDK defaults to USD.
intent - The PayPal JavaScript SDK defaults to capture, which results in the capturing the funds immediately. If you want to authorize funds immediately but capture the funds later, you have to explicitly pass authorize as the intent for the transaction.

3. Render the Smart Payment Buttons

Render the PayPal Smart Payment Buttons to a container element on your web page.

<body>
  <script
    src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID"> // Required. Replace YOUR_CLIENT_ID with your sandbox client ID.
  </script>

  <div id="paypal-button-container"></div>

  <script>
    paypal.Buttons().render('#paypal-button-container');
    // This function displays Smart Payment Buttons on your web page.
  </script>
</body>

Important: If you already added the PayPal script from the Try the buttons demo, swap .render('body') for the element into which you want to render the PayPal buttons.

Button placement and rendering tips

If you're using the default vertical button layout, the buttons might take up a dynamic amount of height on your web page, depending on the buttons that are rendered, the funding source chosen by the user, and other features such as Standard Card Fields. Ensure that Smart Payment Buttons render inside an element that does not have a fixed height.
To create the best checkout experience for your customers and increase your conversion rates, consider where you'll place the PayPal Checkout button on your site. See Choose the optimal button location to learn more. Also, learn how to optimize rendering the PayPal buttons.

4. Set up the transaction

Implement the createOrder function, which is called when the buyer clicks the PayPal button. This step:

Calls PayPal using actions.order.create() to set up the details of a one-time transaction, including the amount, line item details, and more.
Launches the PayPal Checkout window so the buyer can log in and approve the transaction on paypal.com.

<script>
  paypal.Buttons({
    createOrder: function(data, actions) {
      // This function sets up the details of the transaction, including the amount and line item details.
      return actions.order.create({
        purchase_units: [{
          amount: {
            value: '0.01'
          }
        }]
      });
    }
  }).render('#paypal-button-container');
</script>

For the list of parameters you can pass to actions.order.create() to set up the transaction, and example responses, see Create order in the Orders API reference.

Note: You can also call from your server to set up a transaction. Calling from your server provides more control over the payment.

5. Capture the transaction

Implement the onApprove function, which is called after the buyer approves the transaction on paypal.com. This function:

Calls PayPal using actions.order.capture() to capture the funds from the transaction.
Shows a message to the buyer to let them know the transaction is successful.

<script>
  paypal.Buttons({
    createOrder: function(data, actions) {
      // This function sets up the details of the transaction, including the amount and line item details.
      return actions.order.create({
        purchase_units: [{
          amount: {
            value: '0.01'
          }
        }]
      });
    },
    onApprove: function(data, actions) {
      // This function captures the funds from the transaction.
      return actions.order.capture().then(function(details) {
        // This function shows a transaction success message to your buyer.
        alert('Transaction completed by ' + details.payer.name.given_name);
      });
    }
  }).render('#paypal-button-container');
  //This function displays Smart Payment Buttons on your web page.
</script>

For the list of order details you receive from actions.order.capture(), see Capture payment for order in the Orders API reference.

Note: You can also call from your server to capture a transaction.

6. Test the integration

To test your buttons, complete these steps.

Run test transactions

Log in to the Developer Dashboard and create a new sandbox test account.
Click the Smart Payment Buttons. Make sure to also test the credit card buttons.
Log in to PayPal using the test buyer account you created.
Complete a transaction.

Verify test transactions

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

Log in to the sandbox using your sandbox merchant account to confirm that the funds have been received (minus any processing fees).
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.

7. Go live

To launch your button into production, complete these steps:

Create a PayPal business account

Note: If you already have a PayPal business account, skip to Replace sandbox credentials with live credentials.

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

Replace sandbox credentials with live credentials

Change the https://www.paypal.com/sdk/js script tag to use your live client ID.

  <script
    src="https://www.paypal.com/sdk/js?client-id=LIVE_CLIENT_ID">
  </script>

Change any API calls from https://api-m.sandbox.paypal.com to https://api-m.paypal.com and use your production client ID and secret for these calls.

  // Add your client ID and secret
    var PAYPAL_CLIENT = 'PAYPAL_LIVE_CLIENT';
    var PAYPAL_SECRET = 'PAYPAL_LIVE_SECRET';

  // Point your server to the PayPal API
    var PAYPAL_ORDER_API = 'https://api-m.paypal.com/v2/checkout/orders/';

Test a live transaction

Click the PayPal Smart Payment Buttons.
Log in to the PayPal window using a buyer account. If you don’t have a PayPal buyer account, go to the PayPal website and click Sign Up.
Complete a transaction.

Verify live transactions

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

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

You have completed the basic PayPal Smart Payment Buttons integration. Your new buttons set up and capture simple, one-time payments.

Add these features to your integration:

Try the interactive Smart Payment Buttons demo

Test the button code in the interactive demo