Skip to main content

Advanced account operations

This guide covers three operations that are not part of basic creation:

Post-hoc operator binding​

An account can initially be created as Pattern A (only clientId) and later transition to Pattern C when an associateId is assigned. This is useful when the operator is not yet onboarded at the time the account is created.

There are two paths to bind an associate to an existing account:

Path A — Specify associateId when registering a receivable​

If POST /v1/receivables includes associateId and the target account has no associate yet, the system post-hoc binds the associate to the account before registering the receivable. The account becomes Pattern C from that moment on.

POST /v1/receivables
Content-Type: application/json
Idempotency-Key: rcv-2026-04-01-9001

{
  "receivableAccountId": 5511,
  "associateId": 8821,
  "amount": 12500,
  "dueDate": "2026-04-30",
  "externalId": "FAC-A-0001-00009001"
}

If the account already had a different associateId, the API responds 409 with a specific code. If the associate belongs to another customer, it responds 403.

Path B — Update the account explicitly​

PUT /v1/receivable-accounts/{id}
Content-Type: application/json

{
  "associateId": 8821
}

This applies the binding without registering a receivable. If the account already had an associate, see Operator reassignment.

Operator reassignment​

When an account already has an associateId and it needs to be changed (for example, the assigned driver is offboarded or the guardian changes in the educational model), the flow is:

  1. Disable the current account if you want to cut the CVU tied to the previous associate (PUT /v1/receivable-accounts/{id}/status with status: DISABLED).
  2. Create a new account pointing to the new associate (POST /v1/receivable-accounts with the new associateId).

Replacing an associateId with a different one on an active account with a provisioned CVU is not allowed: the CVU is tied to the owner's identity, and reassigning implies generating a new CVU. The API responds 422 with a specific code on attempts to change associateId to a different value on active accounts.

If an associate is offboarded (DELETE /v1/associates/{id}), the accounts that had that associate linked remain in ACTIVE state but become associate-less (they transition to Pattern A — client account). The CVU keeps operating against the account's clientId. To bind a new associate, you can post-hoc bind a new one (see Post-hoc operator binding) — this is allowed on an ACTIVE account because it does not replace an existing associate, it adds one.

Bulk creation​

For scenarios where several accounts need to be created at once, the POST /v1/receivable-accounts/batches endpoint is available. It processes asynchronously and notifies the result via webhook.

POST /v1/receivable-accounts/batches
Idempotency-Key: erp-batch-rac-2026-05-15
Content-Type: application/json

{
  "items": [
    { "clientId": 5001, "associateId": 6001 },
    { "clientId": 5002, "associateId": 6002 }
  ]
}
202 Accepted
Location: /v1/receivable-accounts/batches/1203

{
  "batchId": 1203,
  "status": "PROCESSING",
  "totalItems": 2
}

When processing finishes, Max Pay emits the receivable-account.batch.completed event with a detailed report (success/failure per item). See Event catalog.