Skip to main content

​
Session

A session declares intent to run an operation: checkout (collect) or payout. Create a session against a payment source (invoice, order, or checkout-created source), then execute it before the session expires.
API Reference: Checkout session · Payout session
Hosted checkout skips server-side sessions and executions — the customer pays on a Dollr page. See Hosted checkout.

​
Execution

An execution submits an active session and moves funds. Collection requires:
  • session_id
  • payment_account_id (registered wallet or card)
  • currency
  • reference_id — UUID v4 you generate before the HTTP call
Payout requires session_id, payout_account_id, reference_id, and passcode (merchant verification with device metadata).
reference_id is your idempotency key. If the network fails, poll status with the same reference_id before retrying. Never mint a new UUID until you confirm the original attempt did not land.

​
Card 3D Secure

Collection executions for cards may return requires_action: true and a client_secret. Complete Stripe authentication in your UI before polling status. See Collect with card.

​
Two status models

ModelTracksExample values
ExecutionMovement of fundsPENDING → PROCESSING → COMPLETED | FAILED
Source (invoice/order)Document lifecycleIDLE → ACTIVE → PROCESSING → PAID | CANCELED
Mobile money often stays in PROCESSING for several minutes. Poll execution status; do not re-execute during that window.

​
Poll execution status

GET /v1/status/collection/{reference_id}
GET /v1/status/payout/{reference_id}
For hosted checkout, you can also check source status: 
GET /v1/status/source?source_type=INVOICE&source_id={id}

​
Fee bearer

  • PAYER — Customer pays fees on top of the total; merchant receives the full invoice amount.
  • PAYEE — Merchant absorbs fees; customer pays the listed total.
Last modified on June 23, 2026