Documentación / API / Complementos de pago (REP)

Vista previa de un complemento de pago (sin timbrar)

POSThttps://api.cfdi.express/v1/payments/previewAPI key

Desde la v1.54.0, valida un complemento de pago y lo arma exactamente como se timbraría, sin timbrarlo: no cobra, no aparta folio, no mueve saldos y no guarda nada.

Recibe el mismo cuerpo que POST /v1/payments. Para el pago de una sola factura, manda una sola entrada en documents: este endpoint no recibe el cuerpo de POST /v1/invoices/{id}/payments (monto e invoiceId en la ruta).

Corre las mismas validaciones que al timbrar, con el mismo código: facturas PPD timbradas con saldo pendiente, sobrepago (400 con subcode overpay), secuencia de parcialidades, facturas repetidas, mismo emisor, RFC receptor y moneda, monto igual a la suma de importePagado y una forma de pago real (no 99).

Responde los totales, cada DoctoRelacionado con su parcialidad, saldoAnterior y saldoInsoluto, los datos del CFDI 4.0 con Pagos 2.0 sin sellar y html: la representación impresa con la misma plantilla que el PDF, la marca de agua PREVIEW y la leyenda «VISTA PREVIA — SIN VALIDEZ FISCAL», sin UUID, sellos ni QR.

Es opcional: POST /v1/payments no la exige. No pide Idempotency-Key, no consume timbre ni saldo, no incrementa el folio, no toca el saldoPendiente de las facturas y no crea ningún recurso. Para timbrar lo que se aprobó, manda el mismo cuerpo a POST /v1/payments con tu Idempotency-Key.

La serie es CP. El folio del REP se asigna al timbrar, así que folio siempre es proyectado (folioIsProjected: true). fecha es la hora de la vista previa; fechaPago es la del cuerpo o la hora actual.

En video

¿El REP salió mal? Revísalo antes de timbrar #CFDI · 0:42 · YouTube
Factura y complemento de pago con vista previa en Claude | CFDI Express API · 3:49 · YouTube
Autenticación
Authorization: Bearer sk_test_... | sk_live_...

El header x-account-id indica la cuenta. Si no eres miembro, la respuesta es 403.

Ejemplos

cURL
curl -X POST https://api.cfdi.express/v1/payments/preview \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "formaPago": "03",
    "fechaPago": "2026-11-18T12:00:00",
    "documents": [
      { "invoiceId": "inv7k3q9x2m4v1t8p6d0n5cb", "importePagado": 29000 }
    ]
  }'

Respuesta

200 OK
{
  "object": "payment_preview",
  "livemode": false,
  "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
  "emisor": { "rfc": "EKU9003173C9", "name": "ESCUELA KEMPER URGATE" },
  "serie": "CP",
  "folio": "55",
  "folioIsProjected": true,
  "fecha": "2026-11-18T12:05:00",
  "fechaPago": "2026-11-18T12:00:00",
  "formaPago": "03",
  "monto": 29000,
  "currency": "MXN",
  "exchangeRate": 1,
  "documents": [
    {
      "invoiceId": "inv7k3q9x2m4v1t8p6d0n5cb",
      "numParcialidad": 1,
      "importePagado": 29000,
      "saldoAnterior": 58000,
      "saldoInsoluto": 29000
    }
  ],
  "receiver": {
    "rfc": "XIA190128J61",
    "nombre": "XENON INDUSTRIAL ARTICLES",
    "domicilioFiscal": "01160",
    "regimenFiscal": "601"
  },
  "cfdi": { "Version": "4.0", "TipoDeComprobante": "P", "...": "recortado" },
  "html": "<!DOCTYPE html>…"
}

Errores

StatuscodeCuándo aparece
400validation_errorEl mismo cuerpo lo rechazaría POST /v1/payments: mismo detail, subcode y errors que el timbrado. Incluye overpay (el pago excede el saldo pendiente), numParcialidad fuera de secuencia, una factura que no es PPD, no está timbrada o ya está liquidada, facturas repetidas o de otro emisor, receptor o moneda, monto distinto de la suma de documents[].importePagado y formaPago 99. Solo en la vista previa: una factura sin el CFDI guardado, porque sin él no se pueden prorratear sus impuestos.
401unauthorizedFalta el header Authorization o la llave es inválida.
403forbiddenNo eres miembro de la cuenta del header x-account-id.
404not_foundAlguna factura de documents no existe en tu cuenta.
429rate_limitedExcediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After.

Notas

  • Nunca responde 402: la vista previa no usa saldo. Un rechazo del SAT (sat_rejected) solo puede aparecer al timbrar.
  • Por MCP es la herramienta preview_payment. Recibe los argumentos de create_payment (una factura con invoiceId y monto, o documents) y los manda aquí como documents. Usa la misma tarjeta que la factura: «Autorizar y timbrar» (llama create_payment), «Pedir cambios» y «Descargar PDF». Ver el servidor MCP.

Continuar