Quickstart

Status note. The sandbox environment is live today. Open public sandbox keys are planned (provisioning task), and the REST API contract is contract until the facade ships. The examples below are written against that exact contract — placeholder keys are pk_sandbox_… / sk_sandbox_….

Two paths, same object model:

• Snippet path (recommended) — zero-API: your server creates a PaymentIntent, digid pay Secure Fields on your page capture the card, and the snippet confirms the payment. You never build or host a card form.
• API path — your own UI around the same Secure Fields capture, driving the REST API directly.

Both start in the sandbox: no money moves, test rails only, and every request is authenticated with sandbox-scoped keys.

0. Get sandbox keys

Request access through the signup flow at https://digid.cc/signup. Once your sandbox merchant account exists, create a key pair in the digid pay dashboard or over the API (see Authentication). You will receive a pk_sandbox_… publishable key and a sk_sandbox_… secret key. The secret is shown once — store it in your secret manager and never expose it in client-side code.

1. Snippet path

1a. Server: create a PaymentIntent

curl https://api.digid.cc/v1/payment_intents \
  -u sk_sandbox_...: \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2490,
    "currency": "eur",
    "merchant_reference": "order-1001"
  }'

The response carries id (pi_…) and client_secret, plus status: requires_payment_method.

1b. Client: embed the snippet with your client_secret

The checkout snippet loads once, then renders the Secure Fields and confirms on submit:

<script src="https://assets.digid.cc/checkout.v1.js" integrity="sha384-…" crossorigin="anonymous"></script>

<div id="digid-checkout"></div>

const checkout = await digidPay.checkout({
  clientSecret: 'pi_..._secret_...',   // server-provided, bound to the intent
  publishableKey: 'pk_sandbox_...',
  onEvent: (event) => {
    // 'payment_intent.succeeded' | 'payment_intent.payment_failed' | ...
    console.log(event.type, event.paymentIntent)
  },
})
checkout.mount('#digid-checkout')

The snippet captures the card in digid pay Secure Fields, tokenizes it inside the digid pay tokenization vault, confirms the PaymentIntent, and runs any required SCA challenge in place. When it finishes you receive the matching event and your server gets a webhook.

1c. Server: confirm from your backend (alternative to client confirm)

If you prefer to confirm server-side, capture the token through Secure Fields on your own form (the Secure Fields guide), then:

curl https://api.digid.cc/v1/payment_intents/pi_.../confirm \
  -u sk_sandbox_...: \
  -H "Idempotency-Key: order-1001-confirm" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method": "pmt_test_..." }'

2. API path

Build your own checkout UI around Secure Fields and call the REST API for every step:

1. Create the PaymentIntent (above).
2. Render Secure Fields with the publishable key and client_secret to capture the card and mint a payment token (see the Secure Fields guide).
3. Confirm with the token (above).
4. Fulfil on the payment_intent.succeeded webhook — never on a client callback alone.

Shopper → your page → digid pay Secure Fields → token
        → your server → POST /payment_intents/{id}/confirm → SCA if needed
        → webhook payment_intent.succeeded → fulfil

3. Observe it

Every state transition emits a webhook to any endpoint you register (Webhooks). Use the sandbox test cards in Sandbox to force declines, SCA challenges, and timeouts, and see each state in the dashboard transaction list.

• succeeded with test card 4242 4242 4242 4242
• requires_action with the SCA test card
• failed with a decline card
• cancelled when you cancel before confirm

4. Go live

When integration is green in sandbox, request activation from the dashboard. Activation is operator-reviewed (Accounts); on approval your account gains live mode and you mint live keys. Follow Go live for the checklist — webhooks on, monitoring set, first real payment.

Where next

• Sandbox — test rails, keys, cards, limits.
• Payments API — full request/response reference.
• Tokens — why card data never touches you.