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
Exchange your Client ID and Client Secret for a Bearer token. Store the 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
Link the Party to your merchant account with 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
Repeat for each line item (name, currency, qty, amount).
Step 6 — Publish the Invoice
Transitions the invoice from IDLE to ACTIVE. Editing is locked after this point.
Step 7 — (Optional) Preview Fees
Validate fee calculations and FX rates before funds move. Required query params include base_amount, base_currency, target_currency, payment_method, operation_type, provider, and fee_bearer.
For a published invoice or order, use:
Pass source_type (INVOICE or ORDER), source_id, target_currency, payment_method, and provider.
Step 8 — (Optional) Detect payment method
Mobile money:
Pass the customer’s phone number to get the recommended payment_method and gateway_provider.
Card:
Pass payment_method_id (from your Stripe Elements integration) and operation_type=COLLECTION.
Step 9 — Create a Checkout Session
Pass source_id: invoice.id and source_type: "INVOICE". Store the returned session.id.
Step 10 — Create a Payment Account
Register the customer’s mobile wallet or card. Store the returned payment_account.id.
Step 11 — Execute the Collection
Store your reference_id first
Generate a UUID v4 and persist it before calling this endpoint. If the HTTP response is lost due to a network error, you will need this ID to query the transaction status before retrying.
Pass 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
Poll for status, or use a Realtime Key (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:
Step 13 — Retrieve Receipt
Retrieve the receipt once the collection execution is successful and the source status is 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:
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
Register the beneficiary’s mobile wallet. Use MMO prediction to resolve 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
Pass 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
Last modified on June 23, 2026
