Payments

PaymentIntents are the core resource. Full lifecycle + state machine: Payments concept.

Base path: /v1/payment_intents

Create

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

Field	Type	Notes
amount	int	Minor units (cents for eur). Required.
currency	string	ISO 4217. Required.
merchant_reference	string	Your order reference.
description	string	Human-readable descriptor.
metadata	object	Free-form key/value strings.
capture_method	automatic | manual	automatic at launch; manual capture is a planned contract extension.

Response:

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

Confirm

Confirm with a payment token from digid pay Secure Fields:

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

payment_method is the token returned by Secure Fields. Confirmations never accept raw card fields — a number-shaped field is rejected (invalid_request_error, code raw_card_rejected) per the token-only contract.

Possible resulting statuses:

Status	Meaning
processing	Authorising.
requires_action	SCA challenge pending (see SCA).
succeeded	Authorised and captured.
failed	Declined (card_declined, insufficient_funds, …).

Retrieve

curl https://api.digid.cc/v1/payment_intents/pi_1Ab... -u sk_live_...:

List

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

Pagination is cursor-based: has_more + starting_after (see Rate limits & pagination).

Cancel

Cancels an intent that has not reached a terminal state. Allowed from requires_payment_method, requires_action, and requires_approval:

curl -X POST https://api.digid.cc/v1/payment_intents/pi_1Ab.../cancel \
  -u sk_live_...: \
  -H "Idempotency-Key: order-1001-cancel" \
  -H "Content-Type: application/json"

status becomes cancelled; a payment_intent.cancelled webhook fires.

Approve (agent-initiated payments)

Intents created by an agent start in requires_approval. A designated human approver moves them to processing:

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

See Agents for approval semantics. Declining an agent intent = cancelling it.

Idempotency

Every mutating call accepts Idempotency-Key. Replays with the same key return the original result with no second authorisation; a reused key with a different payload returns idempotency_key_reused.

Webhooks

Every state transition emits a webhook (see Webhooks):

payment_intent.processing, .succeeded, .payment_failed, .cancelled, .requires_action, .requires_approval.

Further reading

• Errors — the envelope and codes.
• Refunds — reverse a succeeded intent.