API Reference flows: Collect · Payout
For hosted checkout (customer pays on a Dollr page with mobile money or card), see Hosted checkout — you can skip payment-account registration and server-side execution.
Collect Payment via Invoice (API-embedded)
This guide covers the document-first collection flow (party → counterparty → invoice → session → payment account → execution). To create a checkout source directly from payer details, see Collect via checkout.
The standard flow for invoicing a customer and collecting payment via mobile money or card from your own UI.
Step 1 — Authenticate
POST /v1/jwt/client/obtain/token
access_token and its expires_in value. Implement proactive refresh before the token expires.
Step 2 — Create a Party
Create a contact record for the customer. Store the returned party.id.
Step 3 — Create a Counterparty
POST /v1/counterparties/create
relationship_type: "CUSTOMER". Store the returned counterparty.id.
Step 4 — Create an Invoice
Pass counterparty_id, currency, note, fee_bearer, and as_payment_link. Store the returned invoice.id.
Step 5 — Add Line Items
POST /v1/invoices/{invoice_id}/items/add
name, currency, qty, amount).
Step 6 — Publish the Invoice
PUT /v1/invoices/publish/{id}
IDLE to ACTIVE. Editing is locked after this point.
Step 7 — (Optional) Preview Fees
GET /v1/predictions/amount-and-fees
base_amount, base_currency, target_currency, payment_method, operation_type, provider, and fee_bearer.
For a published invoice or order, use:
GET /v1/predictions/payment-source/amount-and-fees
source_type (INVOICE or ORDER), source_id, target_currency, payment_method, and provider.
Step 8 — (Optional) Detect payment method
Mobile money:
GET /v1/predictions/mmo-provider-info
payment_method and gateway_provider.
Card:
GET /v1/predictions/card-provider-info
payment_method_id (from your Stripe Elements integration) and operation_type=COLLECTION.
Step 9 — Create a Checkout Session
POST /v1/sessions/checkout
source_id: invoice.id and source_type: "INVOICE". Store the returned session.id.
Step 10 — Create a Payment Account
POST /v1/payment-accounts/create?operation_type=COLLECTION
payment_account.id.
Step 11 — Execute the Collection
POST /v1/executions/collection
session_id, payment_account_id, currency, and your pre-generated reference_id.
For card payments, the response may include requires_action: true and a client_secret for Stripe 3D Secure. Complete authentication in your UI before polling status.
Step 12 — Monitor Status
GET /v1/status/collection/{reference_id}
POST /v1/realtime-keys/collection) for live push updates. Mobile money payments may remain in PROCESSING for several minutes — do not cancel or retry during this window.
You can also check source lifecycle:
GET /v1/status/source?source_type=INVOICE&source_id={id}
Step 13 — Retrieve Receipt
GET /v1/invoices/receipt/{id}
GET /v1/orders/receipt/{id}
PAID. The receipt includes amounts, fees, FX rate, provider, and line items. Use /v1/invoices/receipt/\{id\} for invoices and /v1/orders/receipt/\{id\} for orders.
Receipts are also available by document number:
GET /v1/invoices/receipt/number/{invoice_number}
GET /v1/orders/receipt/number/{order_number}
Issue a Payout
Step 1 — Authenticate
Obtain a Bearer token via POST /v1/jwt/client/obtain/token.
Step 2 — Ensure Recipient Exists
Confirm the recipient has a Party and Counterparty record, or create them.
Step 3 — Create a Payment Account for the Recipient
POST /v1/payment-accounts/create?operation_type=PAYOUT
method and provider from phone.
Step 4 — Create a Payout Session
Pass payout_account_id, amount, and currency. The response includes expires_at and the debiting wallet_id.
Step 5 — Execute the Payout
POST /v1/executions/payout
session_id, payout_account_id, a freshly generated reference_id (UUID v4), and passcode (merchant verification with device metadata). Set up your passcode in the merchant portal — see Payout passcode errors and Payout with Node.js.
Step 6 — Monitor Status
GET /v1/status/payout/{reference_id}
Last modified on June 23, 2026
