Overview
Payments handle taking money for an order. The system has three pieces:- Payment Methods — the available ways to pay (credit card, cash, contact balance, …).
- Payments — a payment record against an order.
- Transactions — the individual charges or refunds under a payment.
Only invoices take payments. A payment can only be made against an
invoice order, and the invoice must be completed.
Payment Method
An available way to pay.| Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name (for example Credit Card). |
slug | string | Yes | Identifier — routes to the right gateway (e.g. stripe, cash, contact-balance). |
description | string | Yes | Customer-facing description. |
is_active | boolean | Yes | Whether the method is available (turn it off without deleting it). |
Payment
A payment record against an order.| Property | Type | Required | Description |
|---|---|---|---|
order_id | reference | Yes | The order being paid. |
contact_id | reference | Yes | The customer making the payment. |
payment_method_id | reference | Yes | The method used. |
value | number | Auto | The amount, kept in sync as transactions are approved. |
description | string | No | Optional description. |
Transaction
An individual charge or refund under a payment.| Property | Type | Required | Description |
|---|---|---|---|
payment_id | reference | Conditional | The payment this belongs to (omit it to create the payment inline). |
type | enum | Yes | payment or refund. |
value | number | Yes | The amount. |
status | enum | Auto | processing, approved, or rejected. |
message | string | Auto | The reason, set when a transaction is rejected. |
How a payment works
A transaction is the entry point. You create one against an order (or an existing payment) — if there’s no payment yet, one is created for you. The transaction is validated (the order must accept payments), processed through its method’s gateway, and marked approved or rejected. As approved transactions land, the order’s paid amount updates; when the paid amount reaches the order total, the order is marked paid.Refunds & contact balance
- A refund is a transaction with
type: refund. A refund can’t exceed the payment it’s reversing (refund invoices under a return are the exception — they move money back to the customer). - The contact balance method pays from a customer’s stored credit: an approved payment lowers their balance, an approved refund raises it.
Seeds
Payment methods, payments, and transactions aren’t supported in Seeds.Governance & permissions
Only a super admin or Master can manage payment methods. Payments are made against orders — see Orders for who can manage those.Related
Orders
Invoices are the orders that take payment.
Contacts
The customer who pays — and whose balance can be used.