Skip to content
Branch: master
Find file History
Mohan Vanmane
Latest commit 4ab5a4f Mar 18, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
src/main Update java example for the docs improvement Mar 16, 2019
.gitignore Java payment form example Sep 26, 2017
PaymentFormExampleJava.png added Process flow to ReadMe for Java. Mar 15, 2019
Procfile replaced PHP by Java in 2 places as per Xiao input Mar 18, 2019

Java Payment Form Example

This example hosts a payment form in Java. It is a Spring Boot app and requires Java 8 or newer.

Setting up

First, you'll need to have created a Square application. If you haven't done this yet, you can quickly set on up in the Square Developer Portal.

Once you've created an Square application, you'll need both the Application ID and the Personal Access Token for it. These are available in the Square Developer Portal as well.

If you want to test Apple Pay, you'll need to replace the contents of src/main/resources/public/.well-known/apple-developer-merchantid-domain-association. You can get real content for this file from the Square Developer Portal, in the Apple Pay section of your application.

Note that Apple Pay cannot be tested when running locally. You'll need to deploy the app to try it out.

Running locally

The app can be run on a command line using Maven. The application expects three environment variables to be set: SQUARE_APP_ID, SQUARE_LOCATION_ID and SQUARE_ACCESS_TOKEN. Both of these can be copied from the Developer Dashboard. Keep in mind that the access token is sensitive and must remain private.

To get up and running, first clone the repo to your local computer. Then open a command line terminal and run the following command:

# The following command sets environment variables and starts the application locally:
SQUARE_APP_ID=replace_me SQUARE_ACCESS_TOKEN=replace_me SQUARE_LOCATION_ID=replace_me mvn spring-boot:run

After running the above command, you can open a browser and go to http://localhost:5000.

The default port used is 5000, but this can be configured in the file.

If the credentials are not set or are invalid, the app will fail during startup.

Application Flow

The Java web application implements the Square Online payment solution to charge a payment source (debit, credit, or digital wallet payment cards).

Square Online payment solution is a 2-step process:

  1. Generate a nonce - Using a Square Payment Form (a client-side JavaScript library called the SqPaymentForm) you accept payment source information and generate a secure payment token (nonce).

    NOTE: The SqPaymentForm library renders the card inputs and digital wallet buttons that make up the payment form and returns a secure payment token (nonce). For more information, see

    After embedding the Square Payment form in your web application, it will look similar to the following screenshot:

  2. Charge the payment source using the nonce - Using a server-side component, that uses the Connect V2 Transaction API, you charge the payment source using the nonce. s The following sections describe how the Java sample implements these steps.

Step 1: Generate a Nonce

When the page loads it renders the form defined in the index.html file. The page also downloads and executes the following scripts defined in the file:

Square Payment Form Javascript library ( It is a library that provides the SqPaymentForm object you use in the next script. For more information about the library, see SqPaymentForm data model.

sq-payment-form.js - This code provides two things:

  • Initializes the SqPaymentForm object by initializing various configuration fields and providing implementation for callback functions. For example,

    • Maps the SqPaymentForm.cardNumber configuration field to corresponding form field:

      cardNumber: {
          elementId: 'sq-card-number',               
          placeholder: '•••• •••• •••• ••••'
    • SqPaymentForm.cardNonceResponseReceived is one of the callbacks the code provides implementation for.

  • Provides the onGetCardNonce event handler code that executes after you click Pay $1.00 Now.

After the buyer enters their information in the form and clicks Pay $1 Now, the application does the following:

  • The onGetCardNonce event handler executes. It first generates a nonce by calling the SqPaymentForm.requestCardNonce function.

  • SqPaymentForm.requestCardNonce invokes SqPaymentForm.cardNonceResponseReceived callback. This callback assigns the nonce to a form field and posts the form to the payment processing page:

    document.getElementById('card-nonce').value = nonce;

    This invokes the form action charge, described in next step.

Step 2: Charge the Payment Source Using the Nonce

All the remaining actions take place in the This server-side component uses the Square Java SDK library to call the Connect V2 Transaction API to charge the payment source using the nonce as shown in the following code fragment.

String charge(@ModelAttribute NonceForm form, Map<String, Object> model) throws ApiException {
        ChargeRequest chargeRequest = new ChargeRequest()
            .amountMoney(new Money().amount(1_00L).currency(CurrencyEnum.USD))
            .note("From a Square sample Java app");

        TransactionsApi transactionsApi = new TransactionsApi();

        ChargeResponse response = transactionsApi.charge(squareLocationId, chargeRequest);

        model.put("transaction", response.getTransaction());

        return "charge";
You can’t perform that action at this time.