Vista previa de un complemento de pago (sin timbrar)
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
Authorization: Bearer sk_test_... | sk_live_...El header x-account-id indica la cuenta. Si no eres miembro, la respuesta es 403.
Ejemplos
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
{
"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
| Status | code | Cuándo aparece |
|---|---|---|
| 400 | validation_error | El 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. |
| 401 | unauthorized | Falta el header Authorization o la llave es inválida. |
| 403 | forbidden | No eres miembro de la cuenta del header x-account-id. |
| 404 | not_found | Alguna factura de documents no existe en tu cuenta. |
| 429 | rate_limited | Excediste 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 decreate_payment(una factura coninvoiceIdymonto, odocuments) y los manda aquí comodocuments. Usa la misma tarjeta que la factura: «Autorizar y timbrar» (llamacreate_payment), «Pedir cambios» y «Descargar PDF». Ver el servidor MCP.
