Collect payments with payment form

Payment Form Implementation Guide

Discover comprehensive code samples demonstrating integration with Payment Form. Understand how to swiftly implement hosted payment forms on your website.

Download Sample Code

Don't code? Use Zuora Payment Link.

1. Quick Start

Configure a Zuora client instance

Server | Server.java

Configure a Zuora client instance with your client ID and client secret. If you don't have them, contact your administrator.

Review the payment form and copy the publishable key

  1. In the Zuora UI, click your username in the upper right and navigate to Settings > Payments > Payment Form.
  2. Verify that the payment form you want to use in this guide is configured as expected.
  3. Copy the publishable key.

Initialize an instance of the Zuora object

Client | checkout.js

Initialize an instance of the Zuora object with your publishable key copied from the previous step.

Run the payment form

Ensure you have installed Java 11.

  1. Build the server: mvn package
  2. Run the server: java -cp target/sample-jar-with-dependencies.jar com.zuora.sample.Server
  3. Run the payment form by navigating to http://localhost:8888/checkout.html.

Try it out

On the page, enter 4111 1111 1111 1111 in the card number field, fill in the remaining card information, and then click the Pay button.

You will be redirected to a return page. The string displayed after "Your order:" is the ID of the created payment. You can find the successful payments in Zuora through the UI, API, Data Source Export, and Data Query.

Congratulations! You now have a basic integration working.

2. Customize

Customize the checkout page

Client | checkout.html

Customize the order summary section on the checkout page for your needs.

Customize the return page

Client | return.html

Customize the layout of the return page for your needs.

Handle payment result

Client | checkout.js

Use the callback function to handle the payment processing result.

The onComplete function returns result in the following structure:

On success:

{

  success: true,

  paymentMethodId?: string;

  paymentId?: string;

}

On error:

{

  success: false,

  error: {

    type: string;

    code: string;

    message: string;

  }

}

3. Integrate

To integrate the payment form with your website, complete a few more steps.

Import Zuora Java client library to your project

Server | pom.xml

Add the highlighted dependency to your POM build and import the library. Replace the version with the latest Zuora API library version. See Zuora Java SDK on Maven Central for the version information.To use the sample code, you must use Maven for the build.

Implement support for multi-entity

Server | Server.java

If there are multiple entities within your tenant, incorporate the following code line into the highlighted code block to support the multi-entity feature:

zuoraClient.setEntityId("REPLACE_WITH_ENTITY_ID");

Here is an example:

port(8888);

staticFiles.externalLocation(Paths.get("public").toAbsolutePath().toString());

zuoraClient.setEntityId("8a80825556ff28a4015709096c5d6f5d");

zuoraClient.initialize();

zuoraClient.setDebugging(true);

Implement backend API to create a payment session

Server | Server.java

In your server, add an endpoint to create a payment session. A one-time token will be returned.

You can specify parameters to define the payment flow mode as one of the following:

  • Create and save a payment method.
  • Process a one-time payment without saving the payment method.
  • Process the first payment and save the payment method for subsequent recurring payments.

You can also specify Gateway Options fields.

See Create a payment session for more information about the parameters.

Load zuora.js

Client | checkout.html

Import the Zuora JavaScript client library.

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 payment form

Client | checkout.html

Create a container and place it where you want the payment form to be rendered.

Initialize an instance of the Zuora object

Client | checkout.js

Initialize an instance of the Zuora object with your publishable key.

Populate the payment form configuration

Client | checkout.js

Generate a payment session when the end-customers click the Pay button.

Unless otherwise specified, the pre-defined default payment form is used. To use a specific payment form, copy its payment form number from the Zuora UI and incorporate the following code line into the highlighted code block:

profile: "REPLACE_WITH_PAYMENT_FORM_NUMBER",

Here is an example for specifying a payment form and other configuration parameters:

profile: "PF-00000006",

locale: "en",

region: "US",

currency: "USD",

amount: "1599.00",

