Registrar

Descripción general

Este endpoint registra un pago de un cliente y lo aplica a una o varias de sus órdenes de cobro. Cada elemento de allocations crea un pago en su orden de cobro. Cuando envías dos o más asignaciones, los pagos creados comparten el mismo payment_group_id. Una solicitud exitosa devuelve 201 con los pagos creados, el saldo a favor generado y los complementos de pago emitidos.

El complemento de pago se decide igual que en la aplicación. Para cada asignación cuya orden de cobro tiene un CFDI de tipo PPD emitido, la API timbra automáticamente un complemento de pago y lo devuelve en payments[].complements. No existe un campo para pedirlo o evitarlo: enviar with_complement responde 400 con VALIDATION_ERROR. Las órdenes de cobro sin CFDI PPD emitido reciben el pago sin complemento.

Al registrar el pago, la API recalcula el saldo pendiente de cada orden de cobro. Si la orden queda pagada, su estatus cambia a paid.

Modo de prueba. Con "test": true, los complementos se timbran de prueba y solo para las órdenes de cobro con un CFDI de prueba PPD emitido. Si una orden de cobro tiene un CFDI PPD real emitido pero no uno de prueba, la solicitud responde 409 con PPD_TEST_CFDI_REQUIRED y no se registra nada. Los pagos y el saldo a favor creados en modo de prueba sí son reales.

Acepta el header Idempotency-Key. Requiere el permiso Crear en Pagos.

Endpoint

{
  "customer_id": "cmu2193s9004kv1dqthqupd39",
  "amount": "500",
  "currency": "MXN",
  "payment_date": "2026-09-14",
  "payment_method": "03",
  "allocations": [
    { "invoice_id": "cmu219f2k008pv1dqi204523f", "amount": "500" }
  ]
}

{
  "customer_id": "cmu219o5b00cyv1dqmrozb5yl",
  "amount": "1500",
  "currency": "MXN",
  "payment_date": "2026-09-14",
  "payment_method": "03",
  "reference": "TRF-78412",
  "test": true,
  "allocations": [
    { "invoice_id": "cmu219r6x00d7v1dq8paog9uj", "amount": "500" },
    { "invoice_id": "cmu219r7z00dkv1dqzeuz744z", "amount": "1000" }
  ]
}

{
  "customer_id": "cmu219o5b00cyv1dqmrozb5yl",
  "amount": "1300",
  "currency": "MXN",
  "payment_date": "2026-09-14",
  "payment_method": "03",
  "exchange_rate": "17.50",
  "convert_overpayment_to_credit": true,
  "allocations": [
    { "invoice_id": "cmu219r7z00dkv1dqzeuz744z", "amount": "1300" }
  ]
}

Tipo de cambio

exchange_rate es siempre el tipo de cambio de USD a MXN. Se envía como string o número mayor o igual a 0 con máximo 2 decimales (por ejemplo "17.50"); con más decimales la API responde 400 con VALIDATION_ERROR.

• Una asignación: el tipo de cambio es requerido cuando currency no es MXN o es distinta de la moneda de la orden de cobro.
• Dos o más asignaciones: el tipo de cambio es requerido cuando currency no es MXN o cuando alguna de las órdenes de cobro tiene una moneda distinta de currency.
• Si es requerido y no lo envías, la API responde 400 con VALIDATION_ERROR en el campo exchange_rate y el mensaje "El tipo de cambio es requerido por el SAT.". Si envías 0, el mensaje es "El tipo de cambio debe ser un número mayor a 0".
• Si no es requerido, el valor enviado se ignora y el pago queda con exchange_rate: null.

Para aplicar el pago a la orden de cobro, un pago en USD a una orden en MXN se convierte multiplicando el monto por el tipo de cambio, y un pago en MXN a una orden en USD, dividiéndolo. Con la misma moneda, el monto se aplica tal cual.

Distribución del monto

Una asignación

• allocations[0].amount debe ser igual a amount; si no, la API responde 400 con VALIDATION_ERROR en allocations.0.amount.
• La orden de cobro no puede estar cancelada y debe tener un saldo pendiente.
• Si el pago supera el saldo pendiente de la orden de cobro más la tolerancia, la API responde 409 con OVERPAYMENT_NOT_ALLOWED, salvo que envíes convert_overpayment_to_credit: true; en ese caso el excedente se registra como saldo a favor.

Dos o más asignaciones

• Cada orden de cobro debe estar en estatus issued u overdue.
• Sin convert_overpayment_to_credit, la suma de las asignaciones debe ser igual a amount, con una diferencia máxima de 0.01. Con convert_overpayment_to_credit: true, la suma puede ser menor que amount y la diferencia se registra como saldo a favor.
• Cada asignación, convertida a la moneda de su orden de cobro, no puede superar el saldo pendiente de esa orden más la tolerancia (ALLOCATION_EXCEEDS_BALANCE). Si la supera dentro de la tolerancia, el excedente se registra como saldo a favor.
• El saldo a favor del pago se registra en un solo movimiento, en la moneda del pago.

La tolerancia es el 1% del total de la orden de cobro, con un máximo de 500 para órdenes en MXN y de 25 para órdenes en USD.

Reglas de los campos

Cualquier otro campo, incluido with_complement, responde 400 con VALIDATION_ERROR (unrecognized_keys).

allocations[]

Formas de pago

Forma de las respuestas

201 — pago registrado

Errores