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 usecheckout.js
can access reference and support material in this Checkout guide. However, PayPal does not updatecheckout.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
- Your buyer clicks the PayPal button.
- The PayPal button calls your server.
- Your server calls the PayPal API to set up the payment.
- The button launches the checkout flow in the buyer's browser.
Tip: Try making test calls with the interactive API Explorer.
Execute the payment
- Your buyer clicks the Pay Now button in the PayPal Checkout flow.
- Buyer reviews their order and clicks the Agree & Pay button.
- The browser calls your server.
- Your server calls the PayPal API to execute the payment.
- 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
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.
- Add a
payment
callback function to the button, which is called when a buyer clicks the button. - In the
payment
callback function, callactions.request.post()
with your server URL. - 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.
- Add an
onAuthorize
callback function to the button, which is called after the buyer authorizes the payment on PayPal. - In the
onAuthorize
callback, callactions.request.post()
with your server URL, and pass thedata.paymentID
anddata.payerID
parameters to the server. - 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.
- Set up a URL to handle requests from the client. This URL is called by the client when the buyer clicks the PayPal button.
- Call the
/v1/payments/payment
REST API with your client ID and secret and your payment details to create a payment ID. - 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.
- 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.
- Get the
paymentID
and thepayerID
from the request body. - 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. - 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:
- Click your PayPal button.
- Log in using your sandbox test buyer account.
- 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'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:
- 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.
- On My Apps & Credentials, click the toggle to Live.
-
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.
- Type a name for your app and click Create App. The app details page opens and displays your credentials.
- Copy and save the client ID and secret for your app.
- Review your app details, make updates as necessary, and save your app.
Set up the button
-
Enter your live client ID and secret into the code. Under
paypal.Button.render()
:- Set
env
toproduction
. - 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';
- Set
- Change the
PAYPAL_API
endpoint to:https://api-m.paypal.com
.
Run live transactions
Complete a live transaction:
- Click your PayPal button.
- 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.
- 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:
- Log in to PayPal using your real PayPal business account to confirm that the funds have been received (minus any processing fees).
- 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: