# Dollr Developer Documentation

> Dollr is a payment infrastructure platform for businesses operating in Africa. It provides a single REST API to collect mobile money and card payments, send payouts, process transfers, and issue refunds — abstracting MTN, Orange, Airtel, and international card networks into one consistent interface.
>
> **Production docs:** https://docs.heydollr.app  
> **AI / MCP:** https://docs.heydollr.app/reference/ai-context · https://docs.heydollr.app/llms.txt · Docs MCP `https://docs.heydollr.app/mcp`  
> **API base URL:** https://api.heydollr.app  
> **OpenAPI:** https://api.heydollr.app/openapi.json  
> **Merchant portal:** https://merchant.heydollr.app  
> **Current version:** v1 (JSON, OAuth 2.0 client credentials)

---

## Authentication

POST `client_id` and `client_secret` to `/v1/jwt/client/obtain/token`. Use `Authorization: Bearer <access_token>` on all protected routes. `expires_in` is in **minutes** — refresh proactively (recommended: new token when under 5 minutes remain).

**API Reference:** https://docs.heydollr.app/api-reference/jwt/client-obtain-token

---

## Payments by market (methods & providers)

| Market | Method enum | Provider |
|--------|-------------|----------|
| Liberia | `MTN_MOMO_LBR`, `ORANGE_MONEY_LBR` | `PAWAPAY` |
| Rwanda | `AIRTEL_RWA`, `MTN_MOMO_RWA`, `ORANGE_MONEY_RWA` | `PAWAPAY` |
| International | `CREDIT_CARD` | `STRIPE` |
| Platform | `WALLET` | `PLATFORM` |

Full matrix: https://docs.heydollr.app/reference/payments-by-market

Detect MoMo operator from phone: `GET /v1/predictions/mmo-provider-info?phone={e164_no_plus}&operation_type=COLLECTION`

---

## Core concepts

- **Party** — Contact (name, phone, optional email, country).
- **Counterparty** — Party linked to your merchant (`CUSTOMER`, `SUPPLIER`, `EMPLOYEE`, `BENEFICIARY`, `OTHER`).
- **Invoice / Order** — Payment sources; publish before collection. Orders omit formal invoice number/due date.
- **Checkout** — `POST /v1/checkouts/create` can auto-create Party/Counterparty from payer details.
- **Session** — Intent: checkout, payout, transfer, refund. Expires if not executed.
- **Execution** — Moves funds; requires `session_id`, `payment_account_id`, `currency`, unique UUID v4 `reference_id` (idempotency key — generate and store **before** the HTTP call).
- **Payment account** — Wallet/card bound to a Party for a given `method` + `provider`.
- **Fee bearer** — `PAYER` (customer pays fees on top) or `PAYEE` (merchant absorbs).

**Glossary:** https://docs.heydollr.app/reference/glossary

---

## Standard collection flow (invoice)

1. `POST /v1/jwt/client/obtain/token`
2. `POST /v1/parties/create`
3. `POST /v1/counterparties/create`
4. `POST /v1/invoices/create` → add items → `PUT /v1/invoices/publish/{id}`
5. `GET /v1/predictions/mmo-provider-info` (recommended)
6. `POST /v1/payment-accounts/create?operation_type=COLLECTION`
7. `POST /v1/sessions/checkout`
8. `POST /v1/executions/collection` (with stored `reference_id`)
9. `GET /v1/status/collection/{reference_id}` until `COMPLETED` or `FAILED`

**Quick Start:** https://docs.heydollr.app/quickstart  
**Choose integration:** https://docs.heydollr.app/guides/choose-integration  
**Collect (Node / Python / checkout):** https://docs.heydollr.app/guides/collect-with-nodejs  
**Full index:** https://docs.heydollr.app/llms-full.txt

---

## Direct checkout (skip invoice steps 2–6)

`POST /v1/checkouts/create` — https://docs.heydollr.app/api/checkouts  
**API Reference:** https://docs.heydollr.app/api-reference/checkouts/create-checkout-source

---

## Status models (do not conflate)

- **Execution:** `PENDING` → `PROCESSING` → `COMPLETED` | `FAILED`
- **Invoice/Order source:** `IDLE` → `ACTIVE` → `PROCESSING` → `PAID` | `CANCELED`
- MoMo may stay `PROCESSING` for minutes — poll status; do not retry with a new `reference_id` during this window.

**Status & incidents:** https://docs.heydollr.app/reference/status-and-incidents

---

## HTTP status codes (summary)

| Code | Action |
|------|--------|
| 200 | Success |
| 401 | Refresh JWT |
| 403 | Permissions / verification |
| 404 | Wrong resource ID |
| 422 | Fix payload — see `detail[]` |
| 429 | Back off; honor `Retry-After` |
| 5xx | Retry with backoff; then support |

