Skip to main content

Getting Started

This tutorial takes you from zero to your first collection impacting Max Pay. You will:

  1. Get credentials and authenticate against sandbox.
  2. Create a client.
  3. Create a receivable account with CVU.
  4. Issue a receivable (record an invoice).
  5. Simulate an incoming collection.
  6. Mark the receivable as paid.

The whole flow takes ~10 minutes. The examples use curl and JavaScript (Node.js). They assume the sandbox environment: https://api-sandbox.maxpay.com.ar/v1.

Step 1 — Get credentials and authenticate​

Ask the Max Pay commercial team for a sandbox clientId and clientSecret. Then authenticate:

curl -X POST https://api-sandbox.maxpay.com.ar/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR...",
  "tokenType": "Bearer",
  "expiresIn": 43200,
  "scope": "clients:read clients:write receivable-accounts:read receivable-accounts:write receivables:read receivables:write ..."
}

Save the accessToken — you will use it on every subsequent request in the header Authorization: Bearer <accessToken>.

Validate that your credentials work:

curl https://api-sandbox.maxpay.com.ar/v1/me \
  -H "Authorization: Bearer $TOKEN"

For scope and error details, see Authentication.

Step 2 — Create a client​

The client represents whoever you will invoice. It is idempotent by (documentType, documentNumber, branchExternalCode):

curl -X POST https://api-sandbox.maxpay.com.ar/v1/clients \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tutorial-cli-001" \
  -d '{
    "businessName": "Kiosco Central",
    "taxId": "30998888887",
    "documentType": "CUIT"
  }'

Response:

{
  "id": 1042,
  "businessName": "Kiosco Central",
  "taxId": "30998888887",
  ...
}

Note the id: 1042 — you need it to create the receivable account.

Step 3 — Create the receivable account​

A receivable account is an account with a dedicated CVU where the client will transfer. Let's bind it to the client we just created:

curl -X POST https://api-sandbox.maxpay.com.ar/v1/receivable-accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tutorial-rac-001" \
  -d '{
    "clientId": 1042
  }'

Response:

{
  "id": 4242,
  "cvu": null,
  "alias": null,
  "status": "PROVISIONING",
  "owner": { "type": "CLIENT", "id": 1042 },
  ...
}

The account starts in PROVISIONING because the CVU is assigned asynchronously against the banking provider.

Wait until the account is active (typically a few seconds). You can poll it or wait for the receivable-account.activated webhook. For this tutorial, poll:

curl https://api-sandbox.maxpay.com.ar/v1/receivable-accounts/4242 \
  -H "Authorization: Bearer $TOKEN"

When you see "status": "ACTIVE" and an assigned cvu, move to the next step.

Step 4 — Issue a receivable​

A receivable is the document that records the debt. Let's issue an invoice of $45,000 with a 15-day due date:

curl -X POST https://api-sandbox.maxpay.com.ar/v1/receivables \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tutorial-rcv-001" \
  -d '{
    "receivableAccountId": 4242,
    "amount": 45000.00,
    "currencyCode": "ARS",
    "receivableType": "INVOICE",
    "legalNumber": "0001-00000001",
    "issueDate": "2026-05-15",
    "dueDate": "2026-05-30"
  }'

Response:

{
  "id": 99001,
  "receivableAccountId": 4242,
  "status": "PENDING",
  ...
}

The receivable is in PENDING. "What is expected to be collected" is now registered.

Step 5 — Simulate a collection​

In sandbox you can simulate that a client transfers to your CVU from the Max Pay web panel (or via a sandbox helper endpoint your account manager can enable for you). Once the simulation is triggered, Max Pay records a movement and emits the movement.created webhook.

If you subscribed to a webhook in this sandbox, you will receive:

{
  "type": "movement.created",
  "data": {
    "movement": {
      "id": 88123,
      "receivableAccountId": 4242,
      "movementType": "CREDIT",
      "operationType": "DEPOSIT",
      "amount": 45000.00,
      "counterParty": { "name": "Kiosco Central", "taxId": "30998888887" }
    }
  }
}

If you have not yet configured webhooks, you can see the movement via API:

curl "https://api-sandbox.maxpay.com.ar/v1/receivable-accounts/4242/movements" \
  -H "Authorization: Bearer $TOKEN"

Step 6 — Mark the receivable as paid​

Max Pay does not automatically match the movement to the receivable. The "this collection pays this invoice" decision is yours: identify the corresponding receivable and mark it as PAID.

curl -X PATCH https://api-sandbox.maxpay.com.ar/v1/receivables/99001/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tutorial-paid-99001" \
  -d '{
    "status": "PAID"
  }'

Response:

{
  "id": 99001,
  "status": "PAID",
  ...
}

Done! You now have a receivable created, collected, and matched.

What's next?​