Welcome to Zuora Product Documentation

Explore our rich library of product information

Set up PayPal on PayPal Complete Payments with Zuora JavaScript SDK

This article describes how to set up PayPal on the PayPal Complete Payments by integrating with a JavaScript SDK provided by Zuora. Complete the following tasks to implement the integration:

Alternatively, if you want to create a PayPal payment method through REST API or UI, see Define and set up payment methods .

Import the Zuora JavaScript client library to your page.

For sandbox environments, use <script src="https://js.zuora.com/payment/sandbox/1.4.0/zuora.js"></script> .

For production environments, use <script src="https://js.zuora.com/payment/1.4.0/zuora.js"></script> .

Create a container for the PayPal button on your page and place it where you want the button to be rendered. Replace paypal-button-container with the ID you want to use.

<div id="paypal-button-container">
<!-- The PayPal button will be inserted here. -->
</div>
  1. Complete prerequisite tasks .
  2. Implement the client-side SDK integration .
  3. Implement the server-side API integration .
  4. Perform integration testing .
  5. Turn on the Payment Form feature. The JavaScript SDK integration utilizes the publishable key from the Payment Form feature for authentication. This integration supports embedding the PayPal button within an iframe hosted by Zuora. To enable Payment Form on your tenant, see the "Before you start" section in Configure payment forms .
  6. Configure a PayPal Complete Payments gateway instance. Ensure that a PayPal Complete Payments gateway instance has been created and is in the active status on your Zuora tenant.
  7. Copy the publishable key from Payment Form. In the Zuora UI, click your username in the upper right and navigate to Settings > Payments > Payment Form . On the Publishable Keys tab, copy the key.
  8. Initialize an instance of the Zuora object with your publishable key.
  9. Populate the payment request parameters and generate a payment session when the end customers click the PayPal button. The following table describes the payment request parameters: For more information about payment flow implementation by using these parameters, see Payment flow use cases in the later section.

    Parameter

    Type

    Description

    currency

    string

    Required.

    The ISO 4217 alphabetic currency code, such as "USD".

    amount

    string

    Required.

    The total amount for the payment. This field is required if intent is authorize .

    countryCode

    string

    The ISO 3166-1 alpha-2 code of the country where the transaction is processed, such as "US".

    If it is not specified, the default value US is used.

    locale

    string

    The locale code, which is the combination of ISO language code and ISO country code, such as "en_US".

    If it is not specified, the default value en_US is used.

    vault

    boolean

    To store the payment method, set this field to true .

    intent

    string

    The intent of the transaction. Currently, only authorize is supported.

    provider

    object

    The payment gateway instance that will process the payment. Specify the following nested fields:

    • name : The type of the payment gateway. To support the PayPal integration on PayPal Complete Payments, specify PaypalCP . This field is case-sensitive.

    • paymentGatewayId : The ID of the PayPal Complete Payments payment gateway instance.

    • clientId : The client ID of the PayPal application, which can be found in the PayPal dashboard.

  10. Mount the button component to the container.
  11. Handle the payment result.

Here is an example of the code implementation:

// The publishable key can be found on the Payment Form setting page.
const publishableKey = "pk_rO0AB..........";
const renderForm = () => {
  const zuora = Zuora(publishableKey);
  zuora.createPayPalButton({
    countryCode: "US",
    locale: "en_US",
    currency: "USD",
    // The amount to be paid. this is required when intent is "authorize".
    amount: "1.00", 
    // set it to true to enable vaulting.
    vault: true, 
    // The intent of the transaction. only "authorize" is supported
    intent: "authorize",
    provider: {
      name: "PaypalCP",
      paymentGatewayId: "4028839390f481ae0190f491084f0004",
      clientId: "AfuCtaWvIgugr1mcrpoEdGTAwxkpeVi-C5Zrw0oXdmFWLh5QzWAeWiu1UmzBe8A6JktG_Z31UKD1jXJ9"
    },
    createPaymentSession: () => {
      // it MUST return a Promise here.
      return new Promise((resolve, reject) => {
        // Send request to your server to create a payment session.
        // The server should return a payment session id.
        // then resolve the promise with the payment session id.
        resolve("payment-session-id-from-server");
      });
    },
    onComplete: (result) => {
      // handle the transaction result
      // when result.success is true, the transaction is successful.
      // result.paymentMethodId is the created payment method id.
      // result.paymentId is the processed payment id.
      //
      // When result.success is false, the transaction is failed.
      // result.error will contain the error code and message.
    }
  }).then(function(paypalButton) {
    paypalButton.mount("#paypal-button-container")
  }).catch(function(error) {
    // failed to create the PayPal button
    console.error(error);
  });
};

In your server, make an API request to the Create a payment session endpoint. For details about the API request parameters, see Create a payment session in the API Reference.

For more information about payment flow implementation, see Payment flow use cases in the later section.

To configure the payment flow mode, specify parameters for creating the server-side payment session and the client-side button, as outlined in the following table:

Supported Payment Flow

Create Payment Session Parameters

Create PayPal Button Parameters

Create and save the PayPal payment method

  • amount: 0

  • processPayment: false

  • storePaymentMethod: true

  • amount: 0

  • vault: true

Process a one-time payment without saving the payment method

  • amount: Specify the amount number. It must match the amount in the button parameter.

  • processPayment: true

  • storePaymentMethod: false

  • amount: Specify the amount number.

  • vault: false

  • intent: authorize

In client code, make a call to your backend API to create a payment session.