#

Crear cobros

Creás un cobro con un referenceId tuyo, un monto, una descripción y al menos una fecha de vencimiento. El pagador paga a un CVU (o se concilia por su CUIL).

#

Campos principales (cobro standard)

POST /payment-request
referenceIdrequeridoTu llave de reconciliación. 8–100 caracteres: letras, números, - y _.
amountopcionalMonto en pesos, hasta 2 decimales, máx 10.000.000. Sin amount, el cobro nace en estado draft.
descriptionrequeridoDescripción del cobro (3–500 caracteres).
dueDatesrequerido1 o 2 fechas de vencimiento (ver Formatos de vencimiento).
surchargecondicionalRecargo del segundo vencimiento. Requerido solo con 2 dueDates (day-only) y amount.
conciliationTypeopcional"cvu" (default) o "cuil". Ver la guía Conciliación.
sendWhatsappNotification / sendEmailNotificationopcionalAvisos al pagador por canal. Ver la guía Notificaciones.
webhookUrlopcionalWebhook exclusivo para este cobro (HTTPS). Ver la guía Webhooks.
metadataopcionalPares clave-valor (string→string) para reconciliación libre: los adjuntás al crear el cobro y vuelven idénticos en el GET individual y en cada webhook. Máx 50 claves, clave ≤40 chars, valor ≤500 chars (solo strings), 8 KB en total. Funciona igual en single y bulk (per-item).
customerrequeridoDatos del pagador. name es requerido; taxDocument es requerido en modo cuil. Podés validarlo contra ARCA antes de crear el cobro. Ver Conciliación → Validar al pagador.
Ver ejemplo
curl
curl -X POST {{integration-url}}/payment-request \
  -H "Authorization: Bearer {user_id_token}" \
  -d '{
    "referenceId": "factura-2026-000123",
    "amount": 5000,
    "description": "Cuota mensual",
    "dueDates": ["2026-02-15"],
    "sendWhatsappNotification": false,
    "sendEmailNotification": false,
    "metadata": { "order_id": "abc-123", "sede": "acme" },
    "customer": { "name": "Juan Pérez" }
  }'
#

Formatos de vencimiento (dueDates)

Vencé por día o en el minuto exacto

Podés vencer por día O en el minuto exacto (datetime), ideal para casos de vida corta: eventos, estacionamiento, reservas. El vencimiento datetime SÍ dispara webhook al expirar (evento payment_request.expired); el day-only solo cambia el estado.

Cada vencimiento acepta uno de dos formatos:

Por día: YYYY-MM-DD

Ej. "2026-02-15". Vence al fin del día en hora Argentina. Debe ser posterior a hoy y como máximo a 35 días. Es el único formato que admite 2 vencimientos (con surcharge).

Con hora: YYYY-MM-DDTHH:MM[:SS]

Zona opcional: sin zona se asume hora Argentina; "Z" es UTC; o un offset como -03:00. Debe ser como mínimo dentro de 3 minutos y como máximo a 35 días. NO admite segundo vencimiento: es para casos de vida corta (eventos, estacionamiento). Al vencer, dispara webhook.

#

Ciclo de vida

draftBorrador: creado sin amount. No envía notificaciones y admite un solo vencimiento.
pendingPendiente de pago.
partial_paymentPago parcial recibido; queda saldo.
total_paymentPagado en su totalidad.
overdueVencido sin pago.
partial_overdueVencido con pago parcial.
canceledCancelado manualmente con POST /payment-request/{referenceId}/cancel.
Un cobro en draft se completa con PATCH /payment-request/{referenceId} (agregando el amount). Si no se completa, se limpia automáticamente 1 hora después de crearse.
Al vencer: los vencimientos por día solo cambian el estado a overdue (job diario 00:00 hora Argentina, sin webhook). Los vencimientos con hora (datetime) marcan overdue en el minuto exacto y sí disparan webhook.
#

Cobro de checkout (widget)

