Checkout PIX con API REST y webhook para USDT o USDC
Flujo en cinco pasos
Crea la clave
Usa POST /keys/sandbox con tu correo para validar el contrato sin dinero, o POST /keys para crear tu clave de producción. La clave sin cifrar se muestra una sola vez.
Consulta el catálogo y los límites
Consulta GET /cashin/catalog, GET /keys/me y GET /cashin/limits. No fijes en el código la red, el mínimo, el máximo ni el tramo de retención.
Obtén la vista previa
POST /cashin/preview valida el activo, la red, la dirección y el importe sin crear una solicitud de cobro.
Crea y muestra el PIX
POST /cashin/charge recibe el importe, el CPF/CNPJ del pagador, el destino y external_id. Muestra el QR solo después de informar de cualquier retención devuelta por la API.
Confirma y concilia
Procesa el webhook firmado. Usa GET /cashin/{cashin_id}/status como alternativa y el mismo external_id en los reintentos.
Solicitud mínima de producción
curl -X POST https://api.luniumpay.com/cashin/charge \
-H 'Content-Type: application/json' \
-H 'X-API-Key: SUA_CHAVE' \
-d '{
"amount_cents": 25000,
"payer_tax_number": "CPF_OU_CNPJ",
"asset": "usdt",
"chain": "polygon",
"payout_address": "CARTEIRA_DO_CLIENTE",
"external_id": "pedido-84721"
}'
El cuerpo de la solicitud es ilustrativo. Consulta el OpenAPI en directo para conocer los campos, límites y respuestas vigentes antes de implementar.
Estados que debe explicar el checkout
pending
QR creado y aún no pagado. No generes otro automáticamente.
delayed
PIX pagado y liberación retenida. No es un fallo; muestra el plazo devuelto por la API.
paid
El PIX se ha recibido. Aún debes confirmar settlement_status; no entregues el producto basándote solo en este estado.
settled
La liquidación se ha completado. Acepta también paid solo cuando settlement_status sea sent o confirmed, según el contrato del flujo.
expired / refunded
Cierra el intento anterior. Si es necesario, crea otro con un identificador comercial nuevo.
Qué debe estar preparado antes del primer PIX real
external_id por pedido, guardado de forma persistente antes de la llamada.Preguntas frecuentes
¿La clave de producción depende de aprobación manual?
No. POST /keys crea la clave de producción en autoservicio. El nombre es obligatorio; el correo, la billetera y el webhook se pueden definir o actualizar según el contrato.
¿Necesito usar polling?
No como vía principal. Los webhooks reducen la latencia y la carga. La consulta de estado debe existir para conciliar y recuperar eventos.
¿Cómo evito duplicar una solicitud de cobro?
Envía external_id. Una repetición idéntica recupera la operación original; cambiar parámetros con el mismo identificador devuelve un conflicto.
Prueba el contrato antes del checkout real
Empieza sin dinero, valida los casos de fallo y cambia a una clave de producción cuando tu tratamiento de los estados sea correcto.