Create a receivable account

This guide covers the simple case: create a receivable account bound to a client (Pattern A). It is the most common flow and the first one you need to implement.

For other patterns (Pattern B without a client, Pattern C with an operator), see Accounts in Patterns B and C. For advanced operations (post-hoc binding, reassignment, bulk creation), see Advanced operations.

Example conventions

All examples assume:

• JWT token in Authorization: Bearer ....
• Headers Content-Type: application/json and Idempotency-Key: ....
• Base URL: https://api.maxpay.com.ar/v1 (or sandbox).

Flow

Code example

// Step 1: client creation (idempotent by taxId + branch)
const client = await maxpay.post('/v1/clients', {
  headers: { 'Idempotency-Key': `erp-cli-${erpClientId}` },
  body: {
    businessName: 'Kiosco Central',
    taxId: '30998888887',
    documentType: 'CUIT',
    email: '[email protected]',
    externalId: erpClientId
  }
});

// Step 2: create the client's receivable account
const account = await maxpay.post('/v1/receivable-accounts', {
  headers: { 'Idempotency-Key': `erp-rac-cli-${erpClientId}` },
  body: {
    clientId: client.id
  }
});

console.log(`Account created: ${account.id}, status=${account.status}`);
// → "Account created: 4242, status=PROVISIONING"
// The cvu arrives via the receivable-account.activated webhook

Request body

POST /v1/receivable-accounts
Idempotency-Key: erp-rac-cli-12345
Content-Type: application/json

{
  "clientId": 1042
}

Field	Type	Required	Description
clientId	int64	Yes	ID of the client the account is bound to
currencyCode	string	No	Default ARS
aliasTemplate	string	No	Overrides the customer-configured template

Response

201 Created
Location: /v1/receivable-accounts/4242
Content-Type: application/json

{
  "id": 4242,
  "cvu": null,
  "alias": null,
  "currencyCode": "ARS",
  "status": "PROVISIONING",
  "owner": { "type": "CLIENT", "id": 1042 },
  "creationDate": "2026-05-15T10:00:00-03:00",
  "modificationDate": "2026-05-15T10:00:00-03:00"
}

Asynchronous CVU provisioning

The receivable account's CVU is provisioned asynchronously after you create it: the initial response returns status: PROVISIONING and cvu: null. The CVU is typically confirmed within seconds.

There are two ways to learn about it:

1. Webhook (recommended): subscribe to the receivable-account.activated event to receive the cvu and alias as soon as they are assigned.
2. Polling: call GET /v1/receivable-accounts/{id} every few seconds until status is ACTIVE.

Issuing receivables before the CVU is ready

Issuing receivables does not require the account to be ACTIVE. You can register receivables against a PROVISIONING account and they stay in PENDING waiting. Receivables model the debt; money movements only start being recorded once the CVU is active.

If provisioning fails

If the banking provider rejects the CVU creation, Max Pay retries automatically with exponential backoff. If the retries are exhausted without success:

• The account moves to status: DISABLED.
• The receivable-account.cvu-failed webhook fires with errorReason indicating the reason.
• There is no fixed timeout on PROVISIONING while retries are in progress.

To resume:

• Reopen the same account with POST /v1/receivable-accounts/{id}/activations if the cause is transient.
• Create a new account if the owner data needs to change.

Branch variant

If the client has multiple branches, each branch is registered as a separate client with the same taxId and a different branchExternalCode. Each branch has its own receivable account.

for (const branch of branches) {
  const client = await maxpay.post('/v1/clients', {
    headers: { 'Idempotency-Key': `erp-cli-${branch.externalCode}` },
    body: {
      businessName: '...',
      taxId: '30997777776',
      documentType: 'CUIT',
      branchExternalCode: branch.externalCode,
      branchDescription: branch.description
    }
  });

  await maxpay.post('/v1/receivable-accounts', {
    headers: { 'Idempotency-Key': `erp-rac-${branch.externalCode}` },
    body: { clientId: client.id }
  });
}

Common errors

Scenario	HTTP	code
clientId and associateId both null	422	receivable-account-requires-owner
clientId points to a client of another customer	403	resource-not-accessible
The owner-type is not enabled in the customer's configuration	422	owner-type-not-supported
An account with the same owner combination and currency already exists	409	receivable-account-already-exists (response includes existingResourceId)
Same Idempotency-Key with a different body	409	idempotency-key-reuse
CVU provisioning failed at the provider	502	external-provider-unavailable