Saltar al contenido principal
Crea un payout de pago de impuestos, facturas o servicios en México, con ejemplos de solicitud/respuesta, manejo de errores y webhooks. Esta guía muestra cómo crear un payout de pago de impuestos, facturas o servicios mediante la API: la estructura de la solicitud, las descripciones de los campos, la gestión de respuestas y las notificaciones de webhook. Lee primero Resumen de pagos de impuestos, facturas y servicios para conocer el alcance y el flujo de pago.

Antes de comenzar

  • Credenciales API válidas (token de acceso).
  • Una cuenta específica financiada para el pago de impuestos y facturas.
  • El billType que planeas pagar, validado con el catálogo de BillType.
  • La referencia de la factura (por ejemplo, una referencia de pago del SAT para México) obtenida del contribuyente o del emisor de la factura.

Endpoint

Para crear un payout de pago de impuestos, facturas o servicios, envía una solicitud POST al endpoint Create a Payout con paymentMethod.type establecido en "BillPay".

Encabezados obligatorios


Solicitud

curl

Parámetros clave de la solicitud

La solicitud requiere varios objetos clave. Consulta la referencia Create a Payout para ver la lista completa de campos, incluidos sender y merchant.

Gestión de la respuesta

Respuesta exitosa

Campos de respuesta clave

Respuesta de error

Consulta la lista completa de códigos de estado y de error en Payout Status and Error Codes.

Consideraciones sobre la referencia de la factura

En México, el billReference es la referencia de pago del SAT: una clave alfanumérica de 20 caracteres que identifica de forma única el concepto fiscal, el contribuyente y el periodo fiscal.
  • Una referencia de pago del SAT tiene una ventana de vigencia limitada establecida por el SAT. Localpayment rechaza una referencia vencida solo una vez que ha sido validada contra el SAT, por lo que esta verificación no es necesariamente instantánea y es posible que el webhook de rechazo no se dispare de inmediato.
  • Localpayment no valida que amount coincida con el valor codificado en la referencia, y una referencia no puede reutilizarse una vez que ha sido pagada. Tu integración debe validar estas condiciones antes de enviar la solicitud.

Pruebas en Stage

Para que puedas validar el flujo de extremo a extremo antes de salir a producción, Localpayment simula la respuesta del emisor de la factura en Stage siempre que el beneficiary.billReference que tú envíes coincida con una de las líneas de captura fijas del catálogo siguiente. Consulta Payout Status and Error Codes para ver la lista completa.
  • Estas líneas de captura solo funcionan en Stage. No están habilitadas en Producción.
  • Cualquier billReference fuera de este catálogo no se resolverá en Stage: como no existe un sandbox real del lado del emisor de la factura contra el cual validar, la transacción permanece en IN_PROGRESS indefinidamente. Utiliza uno de los valores anteriores para tus pruebas en Stage.

Webhooks

Localpayment te notifica el estado final de la transacción mediante webhook, con la misma estructura de payload que la respuesta anterior. La notificación incluye el status final, el externalId y el objeto beneficiary con billType y billReference. Consulta Webhooks para ver ejemplos de payload, validación de firma y configuración.

Reintentos

  • Localpayment reintenta una entrega fallida del webhook hasta 3 veces con retroceso exponencial.
  • Tu endpoint debe responder con HTTP 200 para confirmar la recepción. Cualquier otro código de estado cuenta como una entrega fallida.
  • Si fallan los 3 reintentos, la transacción permanece en su estado final y tú puedes recuperarla manualmente a través de la API.

Próximos pasos

Resumen de pagos de impuestos, facturas y servicios

Alcance, flujo de pago y estados de la transacción.

Aprobaciones y doble firma

Aprende cómo autorizar un payout creado con requireAuth.
Última modificación el 10 de noviembre de 2026