FundamentalsConcepts
Concepts
Core concepts and how they relate — Identity, Account, Payment, Customer, Document.
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
Section titled “Entity map”Owns accounts and delegates permissions.
Internal balance ledger used by payment flows.
Moves funds through origins and destinations.
End user tied to checkout and compliance flows.
Evidence attached for review gates.
Asynchronous notification after state changes.
- 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 staysSETTLED. - Webhooks notify your integration when a Payment or Customer changes state.
Quick definitions
Section titled “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 with type: REFUND and parentPaymentId |
| 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
Section titled “Lifecycle in one diagram”The payment exists and can generate rail instructions.
Funds are reserved when the rail supports authorization.
The platform asks the provider to move the funds.
The provider confirms that the funds arrived.
Reconciliation is complete and the destination is funded.
Review, timeout, and reconciliation branches move the payment to REQUIRES_REVIEW, FAILED, EXPIRED, or UNSETTLED depending on the event.
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
Section titled “Where to go next”- Payment structure — fields and required values.
- Origins and destinations — rails available per country.
- Compliance — review gate, customer levels, supported documents.
- Recipes — implementation guides for setup, sandbox flows, and launch.