To include additional information related to the payment session, specify the PaymentSessionContext parameter in the createPaymentSession callback function. Currently, only the paymentMethodType property is supported in PaymentSessionContext. You can leverage the paymentMethodType property to determine the payment gateway to be used for processing transactions or passing the gateway options while creating the payment session.
  • Property name: paymentMethodType
  • Description: The payment method type of the submitted transaction.
  • Supported values: creditcard, googlepay, applepay, ach, sepa, pad, paypal
  • Example scenario: Overwrite the default payment gateway for transactions submitted through Payment Form - You accept cards on Adyen and PayPal on Braintree to collect payments through Payment Form, and Adyen is the default payment gateway. Card transactions from Payment Form will be processed through Adyen. To overwrite the default payment gateway for PayPal transactions, specify the paymentMethodType property in the PaymentSessionContext parameter. Then, implement logic in your server-side code to route PayPal transactions to Braintree as the payment gateway.
For server-side sample code, see Server.java.

Create and mount the payment form

Client | checkout.js

Create an instance of the payment form component, and mount the form component to the container for displaying the hosted payment form.

package com.zuora.sample;

import static spark.Spark.port;
import static spark.Spark.post;
import static spark.Spark.staticFiles;

import com.zuora.ZuoraClient;
import com.zuora.api.ObjectQueriesApi;
import com.zuora.model.*;

import com.google.gson.Gson;
import spark.utils.StringUtils;

import java.math.BigDecimal;
import java.nio.file.Paths;
import java.util.Map;


public class Server {

    private static Gson gson = new Gson();
    /**
    * Please configure your OAuth client id here.
    */
    private static final String CLIENT_ID = "a113*****************************6e5e";
    /**
    * Please configure your OAuth client secret here.
    */
    private static final String CLIENT_SECRET = "=kSm9jIc****************************wvwJ";
    private final static ZuoraClient zuoraClient = new ZuoraClient(CLIENT_ID, CLIENT_SECRET, ZuoraClient.ZuoraEnv.SBX);


    public static void main(String[] args) {
        port(8888);
        staticFiles.externalLocation(Paths.get("public").toAbsolutePath().toString());
        zuoraClient.initialize();
        zuoraClient.setDebugging(true);

        post("create-payment-session", (request, response) -> {
            response.type("application/json");
            Map map = gson.fromJson(request.body(), Map.class);
            String firstName = (String) map.get("firstName");
            String lastName = (String) map.get("lastName");
            String currency = (String) map.get("currency");
            String amount = (String) map.get("amount");
            String paymentMethodType = (String) map.get("paymentMethodType");
            String paymentGatewayId;
            if ("paypal".equals(paymentMethodType)) {
                // Use Braintree gateway
                paymentGatewayId = "braintreeGatewayId";
            } else {
                // Use Adyen Gateway
                paymentGatewayId = "adyenGatewayId";
            }

            final CreateAccountContact contact = new CreateAccountContact().firstName(firstName)
                    .lastName(lastName)
                    .country("US")
                    .state("CA");
            final CreateAccountRequest createAccountRequest = new CreateAccountRequest()
                    .name(String.join(" ", firstName, lastName))
                    .billToContact(contact)
                    .billCycleDay(1)
                    .soldToSameAsBillTo(true) // alternatively, use .soldToContact(contact)
                    .autoPay(false)
                    .currency(currency);
            final CreateAccountResponse createAccountResponse = zuoraClient.accountsApi().createAccountApi(createAccountRequest).execute();

            final CreatePaymentSessionRequest createPaymentSessionRequest = new CreatePaymentSessionRequest()
                    .currency(currency)
                    .amount(new BigDecimal(amount))
                    .processPayment(true)
                    .accountId(createAccountResponse.getAccountId());
            if (StringUtils.isNotBlank(paymentGatewayId)) {
                createPaymentSessionRequest.setPaymentGateway(paymentGatewayId);
            }
            final CreatePaymentSessionResponse createPaymentSessionResponse = zuoraClient.paymentMethodsApi().createPaymentSessionApi(createPaymentSessionRequest).execute();

            return gson.toJson(createPaymentSessionResponse.getToken());
        });
    }
}