Saltar al contenido principal
Boletos y pago de facturas cubre el riel de boleto de Brasil: la emisión de boletos bancários y el pago de facturas como documentos de impuesto DARF y facturas de servicios públicos y de concesionarias. En la plataforma Lerian, operas esta capacidad desde el módulo Payments en Lerian Console, un plugin gestionado para Midaz aprovisionado para tu organización.

​
Qué puedes hacer

  • Emite boletos con fechas de vencimiento, registrados en tu ledger de Midaz. Un boleto es tradicional, o híbrido cuando el pagador también puede pagarlo por Pix. Puedes elegir su nosso número en la Console o a través de la API. A través de la API, un boleto también puede llevar multas, intereses y descuentos.
  • Emite una serie de 2 a 36 boletos en cuotas, o un lote de 1 a 25 boletos, en una sola solicitud a la API.
  • Paga facturas (pagos de impuesto DARF y facturas de servicios públicos y de concesionarias) directamente desde la Console.
  • Consulta una factura por su línea digitable antes de pagarla. La Console lo hace en el formulario de pago. La API tiene una operación para eso. La respuesta muestra el monto, las fechas y quién recibe el dinero.
  • Haz seguimiento de las operaciones desde un dashboard con tarjetas KPI, actividad reciente y acciones rápidas.

​
Emitir un boleto

Todo boleto registra al titular de la cuenta emisora como beneficiario final, y la respuesta devuelve a ese titular en guarantor. El servicio lee al titular en el CRM de Midaz cuando emite el boleto. No emite nada y rechaza la solicitud en estos casos:
  • La cuenta no tiene titular registrado, o el registro del titular está incompleto: 400 PBP-0116.
  • El titular registrado no puede ser beneficiario final: 422 PBP-0117.
  • El servicio no puede leer el registro, o la lectura no está configurada: 503 PBP-0118.
  • El pagador es el titular de la cuenta: 422 PBP-0119.

​
Boletos híbridos

Un boleto híbrido (type HYBRID) se emite junto con un cobro Pix con vencimiento. Antes de emitir el primero, define la clave Pix y la dirección del receptor con POST /v1/admin/pix-config. Léelas de vuelta con GET /v1/admin/pix-config. Sin una configuración completa, el servicio rechaza el boleto híbrido con 422 PBP-0120. Una clave CPF o CNPJ debe ser el documento del titular de la cuenta emisora. El servicio guarda un historial de los cambios de la clave Pix. GET /v1/admin/pix-config/history los lista, del más reciente al más antiguo, con la clave que fijó cada cambio, la clave que reemplazó, quién lo hizo y cuándo. Una clave CPF, e-mail o teléfono aparece enmascarada. La lista trae los cambios que POST /v1/admin/pix-config hizo después de que el historial empezó, así que una lista vacía no significa que el tenant no tiene clave. pixTxId llega cuando se confirma la emisión. El qrCode de Pix, su pixLocation y el PDF solo se sirven después de que BTG registra el boleto. Mientras el boleto está PENDING, el PDF responde 503 con Retry-After. Un boleto híbrido puede recibir un segundo pago por la vía que no lo liquidó. paidVia registra la vía que liquidó el boleto, BOLETO o PIX. El servicio no acredita el segundo pago: el boleto sigue liquidado por la primera vía. Cuando BTG asocia el segundo pago al boleto, excessPayments lo lista y el evento BOLETO_EXCESS_PAYMENT lo anuncia. Un segundo pago que BTG no asocia al boleto llega a la cuenta de cobro y no se lista.

​
Series de cuotas

POST /v1/boletos/installments crea una serie de 2 a 36 boletos tradicionales, uno por cuota. El total se divide en partes iguales, y el resto va a la última cuota, o tú indicas cada monto en installmentAmounts. La cuota k vence en firstDueDate más k−1 veces intervalDays, de 1 a 365 días, sin ajuste por día hábil. La solicitud responde de inmediato con el estado CREATED, y BTG registra cada cuota después, una por vez. Sigue la serie con GET /v1/boletos/installments/{series_id}. Su status es CREATED, COMPLETED, PARTIAL_FAILURE o FAILED, y closed indica si toda cuota está liquidada, cancelada, inactivada o fallida. Una cuota que BTG aceptó todavía puede terminar FAILED, así que espera a que closed sea true para conocer el resultado final.

​
Lotes de boletos

