Integration builder

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

Client

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

Specify a container element

Client

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

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

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

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

Render the Universal Checkout

Client

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

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

paymentMethod: the payment method token
orderId: your reference for a transaction
amount: the transaction amount in minor units
currencyCode: the ISO-4217 (three-letter) currency code
merchantId: the merchant ID (MID) used to process the transaction

→ Find out more about authorization in our Managing Transactions Guide

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<!DOCTYPE html>
<html>
<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 bodyParser = require('body-parser');
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(bodyParser.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}/transactions/auth`
  const response = await fetch(url, {
    method: 'post',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': API_KEY,
      'Idempotency-Key': 'order-123',  // Optionally add an idempotency key
    },
    body: JSON.stringify({
      paymentMethod: token,
      orderId: 'order-123',
      amount: 700,
      currencyCode: 'EUR',
      merchantId: '<YOUR_MERCHANT_ID>',
    }),
  });
  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
window.addEventListener('load', onLoaded);
async function onLoaded() {
  const clientToken = await fetch('/client-token', {
    method: 'post',
    headers: { 'Content-Type': 'application/json' },
  })
    .then((response) => response.json())
    .then((response) => response.clientToken);
  const primer = new Primer({
    credentials: {
      clientToken, // Your server generated client token
    },
  });
  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) {
      return fetch('/authorize', {
        method: 'post',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(paymentMethod),
      });
    },
  });
}

Preview

Pay