Get started

A quick overview of an end-to-end integration with Primer. Start here!

Integrating with Primer

This guide shows you how to create a checkout page, accept payments across multiple processors and add alternative payment methods using our Universal Checkout. If you'd like to learn more about customizing your checkout, head to our Build your checkout guide.


Creating an account
Primer is in limited release, please contact us to discuss your payment needs.

Environments

Before going live, test your payments integration against our dedicated Sandbox environment. Visit our Testing with Primer page for more information.

API Authentication

Authentication is handled via the X-Api-Key header. Create and manage API keys and scopes from the Dashboard in the Developers area.

This example shows how to use your API key to authenticate against our API.

1
2
3
curl --location --request \
POST 'https://api.sandbox.primer.io/auth/client-token' \
--header 'X-Api-Key: <YOUR_API_KEY>'
curl

Adding a processor connection

With Connections, you can seamlessly add processors, fraud providers, BI tools, accounting software and many other services across your payments services stack.

To add a processor connection, visit the Connections area in the Dashboard.

Setting up your secure checkout page

Capturing & storing payment methods

Storing sensitive payment information poses many risks. Primer's Tokenization service transforms sensitive payment information into an opaque string, called a token.

Primer generates single-use tokens for all payment methods at checkout, enabling you to process payments uniformly via our API regardless of the payment method type. A payment method token can be used across all processor connections (provided the processor supports it).

Payment methods can also be stored in our secure vault for recurring or future payments across different processors. Learn more about vaulting in our Managing transactions guide.

Our checkout libraries enables you to fully host, customize and configure your checkout without exposure to sensitive payment information. To learn more about customizing and building your checkout, visit our Build your checkout guide.

Generating a client token

You must generate a client token in order to initialize the checkout SDK. Client tokens expire after 24 hours.

1
2
3
curl --location --request \
POST 'https://api.sandbox.primer.io/auth/client-token' \
--header 'X-Api-Key: <YOUR_API_KEY>'
curl

The response returned will have a clientToken and expirationDate as shown below.

1
2
3
4
{
"clientToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NUb2tlbiI6IjBmZTRkNzE4LWZkYjgtNGZjOC1iNWQ0LTE5MzMwZDg4NmE0YyIsImNvbmZpZ3VyYXRpb25VcmwiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvY2xpZW50LXNkay9jb25maWd1cmF0aW9uIiwicGF5bWVudEZsb3ciOiJERUZBVUxUIiwidGhyZWVEU2VjdXJlSW5pdFVybCI6Imh0dHBzOi8vc29uZ2JpcmRzdGFnLmNhcmRpbmFsY29tbWVyY2UuY29tL2NhcmRpbmFsY3J1aXNlL3YxL3NvbmdiaXJkLmpzIiwidGhyZWVEU2VjdXJlVG9rZW4iOiJleUowZVhBaU9pSktWMVFpTENKaGJHY2lPaUpJVXpJMU5pSjkuZXlKcWRHa2lPaUpoWlRNMU9HSTVOUzA1TldJd0xUUTRPVEV0WWpNNU9DMHlNR1ExTlRZMU9HWXhaVGNpTENKcFlYUWlPakUyTURFd016QTFPRGtzSW1semN5STZJalZsWWpWaVlXVmpaVFpsWXpjeU5tVmhOV1ppWVRkbE5TSXNJazl5WjFWdWFYUkpaQ0k2SWpWbFlqVmlZVFF4WkRRNFptSmtOakE0T0RoaU9HVTBOQ0o5LkFnXzQwTDhKTmNuV2V5V3V3aDZEcUlBZ1pyQl9Ob3hPQXZoVEw1TUlEb1kiLCJjb3JlVXJsIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwIiwicGNpVXJsIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgxIiwiZW52IjoiTE9DQUxfRE9DS0VSIn0.MXWJNxakJ_L8MBOgDf_IuM7mwODKWoiRsXX_nFYTTMA",
"expirationDate": "2020-09-26T10:43:09.851894"
}
json

