Back to Docs

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.

Setup your checkout page

Add the Primer SDK as a dependency

checkout.html

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

Specify a container element

checkout.html

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

Authentication

server.js

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

→ Read about authentication in our Quick Start Guide

Generate a client token

server.js

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 Quick Start Guide

Initialize the SDK

client.js

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

Render the Universal Checkout

client.js

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

server.js

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 about authorization in our Managing Payments Guide

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

See GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<!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="https://assets.primer.io/primer-sdk-web/v1-latest/Checkout.css">
</head>
<body>
    <div id="checkout-container"></div>
    <script src="https://assets.primer.io/primer-sdk-web/v1-latest/Primer.min.js"></script>
    <!-- Include your script to initialize the SDK and send data to Primer -->
    <script src="static/client.js"></script>
</body>
</html>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
// This example is built using express
const path = require("path");
const express = require("express");
const fetch = require("node-fetch");
const API_KEY = "<YOUR_API_KEY>";
const PRIMER_API_URL = "https://api.sandbox.primer.io";
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);
});
app.post("/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);
});
app.post("/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);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// client.js
window.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("/api/authorize", {
        method: "post",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(paymentMethod),
      });
    },
  });
}

Preview

Pay

Primer

Team

Primer Connect

Careers

Terms

Privacy

Connect

Contact

Developers

Docs

API Reference

Status

Connect

Contact

Developers

Docs

API Reference

Status