Para plataformas · saldo BRL → PIX
Envía Pix mediante la API y sigue cada pago.
Envía PIX desde el saldo en reales brasileños de tu cuenta o de una subcuenta. Una integración para retiros de usuarios, pagos y transferencias, con débito identificado, tarifas desglosadas y seguimiento por API.
Pagos y transferencias integrados en tu sistema.
Usa payout cuando tu plataforma necesite pagar a un destinatario con saldo BRL disponible. Cada pago tiene una referencia, un coste y un estado para conciliarlo con tu sistema.
Para trabajar con varios destinatarios, tu aplicación debe controlar cada intención de pago y su identificador. No des por hecho que existe un único endpoint de lotes o un reparto automático. Consulta también cobros y pagos Pix en LuniumPay.
Qué preparar antes de enviar un PIX
Payout usa saldo BRL disponible. Sirve a las plataformas que ya reciben fondos mediante PIX en custodia y necesitan permitir retiros o transferencias. Cuando el dinero está en una billetera externa de criptomonedas, el flujo correspondiente es cash-out de criptomonedas a PIX.
Comprueba que esté habilitado
Lee payout.enabled en GET /keys/me y custodia_ativa en GET /saldo. Se aplican las condiciones de tu clave.
Comprueba el saldo y las tarifas
Consulta el ámbito correcto: el negocio o customer_ref. El saldo disponible debe cubrir amount_cents más las tarifas del retiro.
Crea y haz el seguimiento
Envía POST /payouts con una referencia guardada de forma persistente y sigue el payout_id devuelto hasta el resultado final.
GET /saldo devuelve solo el saldo del negocio. Para un cliente, usa GET /saldo?customer_ref=cliente-teste. GET /saldo/consolidado suma el negocio y los clientes, pero ese total no es un único saldo disponible para cada subcuenta.
Ejemplo de retiro PIX desde una subcuenta
Usa una clave lun_test_, guardada en el backend, y confirma key.sandbox=true en GET /keys/me. Los ejemplos siguientes usan documentos y destinos sintéticos. No los envíes con credenciales de producción.
Primero, acredita la subcuenta de prueba mediante POST /cashin/charge con destino: "saldo" y confirma el pago simulado. Espera a que el abono esté disponible y usa exactamente el mismo customer_ref en el retiro.
POST /payouts · cuerpo de ejemplo para el sandbox
{
"amount_cents": 5000,
"pix_key": "teste@example.com",
"pix_key_type": "email",
"tax_number": "00000000191",
"funding_source": "pix_brl",
"customer_ref": "cliente-teste",
"external_id": "sandbox-payout-001"
}Envía a https://api.luniumpay.com/payouts, con X-API-Key y Content-Type: application/json. El ejemplo envía R$ 50,00 ficticios; debes tener saldo para ese importe más las tarifas. Sin customer_ref, la operación usa el negocio.
Sustituye la clave PIX y el documento por los del destinatario. tax_number debe contener un CPF o CNPJ válido para claves de correo, teléfono y aleatorias. Para una clave CPF/CNPJ válida, la API obtiene el documento de la propia clave; si se indica, debe coincidir. beneficiary_name sigue siendo opcional y no acredita la titularidad. Las claves de 11 dígitos requieren pix_key_type: "cpf" o "phone"; los teléfonos usan el prefijo internacional, como +55.
Este flujo usa solo saldo en reales brasileños recibido por PIX. funding_source es opcional y solo admite pix_brl. El máximo por PIX es de 600000 centavos (R$ 6.000,00), sujeto a un límite inferior de la cuenta y a las tarifas.
En 409 external_id_divergente o external_id_nao_verificavel, consulta la orden indicada por payout_id/recovery_endpoint. Conserva el identificador; no generes otro para evitar el conflicto. En 503 idempotencia_indisponivel, espera y consulta el mismo external_id: puede existir una orden anterior.
La billetera USDT está separada del saldo BRL: requiere habilitación del proyecto, recibe depósitos externos de USDT y no usa /payouts. Cuando está habilitada, usa funding_source=crypto_usdt; este flujo no exige el documento del destinatario. Sus límites proceden de la cotización y de las condiciones de la API, no del límite máximo de R$ 6.000 del saldo BRL. No está disponible en el sandbox.
Cómo calcular el débito y mostrar el coste
El débito es amount_cents + fee_cents. La tarifa total de la operación reúne fee_service_cents y fee_provider_cents. Consulta saque_fee_bps, saque_taxa_provedor_tipo, saque_taxa_estimada_cents y la fórmula devuelta en GET /saldo.
Consulta la tarifa vigente en la API. Usa las condiciones de la clave para estimar y la tarifa efectiva registrada en la orden para conciliar. Los límites, el período de espera y las retenciones pueden impedir el uso de parte del saldo. 402 saldo_insuficiente significa que el saldo disponible no cubre el débito completo.
El sandbox calcula la tarifa publicada por su API sobre saldo ficticio; consulta las condiciones de producción con la clave real.
Un timeout no autoriza a pagar de nuevo
| Respuesta o estado | Acción del integrador |
|---|---|
processing | Sigue consultando GET /payouts/{payout_id}. No muestres el pago como completado. |
sent / payout.sent | Concilia el importe, las tarifas y los campos de prueba: e2e, paid_at y verify_url, cuando estén disponibles. |
failed o refunded | Consulta la orden y los movimientos. Un rechazo explícito y un resultado incierto requieren tratamientos distintos. |
| Timeout o respuesta incierta | Recupera la operación original. No crees otro external_id para la misma intención de pago. |
Guarda external_id y el identificador devuelto antes de actualizar tu pedido. En los reintentos, conserva la misma referencia y el mismo cuerpo. Configura un receptor HTTPS, valida la firma HMAC sobre el cuerpo sin procesar y elimina los duplicados mediante event_id. Después de un timeout, consulta la operación original antes de decidir si repites la solicitud. El manual de webhooks y conciliación detalla la implementación.
El saldo se reserva antes de llamar al proveedor. Un rechazo explícito puede revertir los débitos; una respuesta incierta requiere conciliación antes de la reversión. Implementa una pantalla que muestre «en procesamiento» y permita actualizar el estado sin crear otra orden.
Consultas de integración
¿Necesito registrar una billetera de criptomonedas para usar payout?
No. Payout PIX usa saldo en reales brasileños y una clave PIX de destino. Puedes recibir ese saldo mediante una solicitud de cobro con destino: "saldo", sin billetera fija.
¿Puedo separar el saldo por usuario?
Sí. Usa customer_ref en el depósito, la consulta y el retiro. La referencia organiza los saldos, pero tu clave de API tiene autoridad sobre tus subcuentas; tu backend debe autorizar a cada usuario.
¿Es necesario validar al titular antes del pago?
GET /pix/keys/lookup es una consulta auxiliar y puede retornar available=false o verified=false. En ese caso, muestra el titular como no verificado. No inventes un nombre ni confundas la falta de disponibilidad de la consulta con la de payout.
¿Cómo probar saldo insuficiente y resultado incierto?
Ejecuta el flujo payout de la integración guiada o del kit. En las pruebas por API, consulta GET /sandbox para la matriz de escenarios y usa settlement_uncertain cuando sea soportado. La resolución ficticia existe únicamente para claves de sandbox.