Building your checkout page


Security
If your checkout page uses the Content-Security-Policy header, you'll need to add a few things to your whitelist.

Include our checkout libraries on your checkout page, and specify a container element.

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.js"></script>
<!-- Include your script to initialize the SDK and send data to Primer -->
<script src="static/checkout.js"></script>
</body>
</html>
html

Securely capturing payment details

Initialize the SDK with your server-generated client token, and assign a selector to the checkout container. Primer avails individual iframes hosted in our PCI compliant infrastructure, meaning you don't have to worry about PCI burden, and removing exposure to sensitive payment data.

The onTokenizeSuccess callback receives a single-use payment method token which can be safely passed to your server for authorization.

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
// checkout.js
window.addEventListener('load', onLoaded)
async function onLoaded() {
const primer = new Primer({
credentials: {
clientToken: '<YOUR_CLIENT_TOKEN>', // 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 recieve 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
fetch('<YOUR_SERVER_URL>', {
method: 'post',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(paymentMethod),
})
},
})
}
js

Authorizing a transaction

You can now authorize the transaction against your processor of choice, using the payment method you just generated. Parameters to authorize a transaction:

ParametersDescription
paymentMethodA one-time use token generated from our checkout libraries, or a recurring token retrieved from the Vault API. e.g. hXIHB_WfR2-M6PM13JDmQnwxNjAxMTE3NTA4. One-time use tokens expire after 15 minutes.
orderIdYour reference for the transaction.
amountThe amount you would like to charge the customer, in minor units. e.g. for $7, use 700.
currencyCodeThe 3 digit currency code in ISO 4217 format. e.g. use USD for US dollars.
merchantIdThe unique merchant ID associated with your processor. Learn how to retrieve your merchant ID.
vaultVault options to store payment methods (if supported).
Optional
unless vaulting.
customerDetailsDetails about your customer. e.g. shipping, billing address.
Optional
unless vaulting.
captureWhether or not the transaction should be directly submitted for settlement upon succesful authorization. true by default, or specify false for authorization-only requests.
Optional

The response body will contain a Transaction object which is generic across processors, containing Primer's transaction status, risk data (AVS/CVV) associated with the transaction, your order ID and our unique transaction ID (which you will use for subsequent requests). Statuses are unified across all processors and payment methods.

Learn about statuses, recurring payments, and downstream requests in Managing transactions.

1
2
3
4
5
6
7
8
9
10
11
curl --location --request \
POST 'https://api.sandbox.primer.io/transactions/auth' \
--header 'X-Api-Key: <YOUR_API_KEY>' \
--header 'Idempotency-Key: order-123' \
--data '{
"paymentMethod": "token",
"orderId": "order-123",
"amount": 700,
"currencyCode": "EUR",
"merchantId": "<YOUR_MERCHANT_ID>"
}'
curl

Congratulations - you've integrated a new processor via our Transactions API and Universal Checkout. How easy was that?

Adding other payment methods

You've now implemented the building blocks to accept payments across all payment method types! Let's add the option to pay with an alternative payment method.

First, add your payment method in Connections, for this example we'll use Apple Pay.

Provide some additional required transactional data for Apple Pay:

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
// checkout.js
async function onLoaded() {
await primer.checkout({
// In addition to the other options above
// Add your company's alpha2 ISO country code
countryCode: 'FR',
// Add the total sale amount for the APM to display
purchaseInfo: {
totalAmount: {
currency: 'EUR',
value: 700,
},
},
// Carry on with sending the token to your server for authorization.
onTokenizeSuccess(paymentMethod) {
fetch('<YOUR_SERVER_URL>', {
method: 'post',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(paymentMethod),
})
},
})
}
js

Believe it or not, that's it. No additional server-side work is required, as Primer generates a uniform, opaque token across all payment method types. You can now seamlessly process Apple Pay transactions across the processor connections which support it.

Now, go ahead and add additional processors, payment pethods, and get started with Workflows to automate payments logic and routing across your payments stack.