On this page
No Headings
PayPal Checkout integration guide
Last updated: August 17, 2026
DOCS
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.jscan access reference and support material in this Checkout guide. However, PayPal does not updatecheckout.jswith 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:
- Your buyer clicks on a PayPal button.
- The PayPal button calls the PayPal API to set up the payment.
- 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
- Click your PayPal Checkout button.
- Log in to PayPal using the test buyer account you created earlier.
- Complete a transaction.
Verify test transactions
Verify your test transactions from both the merchant's and buyer's perspective:
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:
Create a PayPal business account
Note: If you already have a PayPal business account, skip this section.
- 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
- On My Apps & Credentials, click the Live toggle.
- In the REST API apps section, click Create App.
- Note: You must have a business account to create or access live apps.
- Click Create App..
- Configure your live app to match the configuration of your sandbox app.
- Copy your live client ID.
- In the
Configure environmentsection of the script, setenvtoproductionand 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
- Click your PayPal Checkout button.
- 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.
- Complete a transaction.
Verify live transactions
Verify your live transactions from both the merchant's and buyer's perspective:
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 customize your new button or the checkout flow: