Para wallets e plataformas · cripto → PIX
Pague PIX com cripto e acompanhe o comprovante
Use cripto de uma carteira externa para pagar um destinatário por PIX. Antes do envio, você consulta a cotação, confirma o valor e recebe as instruções de depósito. Acompanhe o pagamento e os links de comprovante quando disponíveis.
Como começar com sua IA
Você pode usar Gemini, ChatGPT ou outra IA para entender este percurso e preparar sua integração.
Informe o PIX e escolha a cripto
Use a chave com o valor em reais, ou o copia e cola completo. A IA consulta moedas e redes aceitas e apresenta a cotação, os custos e o vencimento.
Confirme e envie
Confira o valor efetivo do PIX e a quantidade exata de cripto. Após o aceite, envie ao endereço retornado, na rede correta e com memo/tag quando exigido.
Acompanhe o pagamento
Veja depósito, confirmações e pagamento do PIX. A operação apresenta o E2E e os links de comprovante disponíveis; o documento pode ficar pronto depois do pagamento.
Um pedido para sua IA
Quero pagar um PIX usando minha cripto com a Lunium. Confira as moedas e redes disponíveis, mostre a cotação e como conectar minha conta. Com as ferramentas conectadas, peça minha confirmação antes do aceite e acompanhe até o comprovante.
Pagamentos por chave seguem o catálogo. Copia e cola aceita atualmente USDT/USDC em rotas compatíveis. O prazo depende da rede e do processamento do PIX.
A execução real pelo chat exige um agente conectado à sua conta. O conector público da Lunium oferece demonstrações; a conexão de produção por OAuth no ChatGPT ainda não está disponível. Nunca cole sua chave de produção em uma conversa.
Da carteira do cliente à chave PIX
O cash-out é a saída de cripto externa para reais. Ele serve a wallets e plataformas que oferecem saque em PIX a usuários com ativos em blockchain. A rede de entrada e a moeda precisam existir em GET /catalog; esse catálogo é diferente do usado para entregar cripto após um PIX.
Cote antes de depositar
Use POST /cash-outs com a quantidade de cripto ou o valor desejado em reais. Mostre o valor líquido, o destinatário, a rede e a validade.
Aceite a cotação
Chame POST /cash-outs/{cashout_id}/accept. Só depois apresente o endereço de depósito, a quantidade exata e o memo quando existir.
Acompanhe até o PIX
Consulte a ordem ou receba webhooks. Confirmação de depósito ainda não é pagamento PIX; aguarde state=COMPLETED.
Seu dinheiro já está no saldo BRL da Lunium? Use payout PIX para debitá-lo. Cash-out é o fluxo para receber um novo depósito de cripto externa.
Exemplo de cotação de USDT para PIX
Use uma chave lun_test_, guardada no backend, e confirme key.sandbox=true em GET /keys/me. Os exemplos abaixo usam documentos e destinos sintéticos. Não os envie com credenciais de produção.
POST /cash-outs · corpo de exemplo para sandbox
{
"asset": "USDT",
"network": "polygon",
"amount": "10.00",
"pix_key": "teste@example.com",
"pix_key_type": "email",
"external_id": "sandbox-usdt-pix-001"
}Envie para https://api.luniumpay.com/cash-outs com X-API-Key e JSON. Guarde o cashout_id retornado, aceite a cotação e acompanhe GET /cash-outs/{cashout_id}. A criação pode responder 200 em produção ou 201 no sandbox; trate o sucesso conforme o contrato, sem exigir apenas um desses códigos.
| Campo | Regra da integração |
|---|---|
amount | Quantidade de cripto em string decimal, como "10.00". Não use float. |
brl_amount | Alternativa para cotar a partir do PIX desejado, como "50.00". Para pagar uma chave, envie amount ou brl_amount. Para uma cobrança com valor, envie somente br_code completo, sem esses dois campos e sem pix_key; USDT/USDC em rota compatível. |
network | Rede de entrada cripto do GET /catalog. Não copie as redes do catálogo de entrega. |
refund_address | Confirme uma carteira sob controle do destinatário, compatível com o ativo e a rede da devolução. Após conversão, esses dados podem diferir da cripto enviada. Se a ordem pedir endereço, siga refund_asset, refund_network e o fluxo autenticado de AWAITING_REFUND_ADDRESS. |
No sandbox, o depósito e o PIX são simulados após o aceite. Nunca envie cripto ao endereço fictício. Para executar todos os passos, use node sandbox.mjs cashout ou python3 sandbox.py cashout no kit de integração.
Quando considerar o PIX concluído
| Etapa | Estados e ação |
|---|---|
| Cotação e depósito | QUOTE_CREATED, AWAITING_DEPOSIT, DEPOSIT_DETECTED: mantenha a mesma ordem e apresente suas instruções. |
| Confirmação e execução | DEPOSIT_CONFIRMED, SELLING, SOLD, FORWARDING, PAYING_OUT: acompanhe. Nem toda rota usa todas as etapas. |
| Pagamento concluído | COMPLETED: confira pix_e2e, pix_paid_at, receipt_url e verify_url, quando presentes. Os links podem chegar depois; acompanhe a mesma ordem ou cashout.receipt_ready. |
| Exceções | MANUAL_REVIEW, REFUNDING_CRYPTO, REFUNDED, EXPIRED e FAILED exigem tratamento específico. |
Use os links de comprovante retornados. A consulta pública de um E2E verifica um PIX conhecido; não substitui a confirmação de toda a jornada. Em devolução, acompanhe REFUNDED e refund_tx_hash. Prazo e valor dependem da etapa atingida e do provedor.
Guarde external_id e o identificador retornado antes de atualizar seu pedido. Em retry, mantenha a mesma referência e o mesmo corpo. Configure um receptor HTTPS, valide a assinatura HMAC sobre o corpo bruto e deduplique por event_id. Depois de timeout, consulte a operação original antes de decidir repetir. O manual de webhooks e conciliação detalha a implementação.
Rede, devolução e limites no checkout
Consulte os limites da chave em GET /keys/me e as condições efetivas na cotação. Só mostre a oferta enquanto válida. Deposite exatamente o valor aceito na rede retornada e inclua deposit_tag quando houver. Depósito tardio ou divergente deve ser conciliado na mesma ordem; não reutilize o endereço para outra venda.
Em produção, não use a origem on-chain como carteira de devolução sem confirmar seu controle: um saque de exchange pode ter saído de uma carteira coletiva. Cadastre refund_address apropriada. A disponibilidade de uma rota, seus custos e as confirmações exigidas podem mudar.
Dúvidas de integração
Qual a diferença entre USDT para PIX e payout PIX?
USDT para PIX recebe uma nova transferência de cripto e depois paga reais. Payout PIX usa o saldo BRL já disponível na custódia. Escolha pelo lugar onde o dinheiro está antes da operação.
Posso definir quanto o recebedor terá em reais?
Use brl_amount para informar o alvo em reais. A cotação retorna a quantidade exata de cripto e o valor efetivo do PIX, que pode diferir por arredondamento. Confira esses valores, validade, taxas e limites antes do aceite.
O recebedor precisa ser identificado por CPF?
Você informa uma chave PIX válida. Formatos de 11 dígitos exigem o tipo cpf ou phone. A consulta auxiliar de titular pode estar indisponível e não comprova titularidade quando verified=false.
Posso pagar qualquer QR PIX com cripto?
Pagamento por br_code tem disponibilidade própria e pode ser recusado em produção. Não o trate como equivalente ao pagamento para uma chave PIX nem como recurso sempre habilitado.