Upgrade your Checkout integration
DocsCurrentLast updated: April 6th 2022, @ 4:06:12 pm
If you have older checkout integrations, like Express Checkout or checkout.js, you can upgrade your integration to take advantage of the current JavaScript SDK integration. The JavaScript SDK keeps your integration current with button styles and payment features.
Know before you code
Before you start the upgrade, understand key concepts of the JavaScript SDK flow:
- To render the payment buttons, you must use the JavaScript SDK rather than a static image.
- The payment flow launches in a pop-up window instead of doing a full-page redirect.
Also,
- Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:
- Your client ID
- Your personal and business sandbox accounts
- Use your client ID when adding payment options to your website. Use your sandbox accounts when testing the checkout options.
How it works
After the buyer authorizes the transaction, the payment buttons call your JavaScript callback rather than redirecting the buyer to a return URL.
- Your buyer clicks a payment button.
- Your buyer logs into PayPal.
- Your buyer approves the transaction on PayPal.
- Your buyer returns to your site, and you show them a confirmation page.
1. Add payment buttons
Add the JavaScript SDK and payment buttons to your page.
<!DOCTYPE html>
<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"> // Replace YOUR_CLIENT_ID with your sandbox client ID
</script>
<div id="paypal-button-container"></div>
</body>
</html>
Modify the code
- Copy the sample JavaScript SDK code and paste it into the code of your checkout page.
- In the SDK code, replace
YOUR_CLIENT_ID
with your client ID.
See also
2. Update script
Update the script tag to pass the correct parameters for your integration:
- The currency of the transaction.
- The intent of the transaction.
- Whether the transaction is a commit with a Pay Now button or a Continue button.
- Whether the transaction sets up a vault, including reference transactions or subscriptions.
See all parameters that you can pass to the script. For example:
<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID¤cy=EUR&intent=order&commit=false&vault=true"></script>
3. Set up transaction
When your buyer clicks the PayPal button, the script calls a createOrder()
function that you define. In this function, return a promise for a token, payment ID, or order ID, from the PayPal API you're calling:
- NVP/SOAP integrations
- Server-side REST integrations with /v1/payments
- checkout.js integrations with actions.payment.create()
Note: The
createOrder()
function in the JavaScript SDK integration replaces thepayment()
function in thecheckout.js
script.
NVP/SOAP integrations
Return the token
value from an NVP/SOAP SetExpressCheckout
response to the client. Then, return that token in the createOrder
function:
paypal.Buttons({
createOrder: function() {
var SETEC_URL = 'https://mystore.com/api/paypal/set-express-checkout';
return fetch(SETEC_URL, {
method: 'post',
headers: {
'content-type': 'application/json'
}
}).then(function(res) {
return res.json();
}).then(function(data) {
return data.token;
});
}
}).render('#paypal-button-container');
Notes:
The JavaScript SDK integration does not use the
RETURNURL
andCANCELURL
values in the NVP/SOAP API.Pass
https://www.paypal.com/checkoutnow/error
as a placeholder value for these keys. To handle transaction success or failure, useonApprove
,onCancel
, andonError
.To customize the
intent
,currency
,commit
,vault
andlocale
values, see the JavaScript SDK reference.
Server-side REST integrations with /v1/payments
Return the EC-XXXXX
token from the REST API /v1/payments/payment
response.
API endpoint used: Create payment
Locate the token in the response
links
array, in the object whererel
is"approval_url"
:"links": [{ "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY", "rel": "self", "method": "GET" }, { "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-60385559L1062554J", "rel": "approval_url", "method": "REDIRECT" }, { "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-1B56960729604235TKQQIYVY/execute", "rel": "execute", "method": "POST" }]
Extract the
EC-XXXXXX
token from the array:let token; for (let link of response.links) { if (link.rel === 'approval_url') { token = link.href.match(/EC-\w+/)[0]; } } // Now return the `token` to the client
Return the token to
createOrder
on the client side.The required token is
EC-60385559L1062554J
in this example:paypal.Buttons({ createOrder: function() { var CREATE_PAYMENT_URL = 'https://mystore.com/api/paypal/create-payment'; return fetch(CREATE_PAYMENT_URL, { method: 'post', headers: { 'content-type': 'application/json' } }).then(function(res) { return res.json(); }).then(function(data) { return data.token; }); } }).render('#paypal-button-container');
Notes:
The JavaScript SDK integration does not use
return_url
andcancel_url
in the/v1/payments/payment
endpoint.Pass
https://www.paypal.com/checkoutnow/error
as a placeholder value for these keys. To handle transaction success or failure, useonApprove
,onCancel
, andonError
.To customize the
intent
,currency
,commit
,vault
, andlocale
values, see the JavaScript SDK reference.
checkout.js integrations with actions.payment.create()
Migrate the actions.payment.create()
call to actions.order.create()
.
See Add payment buttons.
paypal.Buttons({
createOrder: function() {
return actions.order.create({
purchase_units: [{
amount: {
value: '220.00'
}
}]
});
}
}).render('#paypal-button-container');
4. Finalize payment
After your buyer logs in to PayPal and authorizes the transaction, the script calls the onApprove()
function that you defined. This function finalizes the transaction.
- NVP/SOAP integrations
- Server-side REST integrations with /v1/payments
- Client-side REST integrations with actions.payment.create()
Note: The
onAuthorize()
function from thecheckout.js
script is replaced by theonApprove()
function in the JavaScript SDK integration.
NVP/SOAP integrations
Call your server with the
data.orderID
anddata.payerID
values in aDoExpressCheckoutPayment
NVP/SOAP API call:paypal.Buttons({ onApprove: function(data) { var DOEC_URL = 'https://mystore.com/api/paypal/do-express-checkout'; return fetch(DOEC_URL, { method: 'post', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ token: data.orderID, payerID: data.payerID }) }); } }).render('#paypal-button-container');
Invoke a
DoExpressCheckoutPayment
call on your server with thetoken
andpayerID
.
Server-side REST integrations with /v1/payments
API endpoint used: Create payment
If you have a call to the
/v1/payments/payment/PAY-XXX/execute
endpoint, call your server with thedata.paymentID
anddata.payerID
values:paypal.Buttons({ onApprove: function(data) { var EXECUTE_URL = 'https://mystore.com/api/paypal/execute-payment'; return fetch(EXECUTE_URL, { method: 'post', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ paymentID: data.paymentID, payerID: data.payerID }) }); } }).render('#paypal-button-container');
On your server, invoke a
/v1/payments/payment/PAY-XXX/execute
call with thepaymentID
andpayerID
.
Client-side REST integrations with actions.payment.create()
Migrate the actions.payment.execute()
to actions.order.capture()
. See Set up standard payments.
paypal.Buttons({
onApprove: function(data, actions) {
return actions.order.capture();
}
}).render('#paypal-button-container');
5. Fix deprecations
For checkout.js
integrations, upgrade the deprecated integration to the current integration. To debug issues, check your browser's JavaScript console for errors.
Deprecated integration | Upgrade to integration |
---|---|
Add a script that points to | Add a script that points to |
Add a client-side call to | Add a client-side call to |
Add the | Add the |
Add the | Add the |
Add the | Add the |
Add the | Add the |
Set | Set the container element to your preferred size. |
Pass the | Pass |
Pass the | Pass See Commit. |
Pass the | Pass See Client ID. |
Pass the | Pass See Locale. |
Pass the | The card buttons display automatically in the default integration. |
Pass the | PayPal automatically decides on the optimal buttons to show to your buyers. |
Pass the | Pass See Disable Funding and Disable card. |
Use | Use the built-in browser See Fetch. |
Use | Use the built-in browser See Promise. |
When you set up transaction, pass return and cancel URLs. Call | When you set up transaction, do not pass return and cancel URLs. Call Call See Redirect. |
6. Test your integration
Test and go live with your upgraded integration.