API reference

The POS API is a small, predictable REST surface: JSON in, JSON out, Bearer-key auth. Base URL for all endpoints:

Base URL

https://quirky-chameleon-588.convex.site

Authentication#

Pass your API key as a Bearer token on every request (except the public session status endpoint). Keys are generated and rotated on the Integrations page.

Header

Authorization: Bearer dgp_live_YOUR_KEY

If you've configured an IP allowlist, requests from other addresses fail with 401 — indistinguishable from a bad key, by design.

Create a session#

POST/api/v1/sessions

Creates a payment session (one charge) and returns the QR payload to display.

Field	Type	Notes
`amountCents`	number · required	> 0 and ≤ 100,000,00 ($100,000).
`orderRef`	string · optional	Echoed in webhooks.
`taxCents`	number · optional	Informational.
`tipCents`	number · optional	Informational.
`customerEmail`	string · optional	Receipt email.

Response · 201

{
  "sessionId": "j5xkg8...",
  "status": "PENDING",
  "expiresAt": 1746489600000,
  "qrPayload": "digipae://qr/j5xkg8...",
  "idempotent": false
}

Send an Idempotency-Key header to make creation retry-safe: the same key returns the original session with "idempotent": true instead of creating a duplicate charge.

Get a session#

GET/api/v1/sessions/:sessionId

API-key-scoped status of a session you created. Returns 404for sessions that don't exist or don't belong to you. Statuses: PENDING → COMPLETED · FAILED · EXPIRED · CANCELLED.

No API key. Payer-facing status for browser widgets: merchant name, amount, and live status only. The unguessable session id is the capability — safe to call from the client. Expired sessions lazily flip to EXPIRED on read.

Get merchant profile#

GET/api/v1/merchant/me

Returns your merchant profile and API-key metadata — useful as a smoke test that your key and IP allowlist are configured correctly.

curl

curl https://quirky-chameleon-588.convex.site/api/v1/merchant/me \
  -H "Authorization: Bearer dgp_live_YOUR_KEY"

Rotate API key#

POST/api/v1/keys/rotate

Invalidates your current key and returns a new one once. The old key stops working immediately — deploy the new key to your servers as part of the same operation.

Response · 200

{
  "fullKey": "dgp_live_...",
  "prefix": "dgp_live_ab12",
  "warning": "Store this key securely — it will not be shown again."
}

Errors#

Status	Meaning
`400`	Invalid JSON body, or invalid amountCents.
`401`	Missing/invalid API key — or your IP isn't on the configured allowlist.
`403`	Merchant account not active.
`404`	Session not found (or not yours).
`429`	Rate limit exceeded — back off and retry.

Error bodies are JSON: { "error": "message" }.

CORS#

All /api/v1/* endpoints answer preflight OPTIONS with Access-Control-Allow-Origin: * and allow the Authorization, Content-Type, and Idempotency-Key headers.

CORS being open does not mean your API key belongs in a browser. Keep keys server-side; the only endpoint designed for direct browser use is /api/v1/public/sessions/:id.

Webhooks#

Event delivery, signatures, and retry behavior are covered in Webhooks.