Skip to main content

Bulk receivable creation

For B2B scenarios where the ERP issues many receivables per day (nightly run, end-of-day, initial import), the POST /v1/receivables/batches endpoint is available. It processes asynchronously and notifies the result via webhook.

If you only need to create one receivable, use POST /v1/receivables. If you need to post-hoc bind an operator, see Advanced operations.

Request​

POST /v1/receivables/batches
Idempotency-Key: erp-batch-2026-05-15-cierre
Content-Type: application/json

{
  "items": [
    {
      "receivableAccountId": 4242,
      "amount": 45000.00,
      "currencyCode": "ARS",
      "receivableType": "INVOICE",
      "dueDate": "2026-05-30",
      "legalNumber": "0001-00012345"
    },
    {
      "receivableAccountId": 4243,
      "amount": 12500.00,
      "currencyCode": "ARS",
      "receivableType": "INVOICE",
      "dueDate": "2026-05-30",
      "legalNumber": "0001-00012346"
    }
  ]
}

Each item in the array has the same fields as POST /v1/receivables. Validation runs per item: invalid items do not break the batch, they are reported individually at the end.

Response​

202 Accepted
Location: /v1/receivables/batches/902

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

The batch is processed in the background. The integrator learns the result via the receivable.batch.completed event.

Result via webhook​

{
  "type": "receivable.batch.completed",
  "data": {
    "batchId": 902,
    "totalItems": 500,
    "successCount": 498,
    "failureCount": 2,
    "reportUrl": "https://files.maxpay.com.ar/batches/902/report.csv?token=..."
  }
}

The reportUrl points to a signed CSV with one row per item: batchIndex, receivableId (if created), status (success/error) and error.code with detail in case of failure.

Idempotency​

The Idempotency-Key applies to the whole batch, not to individual items. If the customer retries the same batch with the same key within the cache window, they receive the same batchId (it is not reprocessed). For individual items, deduplication relies on the receivable's business keys (see Idempotency).