Pagos

Vas a lograr registrar un pago con POST /v1/payments sin duplicarlo en un reintento, y leer y conciliar los pagos que ya existen en Mozart.

Registrar un pago por la API requiere una clave con el scope write (ver Autenticación). Sin ese scope, POST /v1/payments responde 403 forbidden.

Registrar un pago

curl -X POST https://api.mozarth.com/v1/payments \
  -H "Authorization: Bearer <tu clave>" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolioId": "01J9XPS0N4H8D2M7Q9V3K5T1WX",
    "debtorId": "01J9XPS8K2M4N6Q8R1T3V5X7YZ",
    "externalId": "pago-2026-08-15-00123",
    "paymentDate": "2026-08-15",
    "amount": 4500,
    "currency": "UYU",
    "method": "transfer",
    "reference": "TRX-889213"
  }'

{
  "data": {
    "id": "01J9XPT8N4Q6R8T1V3X5Y7Z9A2",
    "portfolioId": "01J9XPS0N4H8D2M7Q9V3K5T1WX",
    "debtorId": "01J9XPS8K2M4N6Q8R1T3V5X7YZ",
    "debtId": null,
    "promiseId": null,
    "paymentDate": "2026-08-15",
    "paymentMethod": "transfer",
    "reference": "TRX-889213",
    "amount": 4500,
    "currency": "UYU",
    "createdAt": "2026-08-15T16:20:00.000Z",
    "updatedAt": "2026-08-15T16:20:00.000Z"
  }
}

Campos del body

Campo	Obligatorio	Qué es
`portfolioId`	Sí	La cartera del pago. Tiene que estar dentro del alcance de tu clave
`debtorId`	Sí	El deudor que realizó el pago
`externalId`	Sí	Tu clave de idempotencia (ver abajo). 1 a 128 caracteres
`paymentDate`	Sí	Fecha en que ocurrió el pago, formato `YYYY-MM-DD`
`amount`	Sí	Monto abonado, mayor a 0
`currency`	No	Código ISO de la moneda
`method`	No	Uno de `transfer`, `cash`, `collection_network`, `deposit`, `card`, `check`, `other`
`reference`	No	Número de cheque, comprobante bancario o código de depósito
`debtId`	No	La deuda específica a la que aplica, si la conocés

Idempotencia por `externalId`

externalId es tu clave de idempotencia: identificá cada pago de tu lado con un valor propio (el id de tu transacción, por ejemplo) y mandalo siempre que registres ese pago.

Primer request

Un externalId nuevo para esa cartera crea el pago y responde 201.

Reintento con el mismo externalId

Si volvés a mandar el mismo externalId en la misma cartera —por un timeout, un reintento automático de tu lado, lo que sea— la API no crea un segundo pago: responde 200 con el pago que ya existía.

La idempotencia es por portfolioId + externalId. El mismo externalId en dos carteras distintas crea dos pagos: no es una clave global.

Errores típicos

Situación	Respuesta
La clave no tiene el scope `write`	`403 forbidden`
`debtorId` no existe, o no pertenece a `portfolioId`	`404 not_found`
`amount` supera la deuda pendiente del deudor	`400 validation_error`
`paymentDate` no tiene el formato `YYYY-MM-DD`, o no es una fecha calendario real (`2026-02-30`)	`400 validation_error`
`portfolioId` no pertenece a tu organización	`404 not_found` — a propósito: una cartera ajena responde igual que una que no existe

Ver Paginación, errores y límites para el formato completo del sobre de error.

Ejemplos por lenguaje

curl -X POST https://api.mozarth.com/v1/payments \
  -H "Authorization: Bearer <tu clave>" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolioId": "01J9XPS0N4H8D2M7Q9V3K5T1WX",
    "debtorId": "01J9XPS8K2M4N6Q8R1T3V5X7YZ",
    "externalId": "pago-2026-08-15-00123",
    "paymentDate": "2026-08-15",
    "amount": 4500,
    "currency": "UYU"
  }'

const response = await fetch("https://api.mozarth.com/v1/payments", {
  method: "POST",
  headers: {
    Authorization: "Bearer <tu clave>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    portfolioId: "01J9XPS0N4H8D2M7Q9V3K5T1WX",
    debtorId: "01J9XPS8K2M4N6Q8R1T3V5X7YZ",
    externalId: "pago-2026-08-15-00123",
    paymentDate: "2026-08-15",
    amount: 4500,
    currency: "UYU",
  }),
});

