Saltar al contenido principal

Cómo empezar

Este tutorial te lleva de cero a tener tu primer cobro impactado en Max Pay. Vas a:

  1. Obtener credenciales y autenticar contra sandbox.
  2. Crear un cliente.
  3. Crear una cuenta recaudadora con CVU.
  4. Emitir un comprobante (registrar una factura).
  5. Simular un cobro entrante.
  6. Marcar el comprobante como pagado.

Todo el flujo lleva ~10 minutos. Los ejemplos usan curl y JavaScript (Node.js). Asumen el ambiente sandbox: https://api-sandbox.maxpay.com.ar/v1.

Paso 1 — Obtener credenciales y autenticar​

Pedile al equipo comercial de Max Pay un clientId y un clientSecret de sandbox. Después autenticá:

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

Guardá el accessToken — lo vas a usar en todos los requests siguientes en el header Authorization: Bearer <accessToken>.

Validá que tus credenciales funcionan:

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

Para detalles de scopes y errores, ver Autenticación.

Paso 2 — Crear un cliente​

El cliente representa a quien vas a facturar. Es idempotente por (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",
  ...
}

Anotá el id: 1042 — lo necesitás para crear la cuenta recaudadora.

Paso 3 — Crear la cuenta recaudadora​

Una cuenta recaudadora es la cuenta con CVU dedicado donde el cliente va a transferir. Atámosla al cliente que recién creamos:

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 },
  ...
}

La cuenta arranca en PROVISIONING porque el CVU se asigna de forma asíncrona contra el proveedor bancario.

Esperá a que la cuenta esté activa (típicamente unos segundos). Podés pollearla o esperar el webhook receivable-account.activated. Para este tutorial, polleá:

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

Cuando veas "status": "ACTIVE" y un cvu asignado, seguí al paso siguiente.

Paso 4 — Emitir un comprobante​

Un comprobante es el documento que registra la deuda. Vamos a emitir una factura de $45.000 con vencimiento a 15 días:

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

El comprobante queda en PENDING. Quedó "registrado lo que se espera cobrar".

Paso 5 — Simular un cobro​

En sandbox podés simular que un cliente transfiere a tu CVU desde el panel web de Max Pay (o vía un endpoint helper de sandbox que tu account manager puede habilitarte). Una vez disparada la simulación, Max Pay registra un movement y emite el webhook movement.created.

Si suscribiste un webhook en este sandbox, vas a recibir:

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

Si todavía no configuraste webhooks, podés ver el movement por API:

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

Paso 6 — Marcar el comprobante como pagado​

Max Pay no imputa automáticamente el movement al comprobante. La decisión "este cobro paga esta factura" la tomás vos: identificás el comprobante correspondiente y lo marcás como 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",
  ...
}

¡Listo! Tenés un comprobante creado, cobrado e imputado.

¿Y después?​