Concepts

The conomy_hq platform is built around a small set of entities that map directly to the API surface. Understanding how they relate is the fastest path to a clean integration.

---

Entity map

• Identity owns one or more Accounts.

• Accounts are the internal balance ledgers that pay-ins fund and pay-outs draw from.

• Payments move funds between an Account and an external rail (or between two Accounts on internal types).

• Customers are the end users on whose behalf a payment moves. Documents attached to a Customer drive the compliance review gate.

• Refunds are child Payments linked to a parent via parentPaymentId. The parent stays SETTLED.

• Webhooks notify your integration when a Payment or Customer changes state.

---

Quick definitions

Concept	Lives in	Created via
Identity	Tenant scope	POST /identities
Account	Inside an Identity	POST /accounts
Customer	Tenant scope	POST /customers (or auto-created on first matching topup)
Payment	Tenant scope	POST /payments
Refund	Child of Payment	POST /payments/{id}/refund
Document	Inside a Payment or Customer	POST /payments/{id}/documents or POST /customers/{id}/documents

For the full vocabulary, see Glossary.

---

Lifecycle in one diagram

Every Payment progresses through this state machine. See Payment status for what each transition means and which webhook fires on each step.

---

Where to go next

• Payment structure — fields and required values.

• Origins and destinations — rails available per country.

• Compliance — review gate, customer levels, supported documents.

• Quickstart — first request in under an hour.