Aplicar saldo

Descripción general

Este endpoint aplica el saldo a favor de un cliente a una o varias de sus órdenes de cobro. Por cada aplicación crea un pago con forma de pago 17 (Compensación) y funding_source: "credit", y un movimiento applicationToInvoice que descuenta el monto del saldo a favor. Una solicitud exitosa devuelve 201 con los pagos creados.

currency indica de qué saldo se toma el monto (MXN o USD) y es la moneda de los pagos creados. La suma de los amount no puede superar el saldo disponible en esa moneda.

Igual que en la aplicación, la forma de pago siempre es 17: el cuerpo no acepta payment_method. Cuando la orden de cobro tiene un CFDI PPD timbrado, la API timbra el complemento de pago en la misma solicitud.

Requiere el permiso Crear en Pagos.

Endpoint

Path param: customerId — ID del cliente dueño del saldo a favor y de las órdenes de cobro.

{
  "currency": "MXN",
  "test": true,
  "applications": [
    {
      "invoice_id": "cmu21aagp00hnv1dq2aztwkyr",
      "amount": "300",
      "payment_date": "2026-09-14",
      "reference": "APL-2026-0914"
    }
  ]
}

{
  "currency": "USD",
  "applications": [
    {
      "invoice_id": "cmu21aagp00hnv1dq2aztwkyr",
      "amount": "10",
      "payment_date": "2026-09-14"
    }
  ]
}

Reglas de los campos

El cuerpo no acepta campos adicionales: payment_method o cualquier otro campo desconocido responde 400 con VALIDATION_ERROR.

Comportamiento

• La suma de los amount debe ser menor o igual al saldo a favor disponible en currency.
• Cada orden de cobro debe pertenecer al cliente, no estar cancelada y tener saldo pendiente.
• El monto, convertido a la moneda de la orden de cobro, no puede superar su saldo pendiente más una tolerancia: el menor entre el 1 % del total de la orden y 500 en MXN o 25 en USD.
• Por cada aplicación se crea un pago con payment_method "17" y funding_source "credit", y un movimiento applicationToInvoice por -amount con related_invoice_id, related_payment_id y la nota "Saldo a favor aplicado a la orden de cobro.".
• Se recalcula el saldo pendiente de cada orden de cobro. Si queda liquidada, su estatus cambia a paid; si no, queda en overdue, issued o created según sus fechas.
• Con dos o más aplicaciones, los pagos comparten un payment_group_id que puedes usar en Cancelar grupo de pagos. Con una sola aplicación es null.
• Para deshacer una aplicación, cancela el pago relacionado.

Tipo de cambio

El tipo de cambio siempre es USD→MXN. exchange_rate es obligatorio en una aplicación cuando se cumple cualquiera de estas condiciones:

• currency es distinta a la moneda de la orden de cobro.
• La orden de cobro genera complemento de pago y currency es USD.

Si falta, es null o es menor o igual a cero, la API responde 400 con VALIDATION_ERROR y el mensaje "El tipo de cambio es requerido por el SAT." en applications.{i}.exchange_rate. Cuando no es obligatorio, la API no lo guarda y el pago responde con exchange_rate: null.

Para comparar el monto con el saldo pendiente de la orden de cobro:

Complemento de pago

• Si la orden de cobro tiene un CFDI PPD timbrado, la API timbra el complemento de pago con forma de pago 17, la moneda de currency y payment_date como fecha de pago. El pago responde con el complemento en complement.
• Si la orden de cobro no tiene CFDI PPD timbrado, el pago se crea sin complemento (complement: null).
• Con "test": true, el complemento se timbra de prueba sobre el CFDI PPD de prueba de la orden de cobro. Si la orden tiene un CFDI PPD real timbrado pero no uno de prueba, la API responde 409 con PPD_TEST_CFDI_REQUIRED y no registra nada.
• Si la solicitud falla después de timbrar, la API cancela los complementos que ya había timbrado.

Campos de la respuesta

Errores