**Error handling:** https://docs.heydollr.app/guides/error-handling  
**Error catalog (common messages):** https://docs.heydollr.app/reference/error-catalog

---

## API Guide ↔ API Reference

Prose guides live under `/api/*`. Interactive OpenAPI pages live under `/api-reference/*`. Examples:

| Guide | API Reference entry points |
|-------|---------------------------|
| Parties | `/api-reference/parties/create-party` |
| Invoices | `/api-reference/invoices/create-invoice`, `publish-invoice` |
| Executions | `/api-reference/executions/collect`, `payout`, `transfer`, `refund` |
| Status | `/api-reference/status/get-collection-status` |
| Predictions | `/api-reference/predictions/predict-mmo-provider-info` |

---

## Documentation index

### Getting started

- [Introduction](https://docs.heydollr.app/)
- [Quick Start](https://docs.heydollr.app/quickstart)
- [Changelog](https://docs.heydollr.app/changelog) — API and docs release notes (RSS: /changelog/rss.xml)
- [Choose integration](https://docs.heydollr.app/guides/choose-integration)
- [Authentication](https://docs.heydollr.app/authentication)
- [API conventions](https://docs.heydollr.app/api-conventions)

### Guides

- [Collect with Node.js](https://docs.heydollr.app/guides/collect-with-nodejs)
- [Collect with Python](https://docs.heydollr.app/guides/collect-with-python)
- [Collect with Django](https://docs.heydollr.app/guides/collect-with-django)
- [Collect with Ruby](https://docs.heydollr.app/guides/collect-with-ruby)
- [Payout with Node.js](https://docs.heydollr.app/guides/payout-with-nodejs)
- [Collect with PHP](https://docs.heydollr.app/guides/collect-with-php)
- [Collect with Java](https://docs.heydollr.app/guides/collect-with-java)
- [Collect with Go](https://docs.heydollr.app/guides/collect-with-go)
- [Collect with Rust](https://docs.heydollr.app/guides/collect-with-rust)
- [Collect with .NET](https://docs.heydollr.app/guides/collect-with-dotnet)
- [Collect with Next.js](https://docs.heydollr.app/guides/collect-with-nextjs)
- [Collect with Laravel](https://docs.heydollr.app/guides/collect-with-laravel)
- [Collect via checkout](https://docs.heydollr.app/guides/collect-via-checkout)
- [Integration guide](https://docs.heydollr.app/guides/integration)
- [Realtime status](https://docs.heydollr.app/guides/realtime-status)
- [Error handling](https://docs.heydollr.app/guides/error-handling)

### Concepts

- [Parties & counterparties](https://docs.heydollr.app/concepts/parties-and-counterparties)
- [Sessions & executions](https://docs.heydollr.app/concepts/sessions-and-executions)

### API concepts

- [Parties](https://docs.heydollr.app/api/parties)
- [Counterparties](https://docs.heydollr.app/api/counterparties)
- [Invoices](https://docs.heydollr.app/api/invoices)
- [Orders](https://docs.heydollr.app/api/orders)
- [Checkouts](https://docs.heydollr.app/api/checkouts)
- [Sessions](https://docs.heydollr.app/api/sessions)
- [Executions](https://docs.heydollr.app/api/executions)
- [Transaction Status](https://docs.heydollr.app/api/status)
- [Payment Accounts](https://docs.heydollr.app/api/payment-accounts)
- [Payment Links](https://docs.heydollr.app/api/links)
- [Predictions](https://docs.heydollr.app/api/predictions)
- [Fees](https://docs.heydollr.app/api/fees)
- [Merchants](https://docs.heydollr.app/api/merchants)
- [Realtime Keys](https://docs.heydollr.app/api/realtime-keys)

### Resources

- [Payments by Market](https://docs.heydollr.app/reference/payments-by-market)
- [Examples & tools](https://docs.heydollr.app/reference/examples)
- [Error Catalog](https://docs.heydollr.app/reference/error-catalog)
- [Status & Incidents](https://docs.heydollr.app/reference/status-and-incidents)
- [Glossary](https://docs.heydollr.app/reference/glossary)
- [SDKs](https://docs.heydollr.app/reference/sdks)
- [Support](https://docs.heydollr.app/reference/support)

### External

- [OpenAPI JSON](https://api.heydollr.app/openapi.json)
- [Help Center](https://dollr.tawk.help)
- [Developer email](mailto:dev@heydollr.app)

---

## Support checklist

Include: `reference_id`, request/response bodies (redacted secrets), HTTP status, timestamp (UTC), `method`, `provider`, market.