POST /v1/boletos/batches emite de 1 a 25 boletos tradicionales para una cuenta y un ledger. Responde 202, y el servicio emite cada ítem después, de forma independiente.
  • Un lote fuera de 1 a 25 ítems se rechaza con 422 PBP-0122.
  • Cuando algún ítem incumple una regla, el servicio rechaza el lote completo con 422 PBP-0123 y lista cada problema en itemErrors. No se emite nada. Dos ítems con el mismo nosso número aparecen ahí como PBP-0125.
  • GET /v1/boletos/batches lista lotes, y GET /v1/boletos/batches/{batch_id} devuelve uno con sus ítems.
  • POST /v1/boletos/batches/{batch_id}/cancel intenta cancelar cada ítem en estado CREATED y devuelve un resultado por ítem: CANCELED, CANCEL_FAILED cuando BTG rechaza la cancelación, o NOT_CANCELABLE para cualquier otro ítem, que no se modifica.
  • GET /v1/boletos lista ítems de lote con kind BATCH, o con batchId. Un boleto de un lote lleva batchId y batchPosition.

​
Notificaciones

Una configuración de webhook recibe solo los tipos de evento que nombra en enabledEvents (consulta POST /v1/admin/webhooks). Los eventos de boleto incluyen BOLETO_CREATED, BOLETO_BATCH_FINISHED, BOLETO_EXCESS_PAYMENT y BOLETO_FAILED. BOLETO_FAILED anuncia un boleto individual, una cuota o un ítem de lote que falló. Su cuerpo nombra el kind, la serie y el número de cuota o el lote y la posición, y el error. PIX_KEY_CHANGED anuncia un cambio de la clave Pix. Su aviso nombra el tipo de la clave, no la clave: lee el cambio con la operación de historial. Un evento de pago (PAYMENT_SETTLED, PAYMENT_REJECTED, PAYMENT_FAILED, PAYMENT_CANCELED o PAYMENT_SCHEDULED) anuncia el nuevo estado de un pago, ya lo fije el webhook de BTG o la conciliación.

​
Encuentra un boleto después de una emisión incierta

Una emisión sin nosso número puede responder 202 con un boleto PENDING sin código de barras. El servicio no recibió una respuesta confirmada de BTG, y completa el boleto después. Léelo con GET /v1/boletos/{id}. No envíes la solicitud de nuevo con un nuevo Idempotency-Key: BTG puede haber emitido ya el boleto, y una segunda solicitud puede emitir un segundo. Reenviar con la misma clave es seguro. Cuando la lectura muestre FAILED, el boleto no se emitió, y puedes enviar la solicitud de nuevo con una nueva clave. Cuando BTG rechaza una emisión de una forma que prueba que no emitió ningún boleto, el servicio responde el rechazo y el boleto registrado termina FAILED. GET /v1/boletos lo lista, y un nuevo intento registra un nuevo boleto.

​
Cómo un pago de factura mueve el dinero

  1. El ledger reserva el monto en la cuenta de fondeo. Si el saldo o el límite de sobregiro no lo permiten, el pago falla aquí, y BTG no lo recibe.
  2. Payments envía el pago a BTG.
  3. Cuando Payments registra que BTG aceptó el pago, la API responde 201 con el estado actual del pago, por lo general CREATED. Mientras Payments no tiene una respuesta registrada de BTG, la API responde 202 y el pago queda UNCONFIRMED.
  4. Para un pago de boleto bancario o de servicio público, la conciliación lee el pago en BTG. Si BTG no tiene registro de él durante toda la ventana que define el despliegue, el pago falla con PBP-0211, y Payments libera los fondos.
  5. Para un pago de DARF, los fondos siguen reservados hasta que llega el resultado de BTG.
No envíes de nuevo un pago UNCONFIRMED con un nuevo Idempotency-Key. BTG puede tenerlo ya, y una segunda solicitud puede pagar la factura dos veces. Reenviar con la misma clave es seguro.

​
Encuentra un pago después de un error

Una solicitud que crea un pago puede terminar sin el id del pago, por ejemplo después de un timeout o de una respuesta con estado 5xx. Primero, envía la solicitud de nuevo con el mismo Idempotency-Key. Después de un 409 con PBP-0007 o de un 503 con PBP-0008, espera y envíala de nuevo con la misma clave. Después de que la misma clave devuelva otra respuesta, llama a GET /v1/payments con idempotencyKey igual a esa clave para encontrar lo que la solicitud creó. Envía el mismo X-Organization-Id de esa solicitud. Una respuesta que el servicio devuelve de nuevo a partir de la almacenada lleva el header X-Idempotency-Replayed: true. Después de enviar una solicitud de nuevo con un nuevo Idempotency-Key, no la envíes de nuevo con la clave anterior. La clave anterior puede ejecutar la solicitud otra vez, y las dos solicitudes pueden pagar.

​
Por dónde empezar

Payments en Lerian Console

Activa el plugin Payments y haz un primer recorrido por el módulo.

Resumen de Payments

El dashboard: tarjetas KPI, operaciones recientes y atajos.

Boletos

Emite, consulta y gestiona boletos.

Pago de facturas

Paga DARF y facturas de servicios públicos desde la Console.