Integrate PayPal Checkout

Before beginning your integration, you need to set up your development environment. You can refer to this flow diagram, and watch a video demonstrating how to integrate PayPal standard Checkout.

Start your integration by grabbing the sample code from PayPal’s GitHub repo, or visiting the PayPal GitHub Codespace. Read the Codespaces guide for more information. You can also use Postman to explore and test PayPal APIs. Read the Postman Guide for more information.

1. Integrate front end CLIENT

Set up your front end to integrate standard checkout payments.

Front-end process

1. Your app shows the PayPal checkout buttons.
2. Your app calls server endpoints to create the order and capture payment.

Front-end code

This example uses a checkout.html file to show how to set up the front end to integrate standard payments.

The /client/checkout.html and /client/app.js files handle the client-side logic and define how the PayPal front-end components connect with the back end. Use these files to set up the PayPal checkout using the JavaScript SDK and handle the payer's interactions with the PayPal checkout button.

You'll need to:

• Save the checkout.html file in a folder named /client.
• Save the app.js file in a folder named /client.

Step 1. Add the script tag

Include the <script> tag on any page that shows the PayPal buttons. This script will fetch all the necessary JavaScript to access the buttons on the window object.

Step 2. Configure your script parameters

The snippet in Step 1. Add the script tag shows that you need to pass a client-id and specify which components you want to use. The SDK offers Buttons, Marks, Card Fields, and other components. This sample focuses on the buttons component.

In addition to passing the client-id and specifying which components you want to use, you can also pass the currency you want to use for pricing. For this exercise, we'll use USD.

Buyer Country and Currency are only for use in sandbox testing. These are not to be used in production.

Step 3. Render the PayPal buttons

After setting up the SDK for your website, you need to render the buttons.

The paypal namespace has a Buttons function that initiates the callbacks needed to set up a payment.

The createOrder callback launches when the customer clicks the payment button. The callback starts the order and returns an order ID. After the customer checks out using the PayPal pop-up, this order ID helps you to confirm when the payment is completed.

Completing the payment launches an onApprove callback. Use the onApprove response to update business logic, show a celebration page, or handle error responses.

If your website handles shipping physical items, this documentation includes details about our shipping callbacks.

Step 4. Configure the layout of the Buttons component OPTIONAL

Depending on where you want these buttons to show up on your website, you can lay out the buttons in a horizontal or vertical stack. You can also customize the buttons with different colors and shapes.

To override the default style settings for your page, use a style object inside the Buttons component. Read more about how to customize your payment buttons in the style section of the JavaScript SDK reference page.

Step 5. Support multiple shipping options OPTIONAL

Integrate shipping options to offer your buyers the flexibility to choose their preferred delivery method. Buyers can update their shipping address and select from your shipping options.

• The onShippingAddressChange callback is triggered when the buyer selects a new shipping address. Use the data in this callback to tell the buyer if you support the new shipping address, update shipping costs, and update the line items in the cart.

• The onShippingOptionsChange callback is triggered when the buyer selects a new shipping option. Use the data in this callback to tell the buyer if you support the new shipping method, update shipping costs, and update the line items in the cart.

Visit the JavaScript SDK reference page for more details about the onShippingAddressChange and onShippingOptionsChange callbacks.

2. Integrate back end SERVER

This section explains how to set up your back end to integrate standard checkout payments.

Back-end process

1. Your app creates an order on the back end by calling to the Create Orders V2 API endpoint.
2. Your app calls the Capture Payment endpoint of the Orders V2 API on the back end to move the money when the payer confirms the order.

Back-end code

This sample integration uses a server.js file to set up the back end to integrate with standard payments.

Declare imports and additional functions

The server.js file sets up the port to run your server and starts the express Node.js web application framework.

• Declare a process.env so the DotEnv library imports and declares the client ID and client secret from your .env file.
• Set up the server.js file to retrieve variables and set the base URL for PayPal's sandbox API.
• Make app.use declarations to define a file directory for static files and call the express.json function to parse JSON response bodies.

