Implement a PayPal Checkout Server Integration

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 PayPal Checkout server integration makes calls from your server to the PayPal API. A server integration provides greater flexibility in the types of payments you can set up and execute. For example, with a PayPal Checkout server integration you can immediately authorize funds in a buyer's account and capture the payment later, set up recurring billing, issue refunds, and so on. This integration is well-suited for large merchants and partners.

Note: This guide shows you how to upgrade your existing client integration to a server integration by swapping out the calls that set up and execute payments.

How a server integration works

The following diagrams show you how a server integration works with the PayPal API to set up and execute payments.

Set up the payment

1. Your buyer clicks the PayPal button.
2. The PayPal button calls your server.
3. Your server calls the PayPal API to set up the payment.
4. The button launches the checkout flow in the buyer's browser.

Tip: Try making test calls with the interactive API Explorer.

Execute the payment

1. Your buyer clicks the Pay Now button in the PayPal Checkout flow.
2. Buyer reviews their order and clicks the Agree & Pay button.
3. The browser calls your server.
4. Your server calls the PayPal API to execute the payment.
5. You show a payment receipt page to the buyer.

Server integration upgrade steps

The server integration upgrade includes these steps:

1. Set up your client to call your server
2. Set up your server to call the PayPal API
3. Test it
4. Go live

1. Set up your client to call your server

In this step, modify your existing client-side code to call your server to set up and execute the payment.

Set up the payment

To set up your payment, follow these steps along with the corresponding comments in the example code.

1. Add a payment callback function to the button, which is called when a buyer clicks the button.
2. In the payment callback function, call actions.request.post() with your server URL.
3. Return res.id from the response with the Payment ID returned from your server.

Execute the payment

To execute the payment, follow these steps with the corresponding comments in the example code.

1. Add an onAuthorize callback function to the button, which is called after the buyer authorizes the payment on PayPal.
2. In the onAuthorize callback, call actions.request.post() with your server URL, and pass the data.paymentID and data.payerID parameters to the server.
3. Show the buyer a confirmation message.

<script src="https://www.paypalobjects.com/api/checkout.js"></script>

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

<script>
  paypal.Button.render({
    env: 'sandbox', // Or 'production'
    // Set up the payment:
    // 1. Add a payment callback
    payment: function(data, actions) {
      // 2. Make a request to your server
      return actions.request.post('/my-api/create-payment/')
        .then(function(res) {
          // 3. Return res.id from the response
          return res.id;
        });
    },
    // Execute the payment:
    // 1. Add an onAuthorize callback
    onAuthorize: function(data, actions) {
      // 2. Make a request to your server
      return actions.request.post('/my-api/execute-payment/', {
        paymentID: data.paymentID,
        payerID:   data.payerID
      })
        .then(function(res) {
          // 3. Show the buyer a confirmation message.
        });
    }
  }, '#paypal-button');
</script>

2. Set up your server to call the PayPal API

In this step, you'll add your REST API credentials to your server, and then set up the server to call the PayPal API to set up and execute the payment.

Note: The following code example uses Node.js, but you can use any web platform or language to call the PayPal API. To install node, see Node.js downloads.

Add REST credentials to your server

In the CLIENT and SECRET variables, add your sandbox client ID and secret. For testing purposes, these variables are automatically entered for you in the example code.

Set up the payment

To set up your payment, follow these steps along with the corresponding comments in the example code.

1. Set up a URL to handle requests from the client. This URL is called by the client when the buyer clicks the PayPal button.
2. Call the /v1/payments/payment REST API with your client ID and secret and your payment details to create a payment ID.
3. Return the payment ID to the client as JSON.

Note: For available options, see Set up a payment in the Integration Guide or the Create payment method in the Payments API reference.

Tip: Make test calls to the API using the interactive API Explorer.

Execute the payment

To execute the payment, follow these steps along with the corresponding comments in the example code.

1. Set up a URL to handle requests from the client. This URL is called by the client when the buyer approves the payment on PayPal.
2. Get the paymentID and the payerID from the request body.
3. Call the /v1/payments/payment/PAY-XXX/execute REST API with your client ID and secret, payer ID, and the payment ID. Pass any updated values, such as total, shipping, tax, and so on.
4. Return a success response to the client.

Note: For available options, and the full list of payment details returned by actions.payment.execute(), see Execute payment in the Payments API reference.

var express = require('express');
var request = require('request');
// Add your credentials:
// Add your client ID and secret
var CLIENT =
  'AUJoKVGO3q1WA1tGgAKRdY6qx0qQNIQ6vl6D3k7y64T4qh5WozIQ7V3dl3iusw5BwXYg_T5FzLCRguP8';