Cobrá sin pedirle los datos al pagador

Con type: "checkout" el cobro nace sin pagador y sin CVU. Mandás lo indispensable y te devolvemos un paymentRequestId para abrir el widget embebido. El pagador se identifica adentro del widget con su CUIL o DNI, y recién ahí se le asigna el CVU al que transferir. Es el modo para un e-commerce, donde no conocés al comprador antes de la compra.

typerequeridoEl valor exacto "checkout". Si lo omitís, el cobro es standard.
referenceIdrequeridoTu llave de reconciliación, igual que en un cobro standard.
amountrequeridoAcá SÍ es obligatorio: sin monto el widget no tiene qué mostrar. No existe el estado draft en este modo.
descriptionrequeridoDescripción del cobro que ve el pagador.
expiresInMinutesopcionalMinutos de vida del cobro. Default 15, mínimo 3, máximo 60. Reemplaza a dueDates: no calculás fechas.
webhookUrlopcionalWebhook exclusivo para este cobro, igual que en standard.
metadataopcionalPares clave-valor, igual que en standard.
Este tipo NO acepta customer, dueDates, conciliationType, surcharge ni los campos de notificación. Enviar cualquiera de ellos devuelve 400 indicando el campo. No son opcionales que nadie manda: son parte del contrato que el tipo no admite, porque el pagador todavía no existe cuando creás el cobro.
La conciliación siempre es por CUIL, derivada del tipo. El CVU que recibe el pagador sale de un pool compartido y se libera al pagarse o al vencer, así que no lo guardes para reusarlo. Al vencer, el cobro pasa a overdue y dispara el webhook payment_request.expired en el minuto exacto.
Ver ejemplo
curl
curl -X POST {{integration-url}}/payment-request \
  -H "Authorization: Bearer {user_id_token}" \
  -d '{
    "referenceId": "orden-2026-000123",
    "amount": 15000,
    "description": "Compra en la tienda",
    "type": "checkout",
    "expiresInMinutes": 15
  }'
#

Cobros masivos (bulk)

POST /payment-request/bulk crea entre 1 y 100 cobros en una sola llamada, de forma atómica (all-or-nothing) y siempre en modo CUIL.

  • Body: { "paymentRequests": [ ... ] }. Entre 1 y 100 items (máximo 100), siempre en modo CUIL. Cada item es como el cobro individual sin conciliationType, con customer.taxDocument obligatorio (CUIL de 11 dígitos o DNI de 7-8).
  • 201: todos los cobros comparten un CVU (sharedCvu) y los datos de acreditación (accountInfo). La respuesta trae batchId, total, created y un paymentRequests[] con { referenceId, state }.
  • 400: validación estructural (Joi). Array vacío, más de 100 items, o campos de un item fuera de contrato.
  • 422: validación de negocio. No se crea ningún cobro y la respuesta { message, errors: [{ index, referenceId, reason }] } reporta TODOS los items que fallan, no solo el primero. Los reason vienen en inglés, por ejemplo "Duplicate referenceId within the batch", "The referenceId already exists for this integration", "The taxDocument does not resolve to a valid CUIL".
  • El bulk prohíbe type y expiresInMinutes: ya es CUIL-only con taxDocument obligatorio por ítem, así que no hay tipo que derivar.
Rate limit: una llamada bulk cuenta como UNA sola request contra tu tope diario de requests (200/día), sin importar cuántos items tenga. No consume una request por item: el batch entero pesa 1. Ver la sección Rate limits en Conceptos.
Ver ejemplo
curl
curl -X POST {{integration-url}}/payment-request/bulk \
  -H "Authorization: Bearer {user_id_token}" \
  -d '{
    "paymentRequests": [
      { "referenceId": "socio-001", "amount": 1000,
        "description": "Cuota", "dueDates": ["2026-02-15"],
        "customer": { "name": "Juan Pérez", "taxDocument": "20304050607" } }
    ]
  }'