Step 1. Generate access token

You need an OAuth 2.0 access token to authenticate all REST API requests.

• Declare a generateAccessToken() function that makes a POST call to the /v1/oauth2/ token endpoint to create an access token.
• Set up an auth parameter to combine the PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET as a key-value pair.
• Establish a data object that captures the response.json data from the request and returns the access_token.

Step 2. Create order

You need a createOrder function to start a payment between a payer and a merchant.

• Set up the createOrder function to make a POST request to /v2/checkout/orders and pass data from the cart object to calculate the purchase units for the order.
• Establish an accessToken object to capture the output from the generateAccessToken function later in the API call.

See the Create order endpoint of the PayPal Orders v2 API for sample responses and other details.

Step 3. Capture payment

You need a captureOrder function to move money from the payer to the merchant.

• Set up the captureOrder function to make a POST call to the /v2/checkout/orders/ORDER-ID/capture endpoint using the orderID generated from the Create Order endpoint.
• Establish an accessToken object to capture the output from the generateAccessToken function later in the API call.
• Set up a response that makes a POST call to the /v2/checkout/orders/ORDER-ID/capture endpoint to capture the order, passing the accessToken in the Authorization header.

Visit the Capture payment endpoint of the PayPal Orders v2 API to see sample responses and other details.

Step 4. Handle responses

You need a handleResponse function to set up a listener that returns an HTTP status code from the API response.

• Set up handleResponse to make a POST call to the /api/orders endpoint and return an HTTP status code response.
• Declare an errorMessage object to show an error message when handleResponse returns an error code.

3. Custom Integration OPTIONAL

Handle buyer checkout errors

Use onError callbacks and alternate checkout pages to handle buyer checkout errors.

If an error prevents buyer checkout, alert the user that an error has occurred with the buttons using the onError callback. This error handler is a catch-all. Errors at this point are not expected to be handled beyond showing a generic error message or page.

If a null pointer error prevents the script from loading, provide a different checkout experience.

Handle funding failures

If your payer's funding source fails, the Orders API returns an INSTRUMENT_DECLINED error. A funding source might fail because the billing address associated with the payment method is incorrect, the transaction exceeds the card limit, or the card issuer denies the transaction. To handle this error, restart the payment so the payer can select a different payment option.

Show cancellation page

Show a page to your payers to confirm that the payment was cancelled.

Refund a captured payment

Refund a captured payment from a seller back to a buyer.

4. Test integration

Before going live, test your integration in the sandbox environment. Learn more about card testing, simulating successful payments using test card numbers and generating card error scenarios using rejection triggers.

Test the following use cases before going live:

PayPal Payment

Test a purchase as a payer:

1. Select the PayPal button on your checkout page.
2. Log in using one of your personal sandbox accounts. This ensures the payments will be sent to the correct account. Make sure that you use the sandbox business account that corresponds to the REST app you are using.
3. Note the purchase amount in the PayPal checkout window.
4. Approve the purchase with the Pay Now button. The PayPal window closes and redirects you to your page, indicating that the transaction was completed.

Confirm the money reached the business account:

1. Log in to the PayPal sandbox using the sandbox business account that received the payment. Remember that the SDK source now uses a sandbox client ID from one of your REST apps, and not the default test ID.
2. In Recent Activity, confirm that the sandbox business account received the money, subtracting any fees.
3. Log out of the account.

Card payment

1. Go to the checkout page for your integration.
2. Generate a test card using the credit card generator.
3. Enter the card details in the hosted field, including the name on the card, billing address, and 2-character country code. Then, submit the order.
4. Confirm that the order was processed.
5. Log in to your merchant sandbox account and navigate to the activity page to ensure the payment amount shows up in the account.

5. Go live

Follow this checklist to take your application live.

1. Log into the PayPal Developer Dashboard with your PayPal business account.
2. Obtain your live credentials.
3. Include the new credentials in your integration and Update your PayPal endpoint.

See Move your app to production for more details.