Using Checkout

The easiest way to integrate with Shift4 is to use Checkout. We take care of all the complex parts. All you need to do is to create a Checkout Session on your backend service, and use it with our JS library.

Checkout can be customized to meet your business needs and requirements. Still, if you need more control over the look and feel of your payment form, you can integrate with Shift4 using Components.

You can try different Checkout configurations by going to the examples page.

Introduction

This tutorial shows you how to:

Create a Checkout Session
Charge a card using Checkout

Checkout Sessions provide a secure, server-driven way to initialize Checkout and control every payment attempt.

Step 1: Prepare Checkout Session

The Checkout Session object is used to define what you want to do with the customer's payment. You can either create a single charge (by providing the amount and currency) or create an automatically recurring subscription (by providing the identifier of an existing subscription plan).

To open Checkout, you must first create a Checkout Session on your backend using your secret API key.

The example below shows how to create a simple Checkout Session for a one-time charge:

Shift4Gateway gateway = new Shift4Gateway("pr_test_tXHm9qV9qV9bjIRHcQr9PLPa");

CheckoutProductRequest product = new CheckoutProductRequest()
    .name("Premium Plan")
    .amount(5000)
    .currency("USD");

CheckoutSessionRequest request = new CheckoutSessionRequest()
    .lineItems(Arrays.asList(new LineItemRequest(product, 2)))
    .collectBillingAddress(true)
    .capture(true)
    .locale("en")
    .metadata(Map.of("order_id", "12345"));

String clientSecret = gateway.createCheckoutSession(request).getClientSecret();

The newly created CheckoutSession response will contain a clientSecret field which you will need to pass to the checkout.js library on the frontend.

More information about Checkout Sessions can be found in the Create a checkout session endpoint reference.

Step 2: Charge card using Checkout

Once the Checkout Session is created, you can initialize Checkout on your website using the clientSecret.

Opening Checkout using script tag

The fastest and simplest way to add Checkout to your website is by using the following script tag:

<form action="/your-payment-handler" method="post">
  <script
    src="https://dev.shift4.com/checkout.js"
    class="shift4-button"
    data-key="pk_test_xxxxxxxxxxxxxxxxxxxxxxxx"
    data-client-secret="chcs_xxxxxxxxxxxxxxxxxxxxxxxx">
  </script>
</form>

The script tag must have its CSS class set to shift4-button.

This script tag will be automatically converted to a payment button that will open Checkout when clicked. All configuration is done using data-* attributes, and no additional JavaScript code is required.

When Checkout is successfully completed, the surrounding form tag will be submitted with Checkout results — the following fields will be added to the submitted form: shift4Email, shift4CustomerId, shift4ChargeId, shift4SubscriptionId.

Opening Checkout using JavaScript

If you need more control over opening Checkout or you want to customize the handling of Checkout results, you can open Checkout using JavaScript:

<script src="https://dev.shift4.com/checkout.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>

<script type="text/javascript">
  $(function () {
    Shift4Checkout.key = 'pk_test_xxxxxxxxxxxxxxxxxxxxxxxx';
    Shift4Checkout.success = function (result) {
      // Handle successful payment
      // e.g. send result data to your backend
    };

    Shift4Checkout.error = function (errorMessage) {
      // Handle errors
      // e.g. display a message or log the error
    };

    $('#payment-button').click(function () {
      Shift4Checkout.open({
        clientSecret: 'chcs_xxxxxxxxxxxxxxxxxxxxxxxx'
      });
    });
  });
</script>

<button id="payment-button">Payment button</button>

Next steps

Checkout overview -- how Checkout is initialized and configured.
Checkout customization -- customize the appearance and behavior of your Checkout form.
Create a checkout session -- the full endpoint reference.