Crear una cuenta recaudadora

Esta guía cubre el caso simple: crear una cuenta recaudadora atada a un cliente (Patrón A). Es el flujo más común y el primero que tenés que implementar.

Para otros patrones (Patrón B sin cliente, Patrón C con operador), ver Cuentas en Patrones B y C. Para operaciones avanzadas (vinculación post-hoc, reasignación, alta masiva), ver Operaciones avanzadas.

Convenciones de los ejemplos

Todos los ejemplos asumen:

• Token JWT en Authorization: Bearer ....
• Headers Content-Type: application/json y Idempotency-Key: ....
• Base URL: https://api.maxpay.com.ar/v1 (o sandbox).

Flujo

Ejemplo de código

// Paso 1: alta del cliente (idempotente por 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
  }
});

// Paso 2: alta de la cuenta recaudadora del cliente
const account = await maxpay.post('/v1/receivable-accounts', {
  headers: { 'Idempotency-Key': `erp-rac-cli-${erpClientId}` },
  body: {
    clientId: client.id
  }
});

console.log(`Cuenta creada: ${account.id}, status=${account.status}`);
// → "Cuenta creada: 4242, status=PROVISIONING"
// El cvu llega por webhook receivable-account.activated

Body request

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

{
  "clientId": 1042
}

Campo	Tipo	Requerido	Descripción
clientId	int64	Sí	ID del cliente al que se ata la cuenta
currencyCode	string	No	Default ARS
aliasTemplate	string	No	Sobrescribe el template configurado por el customer

Respuesta

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"
}

Provisión asíncrona del CVU

El CVU de la cuenta recaudadora se asigna de forma asíncrona tras crearla: el response inicial trae status: PROVISIONING y cvu: null. El CVU se confirma típicamente en segundos.

Hay dos formas de enterarte:

1. Webhook (recomendado): suscribite al evento receivable-account.activated para recibir el cvu y alias apenas se asignan.
2. Polling: hacé GET /v1/receivable-accounts/{id} cada pocos segundos hasta que el status sea ACTIVE.

Emitir comprobantes antes de tener CVU

El alta de comprobantes no requiere que la cuenta esté en ACTIVE. Podés registrar comprobantes contra una cuenta PROVISIONING y quedan en PENDING esperando. Los comprobantes modelan la deuda; los movimientos de dinero empiezan a registrarse recién cuando el CVU está activo.

Si la provisión falla

Si el proveedor bancario rechaza el alta del CVU, Max Pay reintenta automáticamente con backoff exponencial. Si los reintentos se agotan sin éxito:

• La cuenta pasa a status: DISABLED.
• Se dispara el webhook receivable-account.cvu-failed con errorReason indicando el motivo.
• No hay timeout fijo en PROVISIONING mientras los reintentos están en curso.

Para retomar:

• Reabrir la misma cuenta con POST /v1/receivable-accounts/{id}/activations si el motivo es transitorio.
• Crear una cuenta nueva si los datos del owner necesitan ajustes.

Variante con sucursales

Si el cliente tiene varias sucursales, cada sucursal se da de alta como un client separado con el mismo taxId y distinto branchExternalCode. Cada sucursal tiene su cuenta recaudadora.

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 }
  });
}

Errores comunes

Escenario	HTTP	code
clientId y associateId ambos nulos	422	receivable-account-requires-owner
clientId apunta a un cliente de otro customer	403	resource-not-accessible
El owner-type no está habilitado en la configuración del customer	422	owner-type-not-supported
Ya existe una cuenta con la misma combinación de owners y currency	409	receivable-account-already-exists (response incluye existingResourceId)
Mismo Idempotency-Key con body distinto	409	idempotency-key-reuse
Provisión de CVU falló en el proveedor	502	external-provider-unavailable