First-time buyer integration (SDK)

DOCS

Last updated: Sept 23rd, 9:52pm

Enhance your existing PayPal billing agreement SDK integration for first-time buyers.

Know before you code

Make sure you complete or have the following before you begin:

Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:
- Get API Credentials (Client ID and Secret)
- Exchange your API credentials for an access token

Make sure you have the ability to identify the buyers who come to your website.

Make sure you are enabled to create and process payments using billing agreements.

Once buyer chooses PayPal to make a purchase:

Review the purchase.

Confirm the purchase and the creation of a billing agreement.

1. Add the SDK and buttons

Add the JavaScript SDK and payment buttons to your page.

1<!DOCTYPE html>
2<html>
3  <head>
4    <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Ensures optimal rendering on mobile devices. -->
5    <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <!-- Optimal Internet Explorer compatibility -->
6  </head>
7  <body>
8    <script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID¤cy=CURRENCY&intent=capture&commit=false&vault=true"> // Replace YOUR_CLIENT_ID with your sandbox client ID
9    </script>
10
11    <div id="paypal-button-container"></div>
12  </body>
13</html>

Modify the code

Update the script tag to pass the required parameters for your integration:

In the SDK code, replace YOUR_CLIENT_ID with your client ID.

Set up the vault parameter to be true.

To customize the intent, currency, commit, vault, and locale values, see the JavaScript SDK reference.

2. Render the button

Add script to render button

1paypal.Buttons({
2// More code to be added here
3}).render('#paypal-button-container');

3. Set up a transaction or create an order

Note: Make sure you're on version 62 or higher of the NVP/SOAP APIs to integrate Pay Later offers.

Tell SDK how to setup a transaction or create an order.

When your buyer clicks the PayPal button, the script calls a createOrder() function that you define. In this function, first get the token value from an NVP/SOAP SetExpressCheckout response to the client. Then, return that token in the createOrder() function:

1paypal.Buttons({
2  createOrder: function() {
3    var SETEC_URL = 'https://mystore.com/api/set-express-checkout-with-billing';
4
5    return fetch(SETEC_URL, {
6      method: 'post',
7      headers: {
8        'content-type': 'application/json'
9      }
10    }).then(function(res) {
11      return res.json();
12    }).then(function(data) {
13      return data.token;
14    });
15  }
16}).render('#paypal-button-container');

Make sure the amount is greater than zero; BA with purchase can't have an amount of zero. For more information, refer to the billing agreements overview page.

Set the L_BILLINGTYPEn to MerchantInitiatedSingleBilling in SetExpressCheckout. See the billing agreement options for more details.

Since the JavaScript SDK integration does not use the RETURNURL and CANCELURL 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, use onApprove, onCancel, and onError.

When a createOrder() function is successful, the SDK automatically redirects the buyer to PayPal to get their approval. The merchant doesn't need to manual redirect the buyer.

4. Buyer approval

Tell the SDK what to do on getting buyer approval.

After your buyer logs in to PayPal and authorizes the transaction successfully, the script calls the onApprove() function that you defined. This function finalizes the transaction. Otherwise, it calls onError().

Call your server with the data.orderID and data.payerID values in a DoExpressCheckoutPayment NVP/SOAP API call.

1paypal.Buttons({
2  onApprove: function(data) {
3    var DOEC_URL = 'https://mystore.com/api/do-express-checkout';
4
5    return fetch(DOEC_URL, {
6      method: 'post',
7      headers: {
8        'content-type': 'application/json'
9      },
10      body: JSON.stringify({
11        token:   data.orderID,
12        payerID: data.payerID
13      })
14    });
15  }
16}).render('#paypal-button-container');

Invoke a DoExpessCheckoutPayment call on your server with the token and payerID.

Alternatively, you can redirect the buyer to a different page (such as the review page) to confirm the payment and call DoExpressCheckoutPayment server call from there.

To handle redirections in onApprove, onCancel, and onError use actions.redirect(‘/desired-page').

Note: Because you don't need to get the buyer approval, the script calls the onApprove() function that you defined after the createOrder() function. This function finalizes the transaction.