{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","cards","card"]},"type":"markdown"},"seo":{"title":"Payment components","description":"Shift4 Payment Platform REST API."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"payment-components","__idx":0},"children":["Payment components"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment components"]}," let you build the checkout into your own page while keeping card data out of your reach: the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["shift4.js"]}," library renders the sensitive inputs (card number, expiry, CVC) and the wallet buttons (Apple Pay, Google Pay) as Shift4-hosted components mounted inside your layout. You control the page, the styling around the fields, and when the payment is submitted; Shift4 handles the card data, payment method logic, and PCI scope."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Everything is driven by a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/create-a-checkout-session"},"children":["Checkout Session"]}," created on your backend — its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientSecret"]}," is what authorizes the components in the browser."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payment components require a fixed line-item amount (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.amount.total"]},"). Customer-chosen amounts (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custom"]},") aren't supported in the embedded flow yet — use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/hosted-checkout"},"children":["Hosted checkout"]}," for those."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-shift4js","__idx":1},"children":["Add shift4.js"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Load the library from Shift4:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<script src=\"https://js.shift4.com/v1/shift4.js\"></script>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"180px","data-label":"Name"},"children":["Name "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"URL"},"children":["URL"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["shift4.js script"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://js.shift4.com/v1/shift4.js"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API base URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.shift4.com"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"keys-platform-public-key-vs-access-token","__idx":2},"children":["Keys: Platform Public Key vs Access Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Initialise the library with your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Platform Public Key"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"var shift4 = Shift4('pk_sandbox_XXXXXXXXXXXXXXXXXXXX');\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Platform Public Key (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pk_…"]},") is designed for the browser. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AccessToken"]}," you use server-side is not — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["never put your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AccessToken"]}," in client-side code"]},". Sandbox keys are prefixed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pk_sandbox_"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"content-security-policy","__idx":3},"children":["Content Security Policy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your page uses a Content Security Policy, allow the following so the library, its components, and its telemetry can load:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"script-src   https://js.shift4.com\nframe-src    https://js.shift4.com\nimg-src      https://t.dev.shift4.com data:\nconnect-src  https://t.dev.shift4.com\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each wallet adds one or two entries on top of this baseline — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components/apple-pay#content-security-policy"},"children":["Apple Pay"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components/google-pay#content-security-policy"},"children":["Google Pay"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-the-checkout-object","__idx":4},"children":["Create the checkout object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On your backend, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/create-a-checkout-session"},"children":["create a Checkout Session"]}," and pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result[0].checkoutSession.clientSecret"]}," to the browser. Then create the checkout object:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"var checkout = await shift4.createCheckout('{{clientSecret}}');\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientSecret"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["single-use"]}," — create a new Checkout Session for each payment attempt."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"components","__idx":5},"children":["Components"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create components from the checkout object and mount them into your own elements:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"checkout.createComponent('number').mount('#number');\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"220px","data-label":"Component"},"children":["Component "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Renders"},"children":["Renders"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiry"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cvc"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Individual card fields — one component per input, arranged however your layout needs."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A single combined card field, if you'd rather mount one component."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apple-pay-button"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Apple Pay button — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components/apple-pay"},"children":["Apple Pay"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["google-pay-button"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Google Pay button — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components/google-pay"},"children":["Google Pay"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wallet buttons and card fields represent separate payment flows with independent Checkout Sessions — each needs its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createCheckout()"]}," call. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/core-concepts/checkout/payment-components/card-payments#offer-wallets-alongside-cards"},"children":["Offer wallets alongside cards"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":6},"children":["Next steps"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":3,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Card payments","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/checkout/payment-components/card-payments"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mount the card fields, submit with continue(), and handle the result events."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Apple Pay","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/checkout/payment-components/apple-pay"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the Apple Pay button — requirements and example."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Google Pay","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/checkout/payment-components/google-pay"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the Google Pay button — CSP and 3D Secure notes."]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Events & error handling","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts/checkout/payment-components/events-and-errors"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The event model and how to handle interruptions and failures."]}]}]}]},"headings":[{"value":"Payment components","id":"payment-components","depth":1},{"value":"Add shift4.js","id":"add-shift4js","depth":2},{"value":"Keys: Platform Public Key vs Access Token","id":"keys-platform-public-key-vs-access-token","depth":2},{"value":"Content Security Policy","id":"content-security-policy","depth":2},{"value":"Create the checkout object","id":"create-the-checkout-object","depth":2},{"value":"Components","id":"components","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Payment components","description":"Embed Shift4-rendered card fields and wallet buttons in your own page with the shift4.js library, driven by the Checkout Session's clientSecret.","markdown":{"lastUpdatedBlock":{"hide":true}},"seo":{"title":"Payment components"}},"lastModified":"2026-10-08T08:30:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/core-concepts/checkout/payment-components","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}