Customer operating models
The operating models describe the different usage patterns of Max Pay based on the customer's business. Understanding them is necessary to decide how to create receivable accounts and how to assign clients and associates. This page is the conceptual basis for the rest of the documentation.
Building blocks
Three entities are involved in a collection:
| Entity | Represents | Example |
|---|---|---|
| Customer | The merchant that uses Max Pay. Implicit in your API key. | DistribuidoraDemo S.A. |
| Client | A client of the customer. A company, a person, or a logical entity like a student. | Kiosco Central; Tomás López (student) |
| Associate | An operator of the customer. A natural person operating the platform. | Operario 042 (driver); Familia López (paying guardian) |
On top of these entities we build the receivable accounts (receivable-accounts), which are the accounts with a dedicated CVU where clients transfer payments.
Receivable account patterns
A receivable account is optionally tied to a client, optionally to an associate, or to both. These are the 3 supported patterns:
| Pattern | clientId | associateId | The customer can see what was collected by... | When it applies |
|---|---|---|---|---|
| A Client account without operator | ✓ | — | Client | Account for a shop/business without an assigned driver yet |
| B Operator account without client discrimination | — | ✓ | Operator | Drivers who collect in bulk and report to the customer |
| C Client account with assigned operator | ✓ | ✓ | Client + Operator | Driver who already scanned invoices for a client; student with paying guardian |
An account without a client or associate is not valid for receivable accounts. That combination is reserved for the customer's MAIN current account.
Pattern A — Client account without operator
Typical case: a B2B customer that onboards a new client and records an invoice before any driver has delivered merchandise to that point of sale.
If the customer is a small business where a single administrator controls all client accounts, Pattern A can be permanent. If the customer has a fleet, this pattern is transitional until a driver scans the first invoice and the account transitions to Pattern C.
Pattern B — Operator account without client discrimination
Typical case: a customer whose operational model is "the driver goes shop by shop and collects; at end of day they report the total". There is no interest in identifying how much each end client paid.
End clients are not modeled in Max Pay for this case. The payer identification stays in the movement metadata (counterParty field with their taxId and name), if the customer needs it for reconciliation.
Pattern C — Client account with assigned operator
This pattern covers two distinct business cases:
Case C.1 — Client with assigned driver
Typical case: a driver of the customer scans an invoice issued to a shop. From that moment, all invoices issued to that shop are associated with their account, and both the customer and the driver can see what was collected per client.
It is common for an account to start as Pattern A and transition to Pattern C when an associate is assigned. See post-hoc operator binding.
Case C.2 — Client and operator are the same real person (educational / clubs model)
In educational institutions, the student is modeled as a client (client entity with their CUIL/CUIT). The payer (who can be the same student if they are an adult, or the parent/guardian) is modeled as an associate linked to that account so they can see the account statement and operate. The diagram is the same as C.1, with different roles represented.
A client and an associate can share taxId. This is not duplication: they represent different roles of the same person (client vs operator). When you create both, you will receive two events: client.created and associate.created.
Which pattern is mine?
Quick decision based on your business model:
| Question | Yes | No |
|---|---|---|
| Do you identify the client by their CUIT? | Pattern A or C | Pattern B |
| Is there an operator (driver, salesperson, guardian) running the account? | Pattern C | Pattern A |
| Does the operator report in bulk without separating by client? | Pattern B | Pattern A or C |
| Education case: student + guardian (same person or not) | Pattern C.2 | — |
Examples:
- B2B distributor that invoices shops and tracks each collection against its client → Pattern A.
- Freight fleet where the driver collects multiple services per shift and reports at the end of the day → Pattern B.
- Distributor with a driver assigned per area who collects from shops along the route → Pattern C.1.
- Educational institution where the student is the client and the guardian is the payer → Pattern C.2.
How the pattern is chosen in practice
You do not have to declare "which pattern you are using" anywhere. Each receivable account is created with the appropriate IDs, and the system infers the pattern automatically. The same customer can have accounts of different patterns simultaneously (for example, different regions operating differently).
Some operations require coherence with the customer's configuration. For example, if your configuration does not include associates, you will receive 403 owner-type-not-supported when trying to pass an associateId. In that case, escalate to your account manager to review the commercial configuration.
Next steps
- Creating receivable accounts: complete flows per pattern, with example code.
- Issuing receivables: how to record debt and its modifications once the account exists.