var SECRET =
  'EOw8LNwDhM7esrQ3nHfzKc7xiWnJc83Eawln4YLfUgivfx1LGzu9Mj0F5wlarilXDqdK9Q5aHVo-VGjJ';
var PAYPAL_API = 'https://api-m.sandbox.paypal.com';
express()
  // Set up the payment:
  // 1. Set up a URL to handle requests from the PayPal button
  .post('/my-api/create-payment/', function(req, res)
  {
    // 2. Call /v1/payments/payment to set up the payment
    request.post(PAYPAL_API + '/v1/payments/payment',
    {
      auth:
      {
        user: CLIENT,
        pass: SECRET
      },
      body:
      {
        intent: 'sale',
        payer:
        {
          payment_method: 'paypal'
        },
        transactions: [
        {
          amount:
          {
            total: '5.99',
            currency: 'USD'
          }
        }],
        redirect_urls:
        {
          return_url: 'https://example.com',
          cancel_url: 'https://example.com'
        }
      },
      json: true
    }, function(err, response)
    {
      if (err)
      {
        console.error(err);
        return res.sendStatus(500);
      }
      // 3. Return the payment ID to the client
      res.json(
      {
        id: response.body.id
      });
    });
  })
  // Execute the payment:
  // 1. Set up a URL to handle requests from the PayPal button.
  .post('/my-api/execute-payment/', function(req, res)
  {
    // 2. Get the payment ID and the payer ID from the request body.
    var paymentID = req.body.paymentID;
    var payerID = req.body.payerID;
    // 3. Call /v1/payments/payment/PAY-XXX/execute to finalize the payment.
    request.post(PAYPAL_API + '/v1/payments/payment/' + paymentID +
      '/execute',
      {
        auth:
        {
          user: CLIENT,
          pass: SECRET
        },
        body:
        {
          payer_id: payerID,
          transactions: [
          {
            amount:
            {
              total: '10.99',
              currency: 'USD'
            }
          }]
        },
        json: true
      },
      function(err, response)
      {
        if (err)
        {
          console.error(err);
          return res.sendStatus(500);
        }
        // 4. Return a success response to the client
        res.json(
        {
          status: 'success'
        });
      });
  }).listen(3000, function()
  {
    console.log('Server listening at http://localhost:3000/');
  });
// Run `node ./server.js` in your terminal

For information on setting up payment notifications, see Webhooks.

Next, test your button in the sandbox.

3. Test it

To test your server upgrade, run several test transactions and verify them in the sandbox.

Run test transactions

Complete a test transaction:

1. Click your PayPal button.
2. Log in using your sandbox test buyer account.
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're ready to launch your new button into production.

4. Go live

To launch your button into production, you'll replace the sandbox credentials with live credentials in your script, and then run and verify a live transaction.

Get live REST API credentials

To generate REST API credentials for the live environment:

1. Log into the Developer Dashboard with your PayPal account credentials. If you don't have an account, you can click on the sign up option.
2. On My Apps & Credentials, click the toggle to Live.

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

   Note: You can only create live apps with a Business account. For more details, see Get Started.

4. Type a name for your app and click Create App. The app details page opens and displays your credentials.
5. Copy and save the client ID and secret for your app.
6. Review your app details, make updates as necessary, and save your app.

Set up the button

1. Enter your live client ID and secret into the code. Under paypal.Button.render():

   • Set env to production.
   • Enter the live client ID that you copied earlier.

   var express = require('express');
   var request = require('request');
   
   // Add your credentials:
   // Add your client ID and secret
   var CLIENT = //Enter your live client ID;
   var SECRET = //Enter your secret;
   
   var PAYPAL_API = 'https://api-m.sandbox.paypal.com';
   

2. Change the PAYPAL_API endpoint to: https://api-m.paypal.com.

Run live transactions

Complete a live transaction:

1. Click your PayPal button.
2. Log in 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.

Complete negative testing

To ensure your checkout flow correctly handles funding source errors, add a redirect that enables your buyer to choose an alternate funding source. For more information, see Manage funding source failure. To complete negative testing, see Negative Testing for REST API.

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 your real PayPal buyer account to confirm that the funds have been sent.

Congratulations. You have completed the server upgrade for your PayPal Checkout integration.

Next

With a PayPal Checkout server integration, you can make advanced payments by calling the REST APIs directly from your server. For more information, see:

• Search Payment Details
• Authorize Payment Now and Capture Funds Later
• Void an Authorization
• Issue Refunds
• Create Orders
• Create Billing Plans and Agreements

See also

You can optionally implement PayPal Checkout customization options and best practices tips:

• Customize the Checkout Button
• Customize the Checkout Flow
• Manage funding source errors
• Handle checkout flow errors
• PayPal Checkout Best Practices