{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["site-link","tabs","tab","admonition"]},"type":"markdown"},"seo":{"title":"Using Checkout","meta":[{"name":"robots","content":"noindex, nofollow"},{"name":"pingdom","content":"sh3MDv8mJpWhCWSTdGtN"}]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"using-checkout","__idx":0},"children":["Using Checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/using-components"},"children":["Components"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can try different Checkout configurations by going to the ",{"$$mdtype":"Tag","name":"SiteLink","attributes":{"href":"/examples/checkout-session"},"children":["examples page"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial shows you how to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a Checkout Session"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Charge a card using Checkout"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checkout Sessions provide a secure, server-driven way to initialize Checkout and control every payment attempt."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-prepare-checkout-session","__idx":2},"children":["Step 1: Prepare Checkout Session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To open Checkout, you must first create a Checkout Session on your backend using your secret API key."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example below shows how to create a simple Checkout Session for a one-time charge:"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Java","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"Shift4Gateway gateway = new Shift4Gateway(\"pr_test_tXHm9qV9qV9bjIRHcQr9PLPa\");\n\nCheckoutProductRequest product = new CheckoutProductRequest()\n    .name(\"Premium Plan\")\n    .amount(5000)\n    .currency(\"USD\");\n\nCheckoutSessionRequest request = new CheckoutSessionRequest()\n    .lineItems(Arrays.asList(new LineItemRequest(product, 2)))\n    .collectBillingAddress(true)\n    .capture(true)\n    .locale(\"en\")\n    .metadata(Map.of(\"order_id\", \"12345\"));\n\nString clientSecret = gateway.createCheckoutSession(request).getClientSecret();\n","lang":"java"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The newly created ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutSession"]}," response will contain a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientSecret"]}," field which you will need to pass to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout.js"]}," library on the frontend."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["More information about Checkout Sessions can be found in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api/shift4-gateway/checkout/createcheckoutsession"},"children":["Create a checkout session"]}," endpoint reference."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-charge-card-using-checkout","__idx":3},"children":["Step 2: Charge card using Checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the Checkout Session is created, you can initialize Checkout on your website using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientSecret"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"opening-checkout-using-script-tag","__idx":4},"children":["Opening Checkout using script tag"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The fastest and simplest way to add Checkout to your website is by using the following script tag:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<form action=\"/your-payment-handler\" method=\"post\">\n  <script\n    src=\"https://dev.shift4.com/checkout.js\"\n    class=\"shift4-button\"\n    data-key=\"pk_test_xxxxxxxxxxxxxxxxxxxxxxxx\"\n    data-client-secret=\"chcs_xxxxxxxxxxxxxxxxxxxxxxxx\">\n  </script>\n</form>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The script tag must have its CSS class set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shift4-button"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This script tag will be automatically converted to a payment button that will open Checkout when clicked. All configuration is done using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data-*"]}," attributes, and no additional JavaScript code is required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When Checkout is successfully completed, the surrounding ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["form"]}," tag will be submitted with Checkout results — the following fields will be added to the submitted form: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shift4Email"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shift4CustomerId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shift4ChargeId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shift4SubscriptionId"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"opening-checkout-using-javascript","__idx":5},"children":["Opening Checkout using JavaScript"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you need more control over opening Checkout or you want to customize the handling of Checkout results, you can open Checkout using JavaScript:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<script src=\"https://dev.shift4.com/checkout.js\"></script>\n<script src=\"https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js\"></script>\n\n<script type=\"text/javascript\">\n  $(function () {\n    Shift4Checkout.key = 'pk_test_xxxxxxxxxxxxxxxxxxxxxxxx';\n    Shift4Checkout.success = function (result) {\n      // Handle successful payment\n      // e.g. send result data to your backend\n    };\n\n    Shift4Checkout.error = function (errorMessage) {\n      // Handle errors\n      // e.g. display a message or log the error\n    };\n\n    $('#payment-button').click(function () {\n      Shift4Checkout.open({\n        clientSecret: 'chcs_xxxxxxxxxxxxxxxxxxxxxxxx'\n      });\n    });\n  });\n</script>\n\n<button id=\"payment-button\">Payment button</button>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":6},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/checkout"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Checkout overview"]}]}," -- how Checkout is initialized and configured."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/checkout/customization"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Checkout customization"]}]}," -- customize the appearance and behavior of your Checkout form."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api/shift4-gateway/checkout/createcheckoutsession"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create a checkout session"]}]}," -- the full endpoint reference."]}]}]},"headings":[{"value":"Using Checkout","id":"using-checkout","depth":1},{"value":"Introduction","id":"introduction","depth":2},{"value":"Step 1: Prepare Checkout Session","id":"step-1-prepare-checkout-session","depth":2},{"value":"Step 2: Charge card using Checkout","id":"step-2-charge-card-using-checkout","depth":2},{"value":"Opening Checkout using script tag","id":"opening-checkout-using-script-tag","depth":3},{"value":"Opening Checkout using JavaScript","id":"opening-checkout-using-javascript","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Using Checkout","description":"Create a Checkout Session on your backend, pass its clientSecret to the browser, and charge a card with the Shift4 Checkout JavaScript library.","seo":{"title":"Using Checkout"}},"lastModified":"2026-09-11T07:43:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/checkout/using-checkout-session","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}