Integration walkthrough

Build an end-to-end integration with Primer and start accepting payments in 3 simple steps: create a secure checkout using our Universal Checkout, tokenize the payment method and authorize a payment against the payment token.

Set up your checkout page

Add the Primer SDK as a dependency


To get started, add the Primer Web SDK to your checkout page.

Specify a container element


Specify a checkout container element for Universal Checkout. The Universal Checkout is a managed checkout experience for all payment types, and handles 3D Secure.

Tokenize the payment method



Server-side requests are authenticated using an API key in the X-Api-Key header.

→ Read about authentication in our API Reference

Generate a client token


On your server, request a client token using your API key. This client token will be used on the front end to initialize the Primer SDK.

→ Read about generating a client token in our Universal Checkout guide

Initialize the SDK


With your client token in hand you can now initialize the SDK on the client-side.

Render the Universal Checkout


Render the Universal Checkout by passing a selector for your checkout container as an argument to .checkout().

The onTokenizeSuccess callback receives a secure, single-use payment token which can be safely passed to your server for authorization. Payment tokens work the same across all payment methods.

Authorize the payment

Authorize the payment


Call the Payments API with the generated payment token and other required payment fields:

  • amount: the amount you would like to charge the customer, in minor units
  • currencyCode: the ISO-4217 (three-letter) currency code
  • orderId: your reference for the payment
  • paymentInstrument: the payment token to use for this payment

→ Find out more in our Payments guide

Congratulations - you've created your first payment with Primer!

<!DOCTYPE html><!-- checkout.html --><html><!-- This added styling and css is entirely optional --><head>    <style>        #checkout-container {            display: flex;            flex-direction: column;            padding: 12px 24px;        }    </style>    <link rel="stylesheet" href=""></head><body>    <div id="checkout-container"></div>    <script src=""></script>    <!-- Include your script to initialize the SDK and send data to Primer -->    <script src="static/client.js"></script></body></html>
// This example is built using expressconst path = require("path");const express = require("express");const fetch = require("node-fetch");const API_KEY = "<YOUR_API_KEY>";const PRIMER_API_URL = "";const app = express();const staticDir = path.join(__dirname, "static");const checkoutPage = path.join(__dirname, "checkout.html");app.use(express.json());app.use(express.static(staticDir));app.get("/", (req, res) => {  return res.sendFile(checkoutPage);});"/client-token", async (req, res) => {  const url = `${PRIMER_API_URL}/auth/client-token`;  const response = await fetch(url, {    method: "post",    headers: {      "Content-Type": "application/json",      "X-Api-Key": API_KEY,    },  });  const json = await response.json();  return res.send(json);});"/authorize", async (req, res) => {  const { token } = req.body;  const url = `${PRIMER_API_URL}/payments`;  const response = await fetch(url, {    method: "post",    headers: {      'Content-Type': 'application/json',      'X-Api-Key': API_KEY,      'X-Idempotency-Key': 'mqum0y1m8n',  // Optionally add an idempotency key    },    body: JSON.stringify({      amount: 700,      currencyCode: "EUR",      orderId: "order-" + Math.random(),      paymentInstrument: {        token: token,      },    }),  });  const json = await response.json();  return res.send(json);});app.listen(process.env.PORT);
// client.jswindow.addEventListener("load", onLoaded);async function onLoaded() {  const clientTokenResponse = await fetch("/client-token", {    method: "post",    headers: { "Content-Type": "application/json" },  });  const { clientToken } = await clientTokenResponse.json();  const primer = new Primer({    credentials: {      clientToken, // Your server generated client token    },  });  // Use `.checkout()` to initialize and render the UI  await primer.checkout({    // Specify the selector of the container element    container: "#checkout-container",    /**     * When a payment method is chosen and the customer clicks 'Pay',     * the payment method is tokenized and you'll receive a token in the     * `onTokenizeSuccess` callback which you can send to your server     * to authorize a transaction.     */    onTokenizeSuccess(paymentMethod) {      // Send the payment method token to your server      return fetch("/authorize", {        method: "post",        headers: { "Content-Type": "application/json" },        body: JSON.stringify(paymentMethod),      });    },  });}




Simulate card payment

Choose a simulation scenario to see an example response



Require 3D secure

© Primer 2021