Get started - Primer

This feature is not available on all Primer accounts. Contact your Customer Success Manager for access.

Do this once per account: what Primer sets up for you, what you set up yourself, and how to test in the sandbox before going live. Then follow Your first payment for the integration itself.

What Primer sets up for you

Before your first payment, your Primer representative sets up three things on your account:

Vault enabled. The proxy rejects every request from an account that isn’t enabled for Primer Vault.
Card available in the checkout builder, without a processor. You turn Card on in the Checkout builder with your usual conditions, the same way an orchestration merchant does. There’s nothing vault-specific to configure for the card form itself.
Your PSP destinations, allowlisted. The proxy only forwards to a PSP host that’s on your account’s allowlist, so a stolen API key can’t be used to send card data anywhere else. For now, your Primer representative sets this list up for you from the hosts you give them; self-service management is planned but not available yet. The list is per environment. See Environments below.

What you do

Create an API key with the right permissions. In Developers, create a key scoped to:
- client_tokens:write, to create the client session.
- payment_instrument:read, to read the vaulted card.
- A permission for the proxy and for saving a vaulted card. At the time of writing this is new and the dashboard scope isn’t finalized. Confirm the exact scope name with your Primer representative.
A vault-only integration doesn’t need transactions:authorize, transactions:capture, or the other payment-processing scopes, since you never ask Primer to create a payment.
Point your PSP client at the proxy. Wherever your backend configures its Stripe, Adyen, or other PSP client, change the base URL to the proxy host and add the two Primer headers. See Send the request through the proxy for the exact headers and a worked example per PSP.

Environments

Primer Vault has separate sandbox and production hosts, and a key or token from one environment never works in the other:

	Sandbox	Production
Primer API	`api.sandbox.primer.io`	`api.primer.io`
Primer proxy	`proxy.sandbox.primer.io`	`proxy.primer.io`
API keys	Sandbox keys only	Production keys only
Client tokens and payment method tokens	Valid only against the sandbox API	Valid only against the production API
PSP destinations	Your PSP’s test/sandbox host	Your PSP’s live host

Create separate API keys for each environment, and keep your destination allowlist for sandbox pointed at your PSP’s test hosts, not its live ones. Mixing them up either leaks a test card to your live PSP account or fails outright, since the host on your allowlist for one environment generally isn’t the host you want in the other.

Testing in the sandbox

Test the full flow in sandbox before going live:

Use your PSP’s own test/sandbox mode. The proxy forwards to whatever host is on your sandbox allowlist; put your PSP’s test host there (for example, Adyen’s test endpoints are on a different hostname than its live ones, while Stripe uses the same host with a test secret key; check your PSP’s own docs for which applies).
Use test cards from your PSP, not from Primer. The card is tokenized by Primer, but the authorization itself happens at your PSP, so the test card numbers and expected outcomes (approved, declined, requires 3DS) are your PSP’s, the same ones you’d use calling them directly today.
Test the outcomes you’ll see in production: a successful proxy payment with the card vaulted, a decline reported back to Primer, a 3DS challenge, and the fallback to Primer approval if you’ve also connected a processor.

Checklist before going live

Vault enabled on your production account.
Card enabled in the Checkout builder.
A production API key with the right permissions, kept separate from your sandbox key.
Your PSP’s live host on your production destination allowlist.
Your PSP client pointed at the production proxy host with your live PSP credential.
A full payment, a decline, and a 3DS challenge tested end to end in sandbox.

Your first payment

The simplest case: every payment goes to your own PSP, with no Primer fallback. One complete example, from creating the session to showing the result. 1. Create the client session.

curl -X POST https://api.sandbox.primer.io/client-session \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Version: 2.4" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-123",
    "currencyCode": "USD",
    "amount": 1000,
    "customerId": "customer-456",
    "mode": "MANUAL"
  }'

See Create the client session for the required fields and what each one is for. 2. Load the checkout.

<primer-checkout client-token="your-client-token"></primer-checkout>

3. Listen for the approval event.

const checkout = document.querySelector('primer-checkout');

checkout.addEventListener('primer:payment-approval-required', async (event) => {
  const { paymentAttemptId, paymentMethodToken, continueFlow } = event.detail;

  await fetch('/my-backend/handle-payment', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ paymentAttemptId, token: paymentMethodToken.token }),
  });

  await continueFlow();
});

See Show the checkout and capture the card for the full event payload. 4. Send the request through the proxy.

curl -X POST https://proxy.sandbox.primer.io/v1/payment_intents \
  -H "X-Primer-Api-Key: YOUR_API_KEY" \
  -H "X-Target-Host: api.stripe.com" \
  -H "Authorization: Bearer YOUR_PSP_SECRET_KEY" \
  -d "amount=1000&card[number]={{tok_abc.NUMBER}}&card[exp_month]={{tok_abc.EXPIRY_MONTH}}&card[exp_year]={{tok_abc.EXPIRY_YEAR}}&card[cvc]={{tok_abc.CVV}}"

See Send the request through the proxy for the full placeholder reference and a second example for Adyen. 5. Resolve the attempt.

curl -X POST https://api.sandbox.primer.io/payment-attempts/{paymentAttemptId}/resolve \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Version: 2.4" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "SUCCEEDED", "vaultPaymentMethod": true }'

See Report the outcome for the full request, response, and error codes. 6. Call continueFlow().

checkout.addEventListener('primer:payment-success-external', (event) => {
  const { paymentAttemptId } = event.detail;
  window.location.href = `/confirmation?attempt=${paymentAttemptId}`;
});

That’s the whole flow for a card that always goes to your own PSP. During the payment covers every step in detail, including deciding per payment whether to use Primer or your own PSP, and falling back to Primer if your PSP declines.

Bring your existing cards

If you already store cards at your current processor or in another vault, you can bring them into Primer rather than asking every customer to re-enter their card. This is the same token migration process used by merchants moving onto Primer orchestration, and there’s nothing vault-specific about it. Your current processor’s token files are transferred to Primer (by SFTP, either direction), and Primer imports them and issues a Primer token for each card. Who does what:

You arrange for your current processor to hand over the token files, following Token migration for the transfer method (processor-hosted SFTP, or Primer’s).
Primer imports the files and issues a saved (multi-use) token for each card, usable through the proxy exactly like a card saved from a vault payment, and tells you via the Support Portal once the migration is done.

The reverse direction, exporting your Primer-vaulted tokens to a different provider, is covered separately in Token export. Timelines depend on token volume and how quickly your current processor completes their side; talk to your Primer representative before you start.

​What Primer sets up for you

​What you do

​Environments

​Testing in the sandbox

​Checklist before going live

​Your first payment

​Bring your existing cards

What Primer sets up for you

What you do

Environments

Testing in the sandbox

Checklist before going live

Your first payment

Bring your existing cards