const { data } = await response.json();
console.log(data.id, response.status); // 201 la primera vez, 200 en un reintento

import requests

response = requests.post(
    "https://api.mozarth.com/v1/payments",
    headers={"Authorization": "Bearer <tu clave>"},
    json={
        "portfolioId": "01J9XPS0N4H8D2M7Q9V3K5T1WX",
        "debtorId": "01J9XPS8K2M4N6Q8R1T3V5X7YZ",
        "externalId": "pago-2026-08-15-00123",
        "paymentDate": "2026-08-15",
        "amount": 4500,
        "currency": "UYU",
    },
)

payment = response.json()["data"]
print(payment["id"], response.status_code)  # 201 la primera vez, 200 en un reintento

Otras formas en que se registra un pago

POST /v1/payments no es la única fuente: un pago también se registra manualmente desde el panel de Mozart, por un link de cobro (pay.mozarth.com), o lo trae el importador de carteras cuando una deuda llega al archivo ya parcialmente pagada. Los tres caminos se leen igual por GET /v1/payments.

Leer pagos

curl "https://api.mozarth.com/v1/payments?portfolioId=01J9XPS0N4H8D2M7Q9V3K5T1WX&limit=20" \
  -H "Authorization: Bearer <tu clave>"

paymentMethod es uno de transfer, cash, collection_network, deposit, card, check u other.

Promesas de pago

GET /v1/promises lista los compromisos de pago futuro. Cuando una promesa se cumple, queda vinculada al pago que la cumplió:

{
  "data": [
    {
      "id": "01J9XPTG5R7T9V2X4Y6Z8A1B3C",
      "portfolioId": "01J9XPS0N4H8D2M7Q9V3K5T1WX",
      "debtorId": "01J9XPS8K2M4N6Q8R1T3V5X7YZ",
      "campaignId": null,
      "callId": "01J9XPT1M3N5Q7R9T2V4X6Y8Z1",
      "status": "fulfilled",
      "type": "installment",
      "amount": 4500,
      "currency": "UYU",
      "promiseDate": "2026-08-15",
      "paymentMethod": "transfer",
      "paymentReference": "TRX-889213",
      "fulfillmentDate": "2026-08-15",
      "paymentId": "01J9XPT8N4Q6R8T1V3X5Y7Z9A2",
      "installmentNumber": 1,
      "createdAt": "2026-08-01T10:00:00.000Z",
      "updatedAt": "2026-08-15T16:20:00.000Z"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false, "limit": 50 }
}

status de una promesa es uno de pending, partial, fulfilled, broken o cancelled.

Conciliación con tus propios registros

La forma confiable de conciliar una promesa con el pago que la cumplió es el vínculo directo por id: promise.paymentId apunta al id del pago correspondiente (y, a la inversa, payment.promiseId apunta a la promesa que ese pago cumplió). Si además necesitás cruzar un pago contra tu propio sistema, usá reference para lo que ya venías registrando manualmente, o externalId para lo que registrás vos mismo por POST /v1/payments — es la clave que vos elegiste. promise.paymentReference es el mismo tipo de dato visto desde la promesa. reference es texto libre y opcional: puede venir vacío, así que no lo uses como única clave de conciliación si tu proceso lo necesita sin excepciones.

Siguiente paso

Seguí con Carga de cartera para cargar deudores y deudas por la API.

Empezar

Guías

Plataforma

Changelog

Registrar un pago

Campos del body

Idempotencia por `externalId`

Errores típicos

Ejemplos por lenguaje

Otras formas en que se registra un pago

Leer pagos

Promesas de pago

Conciliación con tus propios registros

Siguiente paso

​Registrar un pago

​Campos del body

​Idempotencia por externalId

​Errores típicos

​Ejemplos por lenguaje

​Otras formas en que se registra un pago

​Leer pagos

​Promesas de pago

​Conciliación con tus propios registros

​Siguiente paso

Registrar un pago

Campos del body

Idempotencia por `externalId`

Errores típicos

Ejemplos por lenguaje

Otras formas en que se registra un pago

Leer pagos

Promesas de pago

Conciliación con tus propios registros

Siguiente paso