Payments

A PaymentIntent is the digid pay record of a single payment attempt. You create it with an amount and currency, confirm it with a payment token from digid pay Secure Fields, and follow it through webhooks to a terminal state.

Lifecycle

stateDiagram-v2
    [*] --> requires_payment_method: create
    requires_payment_method --> processing: confirm with token
    requires_payment_method --> cancelled: cancel
    requires_action --> processing: SCA completed
    processing --> succeeded
    processing --> failed
    processing --> cancelled
    requires_approval --> processing: human approval
    requires_approval --> cancelled: declined
    succeeded --> [*]
    failed --> [*]
    cancelled --> [*]

States:

State	Meaning
requires_payment_method	Created, waiting to be confirmed with a payment token.
processing	Confirmed; the acquirer is authorising.
requires_action	Paused for an SCA (3-D Secure) challenge. Continues automatically once authenticated.
requires_approval	Agent-initiated payment paused until a human approves (see Agents).
succeeded	Authorised and captured. Terminal.
failed	Declined or could not be processed. Terminal.
cancelled	Cancelled before completion. Terminal.

Create and confirm

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

{
  "id": "pi_1Ab...",
  "object": "payment_intent",
  "amount": 4990,
  "currency": "eur",
  "status": "requires_payment_method",
  "livemode": true,
  "client_secret": "pi_1Ab..._secret_...",
  "created_at": "2026-09-08T09:00:00Z"
}

client_secret is bound to the intent and is the only secret your client-side code should hold. Confirm server-side:

curl https://api.digid.cc/v1/payment_intents/pi_1Ab.../confirm \
  -u sk_live_...: \
  -H "Idempotency-Key: order-2041-confirm" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method": "pmt_..." }'

The response reflects the new state — processing, requires_action (SCA), or a terminal state.

Idempotency

Every mutating request accepts an Idempotency-Key header. Replaying the same key returns the original result and never creates a second charge:

curl https://api.digid.cc/v1/payment_intents/pi_1Ab.../confirm \
  -u sk_live_...: \
  -H "Idempotency-Key: order-2041-confirm" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method": "pmt_..." }'

Send the same key again → same response, no new authorisation. A mismatch (e.g. a reused key with different payload) returns idempotency_key_reused.

Money

Amounts are integers in the currency's minor units (cents for eur, pence for gbp). Never use floats.

{ "amount": 1000, "currency": "eur" }   // €10.00
{ "amount": 1500, "currency": "dkk" }   // kr15.00

Retrieve and list

curl https://api.digid.cc/v1/payment_intents/pi_1Ab... -u sk_live_...:
curl "https://api.digid.cc/v1/payment_intents?limit=25&starting_after=pi_..." -u sk_live_...:

Cross-tenant resources return 404, never 403, so existence is not leaked between merchants.

Agent-initiated payments

Intents created by an agent begin in requires_approval and only proceed after an explicit human approval:

curl https://api.digid.cc/v1/payment_intents/pi_1Ab.../approve \
  -u sk_live_...: \
  -H "Idempotency-Key: approval-order-2041" \
  -H "Content-Type: application/json"

See Agents for the full agent flow and approval semantics.

Refunds

Refunds are separate objects tied to a succeeded PaymentIntent — full or partial, never exceeding the original capture. See Refunds.