Advanced server integration

The advanced integration gives you more control and flexibility when you create and execute payments. For example, you can optionally show the buyer a confirmation page before you finalize the transaction.

In this integration, the buyer approves the payment on your client and you make calls to your server. Your server then makes API calls to create and execute payments.

Note: PayPal recommends that all new integrations use the REST Payments API because new features will be added to this API. However, legacy integrations can use the NVP/SOAP APIs. To migrate an NVP/SOAP integration to REST, contact Merchant Technical Support.

Set up your client

Try the full interactive demo.

To set up your client:

  1. Add the checkout.js script to your client. Then, use this example to configure the script.

  2. To create a payment, set up the payment function:

    • Call your server to set up the payment.
    • To start the buyer approval flow, call resolve(data.paymentID), where the paymentID is the ID that the create payment call returns.
  3. To finalize the payment, set up the onAuthorize function:

    • Use the data.paymentID and data.payerID values in subsequent REST Payments API calls.
    • At this point, you can optionally show payment details to the buyer on a confirmation page.
    • Execute the payment to finalize the transaction from your server.
<div id="paypal-button"></div>

<script src="https://www.paypalobjects.com/api/checkout.js"></script>

<script>
    paypal.Button.render({
    
        env: 'production', // Optional: specify 'sandbox' environment
    
        payment: function(resolve, reject) {
               
            var CREATE_PAYMENT_URL = 'https://my-store.com/paypal/create-payment';
                
            return paypal.request.post(CREATE_PAYMENT_URL)
                .then(function(data) { resolve(data.paymentID); })
                .catch(function(err) { reject(err); });
        },

        onAuthorize: function(data) {
        
            // Note: you can display a confirmation page before executing
            
            var EXECUTE_PAYMENT_URL = 'https://my-store.com/paypal/execute-payment';

            return paypal.request.post(EXECUTE_PAYMENT_URL,
                    { paymentID: data.paymentID, payerID: data.payerID })
                    
                .then(function(data) { /* Go to a success page */ })
                .catch(function(err) { /* Go to an error page  */ });
        }

    }, '#paypal-button');
</script>

How the server integration works

This example describes how your server makes API calls to set up and execute the payment. For detailed server integration steps, see the REST server steps or the NVP/SOAP server steps.

Set up the payment

  1. The payment method you created on the client makes a call to your server.

  2. Your server sends a create payment request to the Payments API.

    Note: You must pass redirect_urls in the create-payment request but PayPal does not automatically call these URLs. PayPal invokes your onAuthorize function when the buyer authorizes the payment. At this point you can choose to redirect the buyer.

  3. Your server reads the id from the JSON response:

        {
            "id": "PAY-0J356327TH335450NK56Y2PQ",
            "intent": "sale",
            "state": "created",
            ...
        }
    
  4. Your server sends a response to your client to pass back the payment ID:

    {
        "paymentID": "PAY-0J356327TH335450NK56Y2PQ"
    }
    
  5. To initiate the checkout flow, the payment method you created on the client passes the paymentID from the JSON response to the checkout.js script.

  6. The Express Checkout flow is launched in a lightbox on your page and gets the buyer's approval for payment.

To further customize the buyer's checkout experience, you can optionally create web experience profiles.

Execute the payment

When the buyer approves the payment, the checkout.js script calls your onAuthorize call back.

Note: You can show payment details on a confirmation page either before or after you execute the payment.

  1. Your client makes a call to your server in the onAuthorize call back.

    The required data.paymentID and data.payerID parameters are passed to your server to execute the payment.

  2. Your server sends an execute payment request to the Payments API and finalizes the payment.

Next

Set up your server.