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.v3.mozarth.com/public/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",
    "externalId": "pago-2026-08-15-00123",
    "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 4217 de la moneda. Si la omitís, se deriva de la moneda de la deuda indicada en debtId, si la hay; si no, de la única moneda de las deudas vivas del deudor o, si no alcanza, de la moneda principal de la cartera. Si no se puede derivar (o el código no es ISO), responde `400` `validation_error`
`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.

Mismo externalId con otro cuerpo

Si el externalId ya existe en esa cartera pero el cuerpo es distinto (monto, moneda, fecha, deudor, deuda, método o referencia), la API no devuelve el pago anterior ni crea uno nuevo: responde 409 idempotency_conflict. Usá un externalId nuevo para un pago distinto.

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`
El `externalId` ya se usó en esa cartera con otro cuerpo	`409 idempotency_conflict`
`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.v3.mozarth.com/public/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.v3.mozarth.com/public/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.v3.mozarth.com/public/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.v3.mozarth.com/public/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 elegiste y vuelve en el campo externalId del pago (null en los pagos que no se cargaron por ese endpoint). 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