Navegar e buscar
Todos os assuntos
Documentação para parceiros
Referência da API
Reserva operacional: R$ 1 por nova operação em chave Pix (pix_key_reserve_usd) ou Copia e Cola (copia_e_cola_buffer_usd), já incluída na cotação. Ordens anteriores e DePix mantêm suas condições. Contrato completo 1.44.2.
Os campos, rotas e respostas do contrato publicado. Comece pelo manual para escolher o fluxo.
Crie sua chave de produção em 60 segundos
Uma chamada, sem aprovação humana e sem espera: a chave lun_live_ é criada na mesma resposta, igual à de teste. Quer só testar? POST /keys/sandbox com o seu e-mail dá uma chave de sandbox na mesma chamada. Ver o passo a passo.
Novidade: Carteira USDT/USDC
Deposite USDT ou USDC em várias redes e pague PIX com esse saldo, por chave ou Copia e Cola, pela API (/carteira-usdt) ou pelo painel. Liberada para todas as chaves de produção; teste com a chave lun_test_, que usa o simulador. Como funciona · Referência.
08/10/2026 · OpenAPI 1.44.0: na venda de DePix, refund_address deixa de ser obrigatória na criação: a carteira de devolução só é pedida se a venda falhar (AWAITING_REFUND_ADDRESS, webhook cashout.awaiting_refund_address e POST /cash-outs/{cashout_id}/refund-address), e DePix que já tinha ido para o provedor só é devolvido depois de o retorno ser confirmado, no máximo o que voltou. No painel do parceiro: conta nova ativada com código de 6 dígitos por e-mail, Encerrar as outras sessões em Meu acesso, e-mail de aviso quando a senha muda, Pagar com cripto com stablecoins e as 30 principais criptos, e saque da comissão a partir de US$ 10. Fluxograma da venda de cripto · Carteira de devolução · Painel · Tudo o que mudou.
08/10/2026 · OpenAPI 1.43.1: o pedido de depósito vale 1 hora (deposit_validity_hours = 1; expires_at = criação + 1 h); envie dentro do prazo e o crédito é automático ao confirmar na rede. No novo painel do parceiro (parceiros.luniumpay.com, mesmo login), o pedido mostra o QR Code do endereço e a contagem regressiva; o painel também traz resumo do negócio, comprovantes em PDF, notificações e equipe com papéis. Conheça o painel.
Novidade: prêmio de US$ 1.000 para parceiros
Até 31/10/2026, o primeiro parceiro cuja chave de produção liquidar 100.000 USDT na compra (cashin.settled) e 100.000 USDT na venda (COMPLETED com Pix pago) leva US$ 1.000 em USDT. Regras completas.
Taxas
A taxa da LuniumPay é definida por parceiro e cai com o volume. Integração padrão: 2% + R$ 2,00 por operação. Parceiros de volume: taxa negociada, chegando a 35 bps sobre a cotação de referência de mercado do USDT para parceiros exclusivos. A taxa vigente da sua chave aparece em GET /keys/me e toda cotação já vem líquida. Sem mensalidade; comece com qualquer volume. Tabela de taxas por produto.
Lunium Partners
Comunidade oficial de integradores. Acompanhe avisos operacionais, manutenções, mudanças da API e a troca entre parceiros. A participação é fortemente recomendada desde o início da integração.
Entrar no Lunium PartnersComo participarOperação e conciliação
Configure a comissão, entenda cada taxa, recupere o monitor e trate incidentes com o contrato vigente.
Taxas e comissõesRecuperar acessoResolver incidentes01 / RECEBERPIX para custódia
Receba em reais. Escolha o destino do saque depois.
02 / SACARSaldo para criptoMoeda, rede e carteira escolhidas a cada retirada.
03 / OPERARAPI pelo TelegramCobrança, saldo e saques no grupo do projeto.
Referência gerada a partir da OpenAPI publicada. As descrições de campos preservam o idioma do contrato. Condições dinâmicas devem ser consultadas na API.
Nenhuma seção encontrada. Tente outra palavra.
Como usar esta referência
Autenticação: X-API-Key. Base: https://api.luniumpay.com. Corpos de requisição usam JSON. A omissão de um campo opcional não desativa as demais validações da operação.
Fluxos, Telegram, webhooks e checklist: abra o manual de integração.
GET /carteira-usdt
Saldo e estado da carteira USDT
Saldo disponível, reservado e confirmando; redes aceitas agora; mínimos. Comece por aqui.
Responses
200 OK
JSON schema · 200
{
"type": "object",
"description": "Estado e saldo da carteira USDT do projeto.",
"properties": {
"enabled": {
"type": "boolean",
"description": "Carteira pronta para operar agora."
},
"sandbox": {
"type": "boolean",
"description": "Presente e true só com chave de teste (simulador)."
},
"funding_source": {
"type": "string",
"enum": [
"crypto_usdt"
]
},
"currency": {
"type": "string",
"enum": [
"USDT"
]
},
"pix_rules": {
"type": "object",
"properties": {
"recipient_document_required": {
"type": "boolean"
}
}
},
"networks": {
"type": "array",
"description": "Redes aceitas AGORA para depósito, com as moedas de cada uma e o prazo estimado de crédito.",
"items": {
"type": "object",
"properties": {
"network": {
"type": "string",
"example": "polygon"
},
"name": {
"type": "string",
"example": "Polygon"
},
"assets": {
"type": "array",
"items": {
"type": "string",
"enum": [
"USDT",
"USDC"
]
}
},
"eta_minutes": {
"type": [
"integer",
"null"
]
}
}
}
},
"balance": {
"type": "object",
"properties": {
"available": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": "Disponível para pagar Pix, em USDT (6 casas)."
},
"reserved": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": "Reservado por Pix em andamento."
},
"confirming": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": "Depósitos vistos, aguardando a confirmação da custódia."
}
}
},
"min_deposit": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": "Depósito mínimo em USDT."
},
"min_payment_brl": {
"type": "string",
"example": "25.00",
"description": "Menor Pix pago com USDT, em reais."
},
"deposit_validity_hours": {
"type": "number",
"description": "Validade de um pedido de depósito, em horas (hoje 1)."
},
"payments_enabled": {
"type": "boolean"
},
"payment_methods": {
"type": "object",
"properties": {
"pix_key": {
"type": "boolean"
},
"br_code": {
"type": "boolean"
}
}
}
}
}401 Chave ausente ou inválida.
403 carteira_nao_liberada: a carteira não está liberada para este projeto.
503 carteira_indisponivel / pagamentos_indisponiveis: tente de novo em instantes (acao: esperar).
GET /carteira-usdt/deposits
Listar depósitos
Os 100 pedidos mais recentes e o que foi creditado.
Responses
200 OK
JSON schema · 200
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"description": "Pedido de depósito. O VALOR EXATO que chega identifica o depósito: envie `amount_to_send` na rede indicada antes de `expires_at`.",
"properties": {
"deposit_id": {
"type": "string",
"example": "ud_3f9c0a1b2c3d4e5f6a7b"
},
"status": {
"type": "string",
"enum": [
"waiting",
"confirming",
"available",
"expired",
"under_review",
"reversed"
],
"description": "`waiting` aguardando o envio · `confirming` visto, confirmando · `available` creditado no saldo · `expired` prazo acabou sem depósito · `under_review` em conferência · `reversed` desfeito."
},
"amount_to_send": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": "Valor exato a enviar (as casas finais identificam o seu depósito)."
},
"amount_received": {
"type": [
"string",
"null"
],
"description": "O que chegou (crédito)."
},
"address": {
"type": "string",
"description": "Endereço de destino na rede escolhida. No teste é fictício (`SANDBOX-NAO-ENVIE-FUNDOS`)."
},
"network": {
"type": "string"
},
"network_name": {
"type": "string"
},
"asset": {
"type": "string"
},
"accepted_assets": {
"type": "array",
"items": {
"type": "string"
}
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Prazo do pedido: 1 hora a partir da criação (`created_at` + `deposit_validity_hours`). Envie dentro do prazo."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"credited_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"origin": {
"type": "string",
"enum": [
"request",
"assigned_by_support"
]
},
"instructions": {
"type": "string",
"description": "Só na criação: o texto para mostrar ao usuário."
},
"sandbox": {
"type": "boolean"
}
}
}
}
}
}401 Chave ausente ou inválida.
403 carteira_nao_liberada: a carteira não está liberada para este projeto.
503 carteira_indisponivel / pagamentos_indisponiveis: tente de novo em instantes (acao: esperar).
POST /carteira-usdt/deposits
Pedir um depósito (USDT/USDC)
Abre um pedido com VALOR EXATO e prazo de 1 hora (expires_at). Mostre ao usuário amount_to_send, network_name e address. O crédito chega sozinho; acompanhe por GET /carteira-usdt/deposits ou pelo webhook wallet.deposit_credited. USDC entra 1 para 1 no saldo.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
amount | string | true | USDT com até 6 casas; mínimo em min_deposit. |
network | string | false | Uma das redes de GET /carteira-usdt (networks[].network). |
Request schema
{
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "string",
"example": "100",
"description": "USDT com até 6 casas; mínimo em min_deposit."
},
"network": {
"type": "string",
"default": "polygon",
"description": "Uma das redes de GET /carteira-usdt (networks[].network)."
}
}
}Example
{
"amount": "100",
"network": "tron"
}Responses
201 Pedido criado.
JSON schema · 201
{
"type": "object",
"description": "Pedido de depósito. O VALOR EXATO que chega identifica o depósito: envie `amount_to_send` na rede indicada antes de `expires_at`.",
"properties": {
"deposit_id": {
"type": "string",
"example": "ud_3f9c0a1b2c3d4e5f6a7b"
},
"status": {
"type": "string",
"enum": [
"waiting",
"confirming",
"available",
"expired",
"under_review",
"reversed"
],
"description": "`waiting` aguardando o envio · `confirming` visto, confirmando · `available` creditado no saldo · `expired` prazo acabou sem depósito · `under_review` em conferência · `reversed` desfeito."
},
"amount_to_send": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": "Valor exato a enviar (as casas finais identificam o seu depósito)."
},
"amount_received": {
"type": [
"string",
"null"
],
"description": "O que chegou (crédito)."
},
"address": {
"type": "string",
"description": "Endereço de destino na rede escolhida. No teste é fictício (`SANDBOX-NAO-ENVIE-FUNDOS`)."
},
"network": {
"type": "string"
},
"network_name": {
"type": "string"
},
"asset": {
"type": "string"
},
"accepted_assets": {
"type": "array",
"items": {
"type": "string"
}
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Prazo do pedido: 1 hora a partir da criação (`created_at` + `deposit_validity_hours`). Envie dentro do prazo."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"credited_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"origin": {
"type": "string",
"enum": [
"request",
"assigned_by_support"
]
},
"instructions": {
"type": "string",
"description": "Só na criação: o texto para mostrar ao usuário."
},
"sandbox": {
"type": "boolean"
}
}
}400 valor_invalido, valor_abaixo_do_minimo (min_usdt), rede_indisponivel.
409 muitos_pedidos_abertos.
401 Chave ausente ou inválida.
403 carteira_nao_liberada: a carteira não está liberada para este projeto.
503 carteira_indisponivel / pagamentos_indisponiveis: tente de novo em instantes (acao: esperar).
GET /carteira-usdt/payments
Listar pagamentos
Os 100 mais recentes. Os concluídos trazem E2E, nome, CPF parcial e o link do comprovante.
Responses
200 OK
JSON schema · 200
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"description": "Pix pago com o saldo USDT.",
"properties": {
"payment_id": {
"type": "string",
"example": "cu_8a7b6c5d4e3f2a1b0c9d"
},
"external_id": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"reservado",
"ordem_criada",
"aceita",
"sacando",
"enviado",
"revisao",
"concluido",
"falhou",
"falhou_apos_envio"
],
"description": "Finais: `concluido` (Pix pago), `falhou` (não executado; a reserva voltou ao saldo), `falhou_apos_envio` (em apuração; a reserva NÃO volta sozinha). `revisao`: em conferência — não é falha, acompanhe. Os demais são etapas em andamento."
},
"final": {
"type": "boolean",
"description": "true quando o estado não muda mais."
},
"payment_method": {
"type": "string",
"enum": [
"pix_key",
"br_code"
]
},
"brl_amount": {
"type": "string"
},
"pix_key": {
"type": [
"string",
"null"
],
"description": "Mascarada."
},
"usdt_reserved": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": ""
},
"usdt_debited": {
"type": [
"string",
"null"
]
},
"usdt_order": {
"type": [
"string",
"null"
]
},
"withdrawal_fee": {
"type": [
"string",
"null"
]
},
"cashout_id": {
"type": [
"string",
"null"
],
"description": "A ordem que pagou o Pix (GET /cash-outs/{cashout_id} tem o detalhe)."
},
"error": {
"type": [
"string",
"null"
]
},
"pix_e2e": {
"type": "string",
"description": "Só em `concluido`: o identificador E2E do Pix."
},
"recipient_name": {
"type": "string",
"description": "Só em `concluido`: nome de quem recebeu."
},
"recipient_document": {
"type": [
"string",
"null"
],
"description": "Só em `concluido`: CPF parcial (padrão do Banco Central) ou CNPJ."
},
"receipt_url": {
"type": [
"string",
"null"
],
"description": "Só em `concluido`: link público do comprovante oficial (null no teste)."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"sandbox": {
"type": "boolean"
}
}
}
}
}
}401 Chave ausente ou inválida.
403 carteira_nao_liberada: a carteira não está liberada para este projeto.
503 carteira_indisponivel / pagamentos_indisponiveis: tente de novo em instantes (acao: esperar).
POST /carteira-usdt/payments
Pagar um Pix com o saldo USDT
Reserva o USDT, paga o Pix e debita o que custou (a sobra da reserva volta). Assíncrono: responde em reservado; acompanhe por GET /carteira-usdt/payments/{payment_id} ou pelos webhooks wallet.payment_completed / wallet.payment_failed. Envie external_id para repetir com segurança: o mesmo external_id com os mesmos dados devolve o mesmo pagamento (200).
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
brl_amount | string | false | Valor que o recebedor recebe, em reais. Use OU brl_amount (com pix_key) OU br_code. |
br_code | string | false | Pix Copia e Cola (começa com 000201). O valor e o recebedor vêm do código; não envie brl_amount. |
funding_source | string | false | Opcional; só aceita crypto_usdt. |
pix_key | string | false | Chave Pix de quem recebe (obrigatória com brl_amount). |
pix_key_type | string | false | Recomendado quando a chave tem 11 dígitos (CPF ou telefone). |
quote_id | string | false | Com br_code: o quote_id da cotação (opcional). |
external_id | string | false | Seu identificador idempotente. |
Request schema
{
"type": "object",
"properties": {
"brl_amount": {
"type": "string",
"example": "50.00",
"description": "Valor que o recebedor recebe, em reais. Use OU brl_amount (com pix_key) OU br_code."
},
"br_code": {
"type": "string",
"description": "Pix Copia e Cola (começa com 000201). O valor e o recebedor vêm do código; não envie brl_amount."
},
"funding_source": {
"type": "string",
"enum": [
"crypto_usdt"
],
"description": "Opcional; só aceita crypto_usdt."
},
"pix_key": {
"type": "string",
"description": "Chave Pix de quem recebe (obrigatória com brl_amount)."
},
"pix_key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"email",
"phone",
"random"
],
"description": "Recomendado quando a chave tem 11 dígitos (CPF ou telefone)."
},
"quote_id": {
"type": "string",
"description": "Com br_code: o quote_id da cotação (opcional)."
},
"external_id": {
"type": "string",
"maxLength": 64,
"description": "Seu identificador idempotente."
}
}
}Example
{
"brl_amount": "50.00",
"pix_key": "cliente@exemplo.com",
"pix_key_type": "email",
"external_id": "pedido-123"
}Responses
201 Pagamento criado.
JSON schema · 201
{
"type": "object",
"description": "Pix pago com o saldo USDT.",
"properties": {
"payment_id": {
"type": "string",
"example": "cu_8a7b6c5d4e3f2a1b0c9d"
},
"external_id": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"reservado",
"ordem_criada",
"aceita",
"sacando",
"enviado",
"revisao",
"concluido",
"falhou",
"falhou_apos_envio"
],
"description": "Finais: `concluido` (Pix pago), `falhou` (não executado; a reserva voltou ao saldo), `falhou_apos_envio` (em apuração; a reserva NÃO volta sozinha). `revisao`: em conferência — não é falha, acompanhe. Os demais são etapas em andamento."
},
"final": {
"type": "boolean",
"description": "true quando o estado não muda mais."
},
"payment_method": {
"type": "string",
"enum": [
"pix_key",
"br_code"
]
},
"brl_amount": {
"type": "string"
},
"pix_key": {
"type": [
"string",
"null"
],
"description": "Mascarada."
},
"usdt_reserved": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": ""
},
"usdt_debited": {
"type": [
"string",
"null"
]
},
"usdt_order": {
"type": [
"string",
"null"
]
},
"withdrawal_fee": {
"type": [
"string",
"null"
]
},
"cashout_id": {
"type": [
"string",
"null"
],
"description": "A ordem que pagou o Pix (GET /cash-outs/{cashout_id} tem o detalhe)."
},
"error": {
"type": [
"string",
"null"
]
},
"pix_e2e": {
"type": "string",
"description": "Só em `concluido`: o identificador E2E do Pix."
},
"recipient_name": {
"type": "string",
"description": "Só em `concluido`: nome de quem recebeu."
},
"recipient_document": {
"type": [
"string",
"null"
],
"description": "Só em `concluido`: CPF parcial (padrão do Banco Central) ou CNPJ."
},
"receipt_url": {
"type": [
"string",
"null"
],
"description": "Só em `concluido`: link público do comprovante oficial (null no teste)."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"sandbox": {
"type": "boolean"
}
}
}200 Repetição do mesmo external_id: o pagamento já existente.
JSON schema · 200
{
"type": "object",
"description": "Pix pago com o saldo USDT.",
"properties": {
"payment_id": {
"type": "string",
"example": "cu_8a7b6c5d4e3f2a1b0c9d"
},
"external_id": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"reservado",
"ordem_criada",
"aceita",
"sacando",
"enviado",
"revisao",
"concluido",
"falhou",
"falhou_apos_envio"
],
"description": "Finais: `concluido` (Pix pago), `falhou` (não executado; a reserva voltou ao saldo), `falhou_apos_envio` (em apuração; a reserva NÃO volta sozinha). `revisao`: em conferência — não é falha, acompanhe. Os demais são etapas em andamento."
},
"final": {
"type": "boolean",
"description": "true quando o estado não muda mais."
},
"payment_method": {
"type": "string",
"enum": [
"pix_key",
"br_code"
]
},
"brl_amount": {
"type": "string"
},
"pix_key": {
"type": [
"string",
"null"
],
"description": "Mascarada."
},
"usdt_reserved": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": ""
},
"usdt_debited": {
"type": [
"string",
"null"
]
},
"usdt_order": {
"type": [
"string",
"null"
]
},
"withdrawal_fee": {
"type": [
"string",
"null"
]
},
"cashout_id": {
"type": [
"string",
"null"
],
"description": "A ordem que pagou o Pix (GET /cash-outs/{cashout_id} tem o detalhe)."
},
"error": {
"type": [
"string",
"null"
]
},
"pix_e2e": {
"type": "string",
"description": "Só em `concluido`: o identificador E2E do Pix."
},
"recipient_name": {
"type": "string",
"description": "Só em `concluido`: nome de quem recebeu."
},
"recipient_document": {
"type": [
"string",
"null"
],
"description": "Só em `concluido`: CPF parcial (padrão do Banco Central) ou CNPJ."
},
"receipt_url": {
"type": [
"string",
"null"
],
"description": "Só em `concluido`: link público do comprovante oficial (null no teste)."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"sandbox": {
"type": "boolean"
}
}
}400 valor_invalido, valor_abaixo_do_minimo, pix_key_obrigatoria, br_code_invalido, campos_conflitantes, cotacao_recusada.
409 saldo_insuficiente, external_id_divergente, cotacao_divergente.
401 Chave ausente ou inválida.
403 carteira_nao_liberada: a carteira não está liberada para este projeto.
503 carteira_indisponivel / pagamentos_indisponiveis: tente de novo em instantes (acao: esperar).
GET /carteira-usdt/payments/{payment_id}
Acompanhar um pagamento
Estado atual do Pix pago com USDT. Concluído traz E2E, nome, CPF parcial e receipt_url.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
payment_id | path | true |
Responses
200 OK
JSON schema · 200
{
"type": "object",
"description": "Pix pago com o saldo USDT.",
"properties": {
"payment_id": {
"type": "string",
"example": "cu_8a7b6c5d4e3f2a1b0c9d"
},
"external_id": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"reservado",
"ordem_criada",
"aceita",
"sacando",
"enviado",
"revisao",
"concluido",
"falhou",
"falhou_apos_envio"
],
"description": "Finais: `concluido` (Pix pago), `falhou` (não executado; a reserva voltou ao saldo), `falhou_apos_envio` (em apuração; a reserva NÃO volta sozinha). `revisao`: em conferência — não é falha, acompanhe. Os demais são etapas em andamento."
},
"final": {
"type": "boolean",
"description": "true quando o estado não muda mais."
},
"payment_method": {
"type": "string",
"enum": [
"pix_key",
"br_code"
]
},
"brl_amount": {
"type": "string"
},
"pix_key": {
"type": [
"string",
"null"
],
"description": "Mascarada."
},
"usdt_reserved": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": ""
},
"usdt_debited": {
"type": [
"string",
"null"
]
},
"usdt_order": {
"type": [
"string",
"null"
]
},
"withdrawal_fee": {
"type": [
"string",
"null"
]
},
"cashout_id": {
"type": [
"string",
"null"
],
"description": "A ordem que pagou o Pix (GET /cash-outs/{cashout_id} tem o detalhe)."
},
"error": {
"type": [
"string",
"null"
]
},
"pix_e2e": {
"type": "string",
"description": "Só em `concluido`: o identificador E2E do Pix."
},
"recipient_name": {
"type": "string",
"description": "Só em `concluido`: nome de quem recebeu."
},
"recipient_document": {
"type": [
"string",
"null"
],
"description": "Só em `concluido`: CPF parcial (padrão do Banco Central) ou CNPJ."
},
"receipt_url": {
"type": [
"string",
"null"
],
"description": "Só em `concluido`: link público do comprovante oficial (null no teste)."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"sandbox": {
"type": "boolean"
}
}
}404 nao_encontrado.
401 Chave ausente ou inválida.
403 carteira_nao_liberada: a carteira não está liberada para este projeto.
503 carteira_indisponivel / pagamentos_indisponiveis: tente de novo em instantes (acao: esperar).
POST /carteira-usdt/quote
Cotar um Pix pago com USDT
Prévia sem efeito: quanto USDT sai para pagar o Pix. Pix mínimo em min_payment_brl.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
brl_amount | string | false | Valor que o recebedor recebe, em reais. Use OU brl_amount (com pix_key) OU br_code. |
br_code | string | false | Pix Copia e Cola (começa com 000201). O valor e o recebedor vêm do código; não envie brl_amount. |
funding_source | string | false | Opcional; só aceita crypto_usdt. |
Request schema
{
"type": "object",
"properties": {
"brl_amount": {
"type": "string",
"example": "50.00",
"description": "Valor que o recebedor recebe, em reais. Use OU brl_amount (com pix_key) OU br_code."
},
"br_code": {
"type": "string",
"description": "Pix Copia e Cola (começa com 000201). O valor e o recebedor vêm do código; não envie brl_amount."
},
"funding_source": {
"type": "string",
"enum": [
"crypto_usdt"
],
"description": "Opcional; só aceita crypto_usdt."
}
}
}Example
{
"brl_amount": "50.00"
}Responses
200 OK
JSON schema · 200
{
"type": "object",
"description": "Prévia de um Pix pago com USDT. Estimativa: ao confirmar, a cotação é refeita e reservamos até 1% a mais (a sobra volta).",
"properties": {
"payment_method": {
"type": "string",
"enum": [
"pix_key",
"br_code"
]
},
"brl_amount": {
"type": "string",
"example": "50.00"
},
"usdt_order": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": "USDT convertidos para pagar o Pix."
},
"withdrawal_fee": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": "Custo de envio."
},
"usdt_total": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": "Total estimado debitado."
},
"usdt_reserved": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": "Quanto fica reservado até o Pix concluir."
},
"quote_id": {
"type": "string",
"description": "Só com br_code: envie em POST /carteira-usdt/payments para garantir que é o mesmo código."
},
"merchant_name": {
"type": [
"string",
"null"
]
},
"pix_key": {
"type": [
"string",
"null"
]
},
"pix_key_type": {
"type": [
"string",
"null"
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"note": {
"type": "string"
},
"sandbox": {
"type": "boolean"
}
}
}400 valor_invalido, valor_abaixo_do_minimo (min_brl), br_code_invalido, campos_conflitantes, cotacao_recusada, funding_source_invalido.
401 Chave ausente ou inválida.
403 carteira_nao_liberada: a carteira não está liberada para este projeto.
503 carteira_indisponivel / pagamentos_indisponiveis: tente de novo em instantes (acao: esperar).
GET /carteira-usdt/statement
Extrato da carteira
As 200 linhas mais recentes do livro, com saldo depois de cada uma.
Responses
200 OK
JSON schema · 200
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"description": "Linha do extrato. `amount` é sempre positivo; `type` dá a direção.",
"properties": {
"entry_id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"deposit",
"reserve",
"release",
"debit",
"reversal"
],
"description": "`deposit` crédito de depósito · `reserve` reserva para um Pix · `debit` Pix pago · `release` sobra ou reserva devolvida ao disponível · `reversal` depósito desfeito."
},
"amount": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": ""
},
"available_after": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": ""
},
"reserved_after": {
"type": "string",
"pattern": "^-?\\d+\\.\\d{6}$",
"description": ""
},
"reference": {
"type": "string",
"description": "`payment_id` do Pix, `deposit` ou `adjustment`."
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}401 Chave ausente ou inválida.
403 carteira_nao_liberada: a carteira não está liberada para este projeto.
503 carteira_indisponivel / pagamentos_indisponiveis: tente de novo em instantes (acao: esperar).
GET /cash-outs
Listar ordens
Parameters
| Field | In | Required | Description |
|---|---|---|---|
state | query | false | |
limit | query | false | |
external_id | query | false | Recuperacao idempotente: devolve a operacao com este external_id (0 ou 1). Unico por chave e produto, case-sensitive, retido permanentemente. |
Responses
200 Ordens da sua chave, mais recentes primeiro.
401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /cash-outs
Cotar (passo 1 de 3)
Cria cotação de cripto externa para PIX; endereço de depósito vem somente no accept. Envie amount OU brl_amount, strings decimais, e um par do GET /catalog. Leia limites por operação/chave em GET /keys/me e limites efetivos/recebedor na resposta. Mandate pode restringir a operação. Informe refund_address para controlar o destino de eventual devolução. br_code tem disponibilidade própria: pode retornar 503 br_code_indisponivel, mesmo quando preview/sandbox aceitam. Produção responde 200 na criação; sandbox pode responder 201.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
asset | string | true | Ativo vendido. Use o id EXATO do GET /catalog (ex.: "usdt"). Combine com network — o par (asset, network) precisa existir no catálogo. |
network | string | true | Rede de entrada cripto publicada em GET /catalog. Não confundir com as redes de entrega de /cashin/catalog. |
amount | string | false | Quantidade de cripto em string decimal ( |
brl_amount | string | false | Cotação REVERSA: o valor do PIX em reais, em string decimal com até 2 casas ( |
pix_key | string | true | Chave que vai receber os reais. Formatos aceitos (normalizados pela API para o formato exato do liquidante; fora disso → 400 pix_key_invalida antes de existir depósito): CPF 11 dígitos · CNPJ 14 dígitos · telefone internacional +55DDDNÚMERO (+5548996005588) · e-mail · chave aleatória em UUID (6602ede6-b1a9-4e63-9178-c6883fd0095e). (en) Key that receives the reais. Accepted formats: CPF 11 digits · CNPJ 14 digits · phone +55 + area code + number · e-mail · random key as UUID. |
pix_key_type | string | false | Opcional: deduzido do formato da chave (e-mail, CNPJ, UUID, telefone com +55). So e obrigatorio quando a chave tem 11 digitos puros, onde CPF e telefone sao indistinguiveis — nesse caso a API recusa com erro tipo_ambiguo em vez de chutar. Values: |
token_address | string | false | Endereço/mint exato. Necessário para tokens do |
external_id | string | false | Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado. |
refund_address | string | false | Carteira de retorno do cliente, compatível com a rede e confirmada por ele. Nao inferir a partir da origem on-chain. Sem carteira, o fluxo pode parar em AWAITING_REFUND_ADDRESS; consulte refund_asset, refund_network e refund_amount quando retornados. Na venda de DePix, opcional desde a 1.44.0 (antes era obrigatória); quando enviada, precisa ser um endereço Liquid válido (lq1…) do cliente, também no sandbox. |
br_code | string | false | Copia e cola de cobrança PIX com valor definido, quando o recurso estiver disponível. USDT/USDC; substitui pix_key, amount e brl_amount. Pode retornar 503 br_code_indisponivel em produção. O amount cotado inclui reserva fixa de R$ 1,00 (reserve_brl; equivalente em USDT no campo copia_e_cola_buffer_usd) que garante o PIX no valor exato do QR; a sobra fica com a Lunium como reserva de correção e não é devolvida. |
Request schema
{
"type": "object",
"required": [
"asset",
"network",
"pix_key"
],
"properties": {
"asset": {
"type": "string",
"examples": [
"USDT"
],
"description": "Ativo vendido. Use o id EXATO do GET /catalog (ex.: \"usdt\"). Combine com network — o par (asset, network) precisa existir no catálogo."
},
"network": {
"type": "string",
"description": "Rede de entrada cripto publicada em GET /catalog. Não confundir com as redes de entrega de /cashin/catalog.",
"examples": [
"polygon"
]
},
"amount": {
"type": "string",
"description": "Quantidade de cripto em string decimal (`\"50\"`), nunca float. Informe `amount` OU `brl_amount` — exatamente um.",
"examples": [
"50"
]
},
"brl_amount": {
"type": "string",
"description": "Cotação REVERSA: o valor do PIX em reais, em string decimal com até 2 casas (`\"250.00\"`). A Lunium calcula a cripto — o `amount` da resposta é o que o cliente deposita. Informe `amount` OU `brl_amount` — exatamente um. Faixa: R$ 6,00 a R$ 250.000,00 por transação, ainda limitada ao teto diário de R$ 100.000,00 do recebedor (o menor dos dois vale). (en) Reverse quote: the BRL the PIX key must receive; the response carries the exact crypto `amount` to deposit.",
"examples": [
"250.00"
]
},
"pix_key": {
"type": "string",
"description": "Chave que vai receber os reais. Formatos aceitos (normalizados pela API para o formato exato do liquidante; fora disso → 400 pix_key_invalida antes de existir depósito): CPF 11 dígitos · CNPJ 14 dígitos · telefone internacional +55DDDNÚMERO (+5548996005588) · e-mail · chave aleatória em UUID (6602ede6-b1a9-4e63-9178-c6883fd0095e).\n\n(en) Key that receives the reais. Accepted formats: CPF 11 digits · CNPJ 14 digits · phone +55 + area code + number · e-mail · random key as UUID."
},
"pix_key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"random"
],
"description": "Opcional: deduzido do formato da chave (e-mail, CNPJ, UUID, telefone com +55). So e obrigatorio quando a chave tem 11 digitos puros, onde CPF e telefone sao indistinguiveis — nesse caso a API recusa com erro tipo_ambiguo em vez de chutar."
},
"token_address": {
"type": "string",
"description": "Endereço/mint exato. Necessário para tokens do `/catalog/dex`, onde símbolos se repetem."
},
"external_id": {
"type": "string",
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
"maxLength": 64
},
"refund_address": {
"type": "string",
"description": "Carteira de retorno do cliente, compatível com a rede e confirmada por ele. Nao inferir a partir da origem on-chain. Sem carteira, o fluxo pode parar em AWAITING_REFUND_ADDRESS; consulte refund_asset, refund_network e refund_amount quando retornados. Na venda de DePix, opcional desde a 1.44.0 (antes era obrigatória); quando enviada, precisa ser um endereço Liquid válido (lq1…) do cliente, também no sandbox.",
"examples": [
"0x51e3d44172868acc60d68ca99591ce4230bc75e0"
]
},
"br_code": {
"type": "string",
"description": "Copia e cola de cobrança PIX com valor definido, quando o recurso estiver disponível. USDT/USDC; substitui pix_key, amount e brl_amount. Pode retornar 503 br_code_indisponivel em produção. O amount cotado inclui reserva fixa de R$ 1,00 (reserve_brl; equivalente em USDT no campo copia_e_cola_buffer_usd) que garante o PIX no valor exato do QR; a sobra fica com a Lunium como reserva de correção e não é devolvida.",
"examples": [
"00020126330014br.gov.bcb.pix0111498113948905204000053039865406…6304ABCD"
]
}
}
}Responses
201 Cotacao criada.
JSON schema · 201
{
"type": "object",
"properties": {
"cashout_id": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"QUOTE_CREATED",
"AWAITING_DEPOSIT",
"DEPOSIT_DETECTED",
"DEPOSIT_CONFIRMED",
"SELLING",
"SOLD",
"FORWARDING",
"PAYING_OUT",
"COMPLETED",
"MANUAL_REVIEW",
"REFUNDING_CRYPTO",
"REFUNDED",
"EXPIRED",
"FAILED",
"DELAYED",
"AWAITING_REFUND_ADDRESS",
"PROCESSING",
"REFUNDING"
],
"description": "Estado da ordem. COMPLETED confirma PIX. Etapas intermediárias variam por trilho. DELAYED pertence ao cenário de sandbox. AWAITING_REFUND_ADDRESS: a ordem precisa devolver e não tem carteira de retorno; informe-a em POST /cash-outs/{cashout_id}/refund-address (venda de cripto e, desde a 1.44.0, venda de DePix). Venda de DePix: QUOTE_CREATED → AWAITING_DEPOSIT → DEPOSIT_DETECTED → PROCESSING → COMPLETED; se o Pix não puder ser pago, REFUNDING → REFUNDED, ou AWAITING_REFUND_ADDRESS quando falta a carteira. DePix que já tinha sido repassado ao provedor só é devolvido depois que o retorno é confirmado: até lá a ordem fica em MANUAL_REVIEW, e a devolução é de no máximo o que voltou."
},
"path": {
"type": [
"string",
"null"
],
"enum": [
"FAST",
"DEX",
"CONVERT",
null
],
"description": "Trilho FAST, DEX ou CONVERT. Prazos dependem da rota, confirmações e processamento."
},
"asset": {
"type": "string",
"examples": [
"USDT"
],
"description": "Ativo vendido. Use o id EXATO do GET /catalog (ex.: \"usdt\"). Combine com network — o par (asset, network) precisa existir no catálogo."
},
"network": {
"type": "string",
"examples": [
"polygon"
],
"description": "Rede blockchain do depósito, como listada no catálogo (ex.: \"polygon\"). O endereço de depósito devolvido só vale nesta rede."
},
"amount": {
"type": "string",
"description": "Quantidade de cripto, em string decimal. Nunca float."
},
"brl_amount": {
"type": [
"string",
"null"
],
"description": "Amount in Brazilian reais (BRL) the PIX key will receive.\n\n(pt) Reais que a chave PIX vai receber."
},
"pix_key": {
"type": "string",
"description": "Chave PIX de destino que recebe os reais (CPF, CNPJ, telefone +55, e-mail ou chave aleatória). Com 11 dígitos crus envie também pix_key_type (\"cpf\" ou \"phone\") — sem isso a API recusa com erro=tipo_ambiguo em vez de adivinhar."
},
"pix_key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"random"
],
"description": "Usually omit it: the type is inferred from the key for e-mails, CNPJs, random keys and phones written with the +55 country code. Only required when the key is 11 bare digits, because a CPF and a phone number are the same length and guessing would pay the wrong person. An explicit type always wins over inference."
},
"deposit_address": {
"type": [
"string",
"null"
],
"description": "Para onde o cliente envia a cripto. Só existe depois do accept."
},
"deposit_tag": {
"type": [
"string",
"null"
],
"description": "Memo/tag que deve acompanhar o depósito quando retornado pelo aceite. Use apenas redes presentes em GET /catalog."
},
"external_id": {
"type": [
"string",
"null"
],
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
"maxLength": 64
},
"refund_address": {
"type": [
"string",
"null"
],
"description": "Carteira de retorno confirmada pelo cliente. Ausência não autoriza usar deposit_from; a ordem pode pedir endereço em AWAITING_REFUND_ADDRESS. Vale também para a venda de DePix (endereço Liquid lq1…) desde a 1.44.0."
},
"refund_tx_hash": {
"type": [
"string",
"null"
],
"description": "Hash da devolução quando concluída; não implica valor/prazo fixo de estorno para todos os casos."
},
"deposit_from": {
"type": [
"string",
"null"
],
"description": "Origem on-chain do deposito, apenas informativa. Pode ser carteira compartilhada de exchange; nunca a escolher automaticamente como destino de devolução."
},
"br_code": {
"type": [
"string",
"null"
],
"description": "Copia e cola informado na cotação (cobrança), quando houve. brl_amount é o valor do QR.\n\n(en) Copy-paste string given at quote time (charge), if any. brl_amount is the QR amount."
},
"merchant_name": {
"type": [
"string",
"null"
],
"description": "Nome do recebedor lido do QR (cobrança).\n\n(en) Receiver name read from the QR (charge)."
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Instante em que a cotação expira, ISO 8601 em UTC (ex.: 2026-09-02T14:03:00Z). Aceites após esse instante falham com erro=cotacao_expirada — recote em vez de insistir."
},
"pix_e2e": {
"type": [
"string",
"null"
],
"description": "Central Bank end-to-end identifier of the completed PIX. Anyone can verify it at GET /v1/verificar/{e2e}, no key required.\n\n(pt) Identificador oficial do PIX no Banco Central. É a prova — devolva ao seu cliente final.",
"examples": [
"E37293930202607312006361894c4a82"
]
},
"pix_paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"receipt_url": {
"type": [
"string",
"null"
],
"description": "Shareable receipt page — opens on the end customer's phone.\n\n(pt) Pagina publica compartilhavel do comprovante. Abre no celular do cliente final.",
"examples": [
"https://app.luniumpay.com/comprovante/uwscff6ASNS1oUcH2LHbvw"
]
},
"receipt_pdf_url": {
"type": [
"string",
"null"
],
"nullable": true,
"format": "uri",
"description": "Receipt as a PDF FILE: attach to a ticket, send over WhatsApp, keep for accounting. Does not depend on our page being up on the day someone checks. Carries recipient name, tax number, institution, amount, date, E2E and the verification link.\n\n(pt) Comprovante em ARQUIVO PDF. E o que se anexa em chamado, manda no WhatsApp do cliente final e guarda na contabilidade -- nao depende de a pagina estar no ar no dia da conferencia. Traz nome, documento e instituicao do recebedor, valor, data, E2E e o link de verificacao. Gerado da MESMA fonte de dados da pagina: os dois nunca divergem. Vem `null` enquanto a ordem nao chegou no estado que o preenche.",
"example": "https://app.luniumpay.com/comprovante/qigpnCTx3gM-Ge7hN27Mvw.pdf"
},
"verify_url": {
"type": [
"string",
"null"
],
"nullable": true,
"format": "uri",
"description": "Direct link to the OPEN verification (no key). Hand it to your counterparty so they can confirm the payment themselves, without trusting you or us. Never exposes PIX key, full name or tax number.\n\n(pt) Link direto da verificacao ABERTA (sem chave). Entregue ao seu contraparte para ele mesmo confirmar o pagamento, sem precisar confiar em voce nem em nos. Nao expoe chave PIX, nome completo nem documento. Vem `null` enquanto a ordem nao chegou no estado que o preenche.",
"example": "https://api.luniumpay.com/v1/verificar/E3729393020260731214021222ac6ff1"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"timeline": {
"type": "array",
"description": "Linha do tempo carimbada pelo SERVIDOR a cada transição (hora do gateway, não do seu polling): AWAITING_DEPOSIT → DEPOSIT_DETECTED → DEPOSIT_CONFIRMED → (SELLING → SOLD → FORWARDING, só na corretora) → PAYING_OUT → COMPLETED. Use para o rastreador do cliente.",
"items": {
"type": "object",
"properties": {
"state": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
}
}
}
},
"confirmations": {
"type": [
"integer",
"null"
],
"description": "Confirmações do depósito já observadas, AO VIVO. Aparece só enquanto a ordem está confirmando e não é persistido — o número muda a cada bloco. Use com confirmations_required para desenhar o progresso em vez de um \"aguardando\" sem fim."
},
"confirmations_required": {
"type": [
"integer",
"null"
],
"description": "Confirmações que a corretora exige antes de creditar o depósito desta rede."
},
"failure_reason": {
"type": [
"string",
"null"
],
"description": "Motivo de falha quando retornado, inclusive nos cenários de sandbox."
},
"sandbox": {
"type": "boolean",
"description": "True for fictitious sandbox operations."
},
"simulation": {
"type": "object",
"additionalProperties": true
}
}
}200 Cotação criada.
JSON schema · 200
{
"type": "object",
"properties": {
"cashout_id": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"QUOTE_CREATED",
"AWAITING_DEPOSIT",
"DEPOSIT_DETECTED",
"DEPOSIT_CONFIRMED",
"SELLING",
"SOLD",
"FORWARDING",
"PAYING_OUT",
"COMPLETED",
"MANUAL_REVIEW",
"REFUNDING_CRYPTO",
"REFUNDED",
"EXPIRED",
"FAILED",
"DELAYED",
"AWAITING_REFUND_ADDRESS",
"PROCESSING",
"REFUNDING"
],
"description": "Estado da ordem. COMPLETED confirma PIX. Etapas intermediárias variam por trilho. DELAYED pertence ao cenário de sandbox. AWAITING_REFUND_ADDRESS: a ordem precisa devolver e não tem carteira de retorno; informe-a em POST /cash-outs/{cashout_id}/refund-address (venda de cripto e, desde a 1.44.0, venda de DePix). Venda de DePix: QUOTE_CREATED → AWAITING_DEPOSIT → DEPOSIT_DETECTED → PROCESSING → COMPLETED; se o Pix não puder ser pago, REFUNDING → REFUNDED, ou AWAITING_REFUND_ADDRESS quando falta a carteira. DePix que já tinha sido repassado ao provedor só é devolvido depois que o retorno é confirmado: até lá a ordem fica em MANUAL_REVIEW, e a devolução é de no máximo o que voltou."
},
"path": {
"type": [
"string",
"null"
],
"enum": [
"FAST",
"DEX",
"CONVERT",
null
],
"description": "Trilho FAST, DEX ou CONVERT. Prazos dependem da rota, confirmações e processamento."
},
"asset": {
"type": "string",
"examples": [
"USDT"
],
"description": "Ativo vendido. Use o id EXATO do GET /catalog (ex.: \"usdt\"). Combine com network — o par (asset, network) precisa existir no catálogo."
},
"network": {
"type": "string",
"examples": [
"polygon"
],
"description": "Rede blockchain do depósito, como listada no catálogo (ex.: \"polygon\"). O endereço de depósito devolvido só vale nesta rede."
},
"amount": {
"type": "string",
"description": "Quantidade de cripto, em string decimal. Nunca float."
},
"brl_amount": {
"type": [
"string",
"null"
],
"description": "Amount in Brazilian reais (BRL) the PIX key will receive.\n\n(pt) Reais que a chave PIX vai receber."
},
"pix_key": {
"type": "string",
"description": "Chave PIX de destino que recebe os reais (CPF, CNPJ, telefone +55, e-mail ou chave aleatória). Com 11 dígitos crus envie também pix_key_type (\"cpf\" ou \"phone\") — sem isso a API recusa com erro=tipo_ambiguo em vez de adivinhar."
},
"pix_key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"random"
],
"description": "Usually omit it: the type is inferred from the key for e-mails, CNPJs, random keys and phones written with the +55 country code. Only required when the key is 11 bare digits, because a CPF and a phone number are the same length and guessing would pay the wrong person. An explicit type always wins over inference."
},
"deposit_address": {
"type": [
"string",
"null"
],
"description": "Para onde o cliente envia a cripto. Só existe depois do accept."
},
"deposit_tag": {
"type": [
"string",
"null"
],
"description": "Memo/tag que deve acompanhar o depósito quando retornado pelo aceite. Use apenas redes presentes em GET /catalog."
},
"external_id": {
"type": [
"string",
"null"
],
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
"maxLength": 64
},
"refund_address": {
"type": [
"string",
"null"
],
"description": "Carteira de retorno confirmada pelo cliente. Ausência não autoriza usar deposit_from; a ordem pode pedir endereço em AWAITING_REFUND_ADDRESS. Vale também para a venda de DePix (endereço Liquid lq1…) desde a 1.44.0."
},
"refund_tx_hash": {
"type": [
"string",
"null"
],
"description": "Hash da devolução quando concluída; não implica valor/prazo fixo de estorno para todos os casos."
},
"deposit_from": {
"type": [
"string",
"null"
],
"description": "Origem on-chain do deposito, apenas informativa. Pode ser carteira compartilhada de exchange; nunca a escolher automaticamente como destino de devolução."
},
"br_code": {
"type": [
"string",
"null"
],
"description": "Copia e cola informado na cotação (cobrança), quando houve. brl_amount é o valor do QR.\n\n(en) Copy-paste string given at quote time (charge), if any. brl_amount is the QR amount."
},
"merchant_name": {
"type": [
"string",
"null"
],
"description": "Nome do recebedor lido do QR (cobrança).\n\n(en) Receiver name read from the QR (charge)."
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Instante em que a cotação expira, ISO 8601 em UTC (ex.: 2026-09-02T14:03:00Z). Aceites após esse instante falham com erro=cotacao_expirada — recote em vez de insistir."
},
"pix_e2e": {
"type": [
"string",
"null"
],
"description": "Central Bank end-to-end identifier of the completed PIX. Anyone can verify it at GET /v1/verificar/{e2e}, no key required.\n\n(pt) Identificador oficial do PIX no Banco Central. É a prova — devolva ao seu cliente final.",
"examples": [
"E37293930202607312006361894c4a82"
]
},
"pix_paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"receipt_url": {
"type": [
"string",
"null"
],
"description": "Shareable receipt page — opens on the end customer's phone.\n\n(pt) Pagina publica compartilhavel do comprovante. Abre no celular do cliente final.",
"examples": [
"https://app.luniumpay.com/comprovante/uwscff6ASNS1oUcH2LHbvw"
]
},
"receipt_pdf_url": {
"type": [
"string",
"null"
],
"nullable": true,
"format": "uri",
"description": "Receipt as a PDF FILE: attach to a ticket, send over WhatsApp, keep for accounting. Does not depend on our page being up on the day someone checks. Carries recipient name, tax number, institution, amount, date, E2E and the verification link.\n\n(pt) Comprovante em ARQUIVO PDF. E o que se anexa em chamado, manda no WhatsApp do cliente final e guarda na contabilidade -- nao depende de a pagina estar no ar no dia da conferencia. Traz nome, documento e instituicao do recebedor, valor, data, E2E e o link de verificacao. Gerado da MESMA fonte de dados da pagina: os dois nunca divergem. Vem `null` enquanto a ordem nao chegou no estado que o preenche.",
"example": "https://app.luniumpay.com/comprovante/qigpnCTx3gM-Ge7hN27Mvw.pdf"
},
"verify_url": {
"type": [
"string",
"null"
],
"nullable": true,
"format": "uri",
"description": "Direct link to the OPEN verification (no key). Hand it to your counterparty so they can confirm the payment themselves, without trusting you or us. Never exposes PIX key, full name or tax number.\n\n(pt) Link direto da verificacao ABERTA (sem chave). Entregue ao seu contraparte para ele mesmo confirmar o pagamento, sem precisar confiar em voce nem em nos. Nao expoe chave PIX, nome completo nem documento. Vem `null` enquanto a ordem nao chegou no estado que o preenche.",
"example": "https://api.luniumpay.com/v1/verificar/E3729393020260731214021222ac6ff1"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"timeline": {
"type": "array",
"description": "Linha do tempo carimbada pelo SERVIDOR a cada transição (hora do gateway, não do seu polling): AWAITING_DEPOSIT → DEPOSIT_DETECTED → DEPOSIT_CONFIRMED → (SELLING → SOLD → FORWARDING, só na corretora) → PAYING_OUT → COMPLETED. Use para o rastreador do cliente.",
"items": {
"type": "object",
"properties": {
"state": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
}
}
}
},
"confirmations": {
"type": [
"integer",
"null"
],
"description": "Confirmações do depósito já observadas, AO VIVO. Aparece só enquanto a ordem está confirmando e não é persistido — o número muda a cada bloco. Use com confirmations_required para desenhar o progresso em vez de um \"aguardando\" sem fim."
},
"confirmations_required": {
"type": [
"integer",
"null"
],
"description": "Confirmações que a corretora exige antes de creditar o depósito desta rede."
},
"failure_reason": {
"type": [
"string",
"null"
],
"description": "Motivo de falha quando retornado, inclusive nos cenários de sandbox."
},
"sandbox": {
"type": "boolean",
"description": "True for fictitious sandbox operations."
},
"simulation": {
"type": "object",
"additionalProperties": true
}
}
}400 Pedido inválido ou rede indisponível.
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}409 `external_id` já usado com outros parâmetros.
422 Parametros semanticamente invalidos.
JSON schema · 422
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /cash-outs/preview
Prévia de cotação (não cria ordem)
Prévia de conversão nos dois sentidos (amount OU brl_amount), sem ordem e sem pix_key. Não reserva saldo, limite ou endereço. A criação/aceite aplicam gates adicionais, incluindo disponibilidade de br_code, limite do recebedor e mandate. Sucesso da prévia não garante que a ordem será aceita.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
asset | string | true | Ativo vendido. Use o id EXATO do GET /catalog (ex.: "usdt"). Combine com network — o par (asset, network) precisa existir no catálogo. |
network | string | true | Rede de entrada cripto publicada em GET /catalog. Não confundir com as redes de entrega de /cashin/catalog. |
amount | string | false | Quantidade de cripto em string decimal ( |
brl_amount | string | false | Cotação REVERSA: o valor do PIX em reais, em string decimal com até 2 casas ( |
token_address | string | false | Endereço/mint exato. Necessário para tokens do |
br_code | string | false | PIX copia e cola de uma COBRANÇA com valor. A prévia decodifica o QR e devolve amount, brl_amount (= valor do QR), merchant_name e a chave mascarada — sem criar ordem. Com br_code não envie amount nem brl_amount. Mesmas regras de POST /cash-outs: USDT ou USDC, qualquer rede do catálogo. |
Request schema
{
"type": "object",
"required": [
"asset",
"network"
],
"properties": {
"asset": {
"type": "string",
"examples": [
"USDT"
],
"description": "Ativo vendido. Use o id EXATO do GET /catalog (ex.: \"usdt\"). Combine com network — o par (asset, network) precisa existir no catálogo."
},
"network": {
"type": "string",
"description": "Rede de entrada cripto publicada em GET /catalog. Não confundir com as redes de entrega de /cashin/catalog.",
"examples": [
"polygon"
]
},
"amount": {
"type": "string",
"description": "Quantidade de cripto em string decimal (`\"50\"`), nunca float. Informe `amount` OU `brl_amount` — exatamente um.",
"examples": [
"50"
]
},
"brl_amount": {
"type": "string",
"description": "Cotação REVERSA: o valor do PIX em reais, em string decimal com até 2 casas (`\"250.00\"`). A Lunium calcula a cripto — o `amount` da resposta é o que o cliente deposita. Informe `amount` OU `brl_amount` — exatamente um. Faixa: R$ 6,00 a R$ 250.000,00 por transação, ainda limitada ao teto diário de R$ 100.000,00 do recebedor (o menor dos dois vale). (en) Reverse quote: the BRL the PIX key must receive; the response carries the exact crypto `amount` to deposit.",
"examples": [
"250.00"
]
},
"token_address": {
"type": "string",
"description": "Endereço/mint exato. Necessário para tokens do `/catalog/dex`, onde símbolos se repetem."
},
"br_code": {
"type": "string",
"description": "PIX copia e cola de uma COBRANÇA com valor. A prévia decodifica o QR e devolve amount, brl_amount (= valor do QR), merchant_name e a chave mascarada — sem criar ordem. Com br_code não envie amount nem brl_amount. Mesmas regras de POST /cash-outs: USDT ou USDC, qualquer rede do catálogo."
}
}
}Responses
200 Prévia calculada (nenhuma ordem criada).
JSON schema · 200
{
"type": "object",
"properties": {
"preview": {
"type": "boolean",
"const": true
},
"asset": {
"type": "string"
},
"network": {
"type": "string"
},
"path": {
"type": "string",
"enum": [
"FAST",
"DEX",
"CONVERT"
],
"description": "Trilho que a venda usaria."
},
"amount": {
"type": "string",
"description": "Cripto a enviar (decimal em string)."
},
"brl_amount": {
"type": "string",
"description": "Valor do PIX em reais."
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Validade que a cotação teria."
},
"merchant_name": {
"type": [
"string",
"null"
],
"description": "Só com br_code: nome do recebedor da cobrança."
},
"pix_key": {
"type": [
"string",
"null"
],
"description": "Só com br_code: chave do recebedor, mascarada."
},
"pix_key_type": {
"type": [
"string",
"null"
]
}
},
"required": [
"preview",
"asset",
"network",
"amount",
"brl_amount"
]
}400 Pedido inválido ou rede indisponível.
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}422 Parametros semanticamente invalidos.
JSON schema · 422
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /cash-outs/{cashout_id}
Acompanhar (passo 3 de 3)
Prefira o webhook. Se consultar, use uma vez a cada 10–15 s: uma vez por segundo consome sozinho o limite de 60 requisições por minuto da chave.
Comprovante oficial. Em COMPLETED a ordem traz pix_e2e, receipt_url, receipt_pdf_url e verify_url: o mesmo comprovante do PIX em quatro formas, que também chega pelo webhook (cashout.completed e cashout.receipt_ready), pelo painel do parceiro e pelo Telegram. O que ele contém e como entregar ao seu cliente.
Quando state for COMPLETED, os campos pix_e2e, pix_paid_at e receipt_url estarão preenchidos.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
cashout_id | path | true |
Responses
200 Estado atual.
JSON schema · 200
{
"type": "object",
"properties": {
"cashout_id": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"QUOTE_CREATED",
"AWAITING_DEPOSIT",
"DEPOSIT_DETECTED",
"DEPOSIT_CONFIRMED",
"SELLING",
"SOLD",
"FORWARDING",
"PAYING_OUT",
"COMPLETED",
"MANUAL_REVIEW",
"REFUNDING_CRYPTO",
"REFUNDED",
"EXPIRED",
"FAILED",
"DELAYED",
"AWAITING_REFUND_ADDRESS",
"PROCESSING",
"REFUNDING"
],
"description": "Estado da ordem. COMPLETED confirma PIX. Etapas intermediárias variam por trilho. DELAYED pertence ao cenário de sandbox. AWAITING_REFUND_ADDRESS: a ordem precisa devolver e não tem carteira de retorno; informe-a em POST /cash-outs/{cashout_id}/refund-address (venda de cripto e, desde a 1.44.0, venda de DePix). Venda de DePix: QUOTE_CREATED → AWAITING_DEPOSIT → DEPOSIT_DETECTED → PROCESSING → COMPLETED; se o Pix não puder ser pago, REFUNDING → REFUNDED, ou AWAITING_REFUND_ADDRESS quando falta a carteira. DePix que já tinha sido repassado ao provedor só é devolvido depois que o retorno é confirmado: até lá a ordem fica em MANUAL_REVIEW, e a devolução é de no máximo o que voltou."
},
"path": {
"type": [
"string",
"null"
],
"enum": [
"FAST",
"DEX",
"CONVERT",
null
],
"description": "Trilho FAST, DEX ou CONVERT. Prazos dependem da rota, confirmações e processamento."
},
"asset": {
"type": "string",
"examples": [
"USDT"
],
"description": "Ativo vendido. Use o id EXATO do GET /catalog (ex.: \"usdt\"). Combine com network — o par (asset, network) precisa existir no catálogo."
},
"network": {
"type": "string",
"examples": [
"polygon"
],
"description": "Rede blockchain do depósito, como listada no catálogo (ex.: \"polygon\"). O endereço de depósito devolvido só vale nesta rede."
},
"amount": {
"type": "string",
"description": "Quantidade de cripto, em string decimal. Nunca float."
},
"brl_amount": {
"type": [
"string",
"null"
],
"description": "Amount in Brazilian reais (BRL) the PIX key will receive.\n\n(pt) Reais que a chave PIX vai receber."
},
"pix_key": {
"type": "string",
"description": "Chave PIX de destino que recebe os reais (CPF, CNPJ, telefone +55, e-mail ou chave aleatória). Com 11 dígitos crus envie também pix_key_type (\"cpf\" ou \"phone\") — sem isso a API recusa com erro=tipo_ambiguo em vez de adivinhar."
},
"pix_key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"random"
],
"description": "Usually omit it: the type is inferred from the key for e-mails, CNPJs, random keys and phones written with the +55 country code. Only required when the key is 11 bare digits, because a CPF and a phone number are the same length and guessing would pay the wrong person. An explicit type always wins over inference."
},
"deposit_address": {
"type": [
"string",
"null"
],
"description": "Para onde o cliente envia a cripto. Só existe depois do accept."
},
"deposit_tag": {
"type": [
"string",
"null"
],
"description": "Memo/tag que deve acompanhar o depósito quando retornado pelo aceite. Use apenas redes presentes em GET /catalog."
},
"external_id": {
"type": [
"string",
"null"
],
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
"maxLength": 64
},
"refund_address": {
"type": [
"string",
"null"
],
"description": "Carteira de retorno confirmada pelo cliente. Ausência não autoriza usar deposit_from; a ordem pode pedir endereço em AWAITING_REFUND_ADDRESS. Vale também para a venda de DePix (endereço Liquid lq1…) desde a 1.44.0."
},
"refund_tx_hash": {
"type": [
"string",
"null"
],
"description": "Hash da devolução quando concluída; não implica valor/prazo fixo de estorno para todos os casos."
},
"deposit_from": {
"type": [
"string",
"null"
],
"description": "Origem on-chain do deposito, apenas informativa. Pode ser carteira compartilhada de exchange; nunca a escolher automaticamente como destino de devolução."
},
"br_code": {
"type": [
"string",
"null"
],
"description": "Copia e cola informado na cotação (cobrança), quando houve. brl_amount é o valor do QR.\n\n(en) Copy-paste string given at quote time (charge), if any. brl_amount is the QR amount."
},
"merchant_name": {
"type": [
"string",
"null"
],
"description": "Nome do recebedor lido do QR (cobrança).\n\n(en) Receiver name read from the QR (charge)."
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Instante em que a cotação expira, ISO 8601 em UTC (ex.: 2026-09-02T14:03:00Z). Aceites após esse instante falham com erro=cotacao_expirada — recote em vez de insistir."
},
"pix_e2e": {
"type": [
"string",
"null"
],
"description": "Central Bank end-to-end identifier of the completed PIX. Anyone can verify it at GET /v1/verificar/{e2e}, no key required.\n\n(pt) Identificador oficial do PIX no Banco Central. É a prova — devolva ao seu cliente final.",
"examples": [
"E37293930202607312006361894c4a82"
]
},
"pix_paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"receipt_url": {
"type": [
"string",
"null"
],
"description": "Shareable receipt page — opens on the end customer's phone.\n\n(pt) Pagina publica compartilhavel do comprovante. Abre no celular do cliente final.",
"examples": [
"https://app.luniumpay.com/comprovante/uwscff6ASNS1oUcH2LHbvw"
]
},
"receipt_pdf_url": {
"type": [
"string",
"null"
],
"nullable": true,
"format": "uri",
"description": "Receipt as a PDF FILE: attach to a ticket, send over WhatsApp, keep for accounting. Does not depend on our page being up on the day someone checks. Carries recipient name, tax number, institution, amount, date, E2E and the verification link.\n\n(pt) Comprovante em ARQUIVO PDF. E o que se anexa em chamado, manda no WhatsApp do cliente final e guarda na contabilidade -- nao depende de a pagina estar no ar no dia da conferencia. Traz nome, documento e instituicao do recebedor, valor, data, E2E e o link de verificacao. Gerado da MESMA fonte de dados da pagina: os dois nunca divergem. Vem `null` enquanto a ordem nao chegou no estado que o preenche.",
"example": "https://app.luniumpay.com/comprovante/qigpnCTx3gM-Ge7hN27Mvw.pdf"
},
"verify_url": {
"type": [
"string",
"null"
],
"nullable": true,
"format": "uri",
"description": "Direct link to the OPEN verification (no key). Hand it to your counterparty so they can confirm the payment themselves, without trusting you or us. Never exposes PIX key, full name or tax number.\n\n(pt) Link direto da verificacao ABERTA (sem chave). Entregue ao seu contraparte para ele mesmo confirmar o pagamento, sem precisar confiar em voce nem em nos. Nao expoe chave PIX, nome completo nem documento. Vem `null` enquanto a ordem nao chegou no estado que o preenche.",
"example": "https://api.luniumpay.com/v1/verificar/E3729393020260731214021222ac6ff1"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"timeline": {
"type": "array",
"description": "Linha do tempo carimbada pelo SERVIDOR a cada transição (hora do gateway, não do seu polling): AWAITING_DEPOSIT → DEPOSIT_DETECTED → DEPOSIT_CONFIRMED → (SELLING → SOLD → FORWARDING, só na corretora) → PAYING_OUT → COMPLETED. Use para o rastreador do cliente.",
"items": {
"type": "object",
"properties": {
"state": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
}
}
}
},
"confirmations": {
"type": [
"integer",
"null"
],
"description": "Confirmações do depósito já observadas, AO VIVO. Aparece só enquanto a ordem está confirmando e não é persistido — o número muda a cada bloco. Use com confirmations_required para desenhar o progresso em vez de um \"aguardando\" sem fim."
},
"confirmations_required": {
"type": [
"integer",
"null"
],
"description": "Confirmações que a corretora exige antes de creditar o depósito desta rede."
},
"failure_reason": {
"type": [
"string",
"null"
],
"description": "Motivo de falha quando retornado, inclusive nos cenários de sandbox."
},
"sandbox": {
"type": "boolean",
"description": "True for fictitious sandbox operations."
},
"simulation": {
"type": "object",
"additionalProperties": true
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /cash-outs/{cashout_id}/accept
Aceitar e receber o endereço (passo 2 de 3)
Trava a cotação e devolve deposit_address. Envie exatamente a quantidade cotada.
Se a rede exigir memo/tag, ele vem em deposit_tag — depósito sem o memo se perde.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
cashout_id | path | true |
Responses
200 Endereço de depósito.
JSON schema · 200
{
"type": "object",
"properties": {
"cashout_id": {
"type": "string",
"format": "uuid"
},
"state": {
"type": "string",
"enum": [
"QUOTE_CREATED",
"AWAITING_DEPOSIT",
"DEPOSIT_DETECTED",
"DEPOSIT_CONFIRMED",
"SELLING",
"SOLD",
"FORWARDING",
"PAYING_OUT",
"COMPLETED",
"MANUAL_REVIEW",
"REFUNDING_CRYPTO",
"REFUNDED",
"EXPIRED",
"FAILED",
"DELAYED",
"AWAITING_REFUND_ADDRESS",
"PROCESSING",
"REFUNDING"
],
"description": "Estado da ordem. COMPLETED confirma PIX. Etapas intermediárias variam por trilho. DELAYED pertence ao cenário de sandbox. AWAITING_REFUND_ADDRESS: a ordem precisa devolver e não tem carteira de retorno; informe-a em POST /cash-outs/{cashout_id}/refund-address (venda de cripto e, desde a 1.44.0, venda de DePix). Venda de DePix: QUOTE_CREATED → AWAITING_DEPOSIT → DEPOSIT_DETECTED → PROCESSING → COMPLETED; se o Pix não puder ser pago, REFUNDING → REFUNDED, ou AWAITING_REFUND_ADDRESS quando falta a carteira. DePix que já tinha sido repassado ao provedor só é devolvido depois que o retorno é confirmado: até lá a ordem fica em MANUAL_REVIEW, e a devolução é de no máximo o que voltou."
},
"path": {
"type": [
"string",
"null"
],
"enum": [
"FAST",
"DEX",
"CONVERT",
null
],
"description": "Trilho FAST, DEX ou CONVERT. Prazos dependem da rota, confirmações e processamento."
},
"asset": {
"type": "string",
"examples": [
"USDT"
],
"description": "Ativo vendido. Use o id EXATO do GET /catalog (ex.: \"usdt\"). Combine com network — o par (asset, network) precisa existir no catálogo."
},
"network": {
"type": "string",
"examples": [
"polygon"
],
"description": "Rede blockchain do depósito, como listada no catálogo (ex.: \"polygon\"). O endereço de depósito devolvido só vale nesta rede."
},
"amount": {
"type": "string",
"description": "Quantidade de cripto, em string decimal. Nunca float."
},
"brl_amount": {
"type": [
"string",
"null"
],
"description": "Amount in Brazilian reais (BRL) the PIX key will receive.\n\n(pt) Reais que a chave PIX vai receber."
},
"pix_key": {
"type": "string",
"description": "Chave PIX de destino que recebe os reais (CPF, CNPJ, telefone +55, e-mail ou chave aleatória). Com 11 dígitos crus envie também pix_key_type (\"cpf\" ou \"phone\") — sem isso a API recusa com erro=tipo_ambiguo em vez de adivinhar."
},
"pix_key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"random"
],
"description": "Usually omit it: the type is inferred from the key for e-mails, CNPJs, random keys and phones written with the +55 country code. Only required when the key is 11 bare digits, because a CPF and a phone number are the same length and guessing would pay the wrong person. An explicit type always wins over inference."
},
"deposit_address": {
"type": [
"string",
"null"
],
"description": "Para onde o cliente envia a cripto. Só existe depois do accept."
},
"deposit_tag": {
"type": [
"string",
"null"
],
"description": "Memo/tag que deve acompanhar o depósito quando retornado pelo aceite. Use apenas redes presentes em GET /catalog."
},
"external_id": {
"type": [
"string",
"null"
],
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
"maxLength": 64
},
"refund_address": {
"type": [
"string",
"null"
],
"description": "Carteira de retorno confirmada pelo cliente. Ausência não autoriza usar deposit_from; a ordem pode pedir endereço em AWAITING_REFUND_ADDRESS. Vale também para a venda de DePix (endereço Liquid lq1…) desde a 1.44.0."
},
"refund_tx_hash": {
"type": [
"string",
"null"
],
"description": "Hash da devolução quando concluída; não implica valor/prazo fixo de estorno para todos os casos."
},
"deposit_from": {
"type": [
"string",
"null"
],
"description": "Origem on-chain do deposito, apenas informativa. Pode ser carteira compartilhada de exchange; nunca a escolher automaticamente como destino de devolução."
},
"br_code": {
"type": [
"string",
"null"
],
"description": "Copia e cola informado na cotação (cobrança), quando houve. brl_amount é o valor do QR.\n\n(en) Copy-paste string given at quote time (charge), if any. brl_amount is the QR amount."
},
"merchant_name": {
"type": [
"string",
"null"
],
"description": "Nome do recebedor lido do QR (cobrança).\n\n(en) Receiver name read from the QR (charge)."
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Instante em que a cotação expira, ISO 8601 em UTC (ex.: 2026-09-02T14:03:00Z). Aceites após esse instante falham com erro=cotacao_expirada — recote em vez de insistir."
},
"pix_e2e": {
"type": [
"string",
"null"
],
"description": "Central Bank end-to-end identifier of the completed PIX. Anyone can verify it at GET /v1/verificar/{e2e}, no key required.\n\n(pt) Identificador oficial do PIX no Banco Central. É a prova — devolva ao seu cliente final.",
"examples": [
"E37293930202607312006361894c4a82"
]
},
"pix_paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"receipt_url": {
"type": [
"string",
"null"
],
"description": "Shareable receipt page — opens on the end customer's phone.\n\n(pt) Pagina publica compartilhavel do comprovante. Abre no celular do cliente final.",
"examples": [
"https://app.luniumpay.com/comprovante/uwscff6ASNS1oUcH2LHbvw"
]
},
"receipt_pdf_url": {
"type": [
"string",
"null"
],
"nullable": true,
"format": "uri",
"description": "Receipt as a PDF FILE: attach to a ticket, send over WhatsApp, keep for accounting. Does not depend on our page being up on the day someone checks. Carries recipient name, tax number, institution, amount, date, E2E and the verification link.\n\n(pt) Comprovante em ARQUIVO PDF. E o que se anexa em chamado, manda no WhatsApp do cliente final e guarda na contabilidade -- nao depende de a pagina estar no ar no dia da conferencia. Traz nome, documento e instituicao do recebedor, valor, data, E2E e o link de verificacao. Gerado da MESMA fonte de dados da pagina: os dois nunca divergem. Vem `null` enquanto a ordem nao chegou no estado que o preenche.",
"example": "https://app.luniumpay.com/comprovante/qigpnCTx3gM-Ge7hN27Mvw.pdf"
},
"verify_url": {
"type": [
"string",
"null"
],
"nullable": true,
"format": "uri",
"description": "Direct link to the OPEN verification (no key). Hand it to your counterparty so they can confirm the payment themselves, without trusting you or us. Never exposes PIX key, full name or tax number.\n\n(pt) Link direto da verificacao ABERTA (sem chave). Entregue ao seu contraparte para ele mesmo confirmar o pagamento, sem precisar confiar em voce nem em nos. Nao expoe chave PIX, nome completo nem documento. Vem `null` enquanto a ordem nao chegou no estado que o preenche.",
"example": "https://api.luniumpay.com/v1/verificar/E3729393020260731214021222ac6ff1"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"timeline": {
"type": "array",
"description": "Linha do tempo carimbada pelo SERVIDOR a cada transição (hora do gateway, não do seu polling): AWAITING_DEPOSIT → DEPOSIT_DETECTED → DEPOSIT_CONFIRMED → (SELLING → SOLD → FORWARDING, só na corretora) → PAYING_OUT → COMPLETED. Use para o rastreador do cliente.",
"items": {
"type": "object",
"properties": {
"state": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
}
}
}
},
"confirmations": {
"type": [
"integer",
"null"
],
"description": "Confirmações do depósito já observadas, AO VIVO. Aparece só enquanto a ordem está confirmando e não é persistido — o número muda a cada bloco. Use com confirmations_required para desenhar o progresso em vez de um \"aguardando\" sem fim."
},
"confirmations_required": {
"type": [
"integer",
"null"
],
"description": "Confirmações que a corretora exige antes de creditar o depósito desta rede."
},
"failure_reason": {
"type": [
"string",
"null"
],
"description": "Motivo de falha quando retornado, inclusive nos cenários de sandbox."
},
"sandbox": {
"type": "boolean",
"description": "True for fictitious sandbox operations."
},
"simulation": {
"type": "object",
"additionalProperties": true
}
}
}404 Ordem não encontrada.
422 Cotação expirada ou já aceita.
401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /cash-outs/{cashout_id}/refund-address
Informar a carteira confirmada para devolução pendente
Use quando a ordem estiver em AWAITING_REFUND_ADDRESS (refund_address_required: true, webhook cashout.awaiting_refund_address): a venda precisou ser devolvida e a ordem não tinha carteira de retorno. Envie a carteira do SEU cliente na rede da devolução (refund_network e refund_asset da ordem). A Lunium nunca devolve para a origem on-chain do depósito (deposit_from), e a carteira registrada não é trocada.
Venda de DePix (asset DEPIX, network liquid), desde a 1.44.0: informe um endereço Liquid (lq1…) do cliente. Repetir o mesmo endereço responde 200 com a ordem; outro endereço responde 409 refund_address_imutavel; endereço da própria Lunium (o de depósito desta ou de outra venda, ou carteira da casa) é recusado com 400 refund_address_invalida. Se o DePix estava inteiro com a Lunium (ou o retorno do provedor já foi confirmado), a ordem vai para REFUNDING (webhook cashout.refunding) e a devolução é enviada automaticamente, no valor de refund_amount: REFUNDED com refund_tx_hash (webhook cashout.refunded). Se o DePix já tinha sido repassado ao provedor e o retorno ainda não foi confirmado, a ordem vai para MANUAL_REVIEW (webhook cashout.under_review): a devolução só acontece depois dessa confirmação, e é de no máximo o que voltou. A carteira só é pedida quando a venda falha: fora de AWAITING_REFUND_ADDRESS, ordem sem carteira responde 409 devolucao_indisponivel.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
cashout_id | path | true |
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
refund_address | string | true | Endereço confirmado pelo cliente na rede da devolução retornada pela ordem. Nunca inferir deposit_from. Venda de DePix: endereço Liquid (lq1…) do cliente. |
Request schema
{
"type": "object",
"required": [
"refund_address"
],
"properties": {
"refund_address": {
"type": "string",
"description": "Endereço confirmado pelo cliente na rede da devolução retornada pela ordem. Nunca inferir deposit_from. Venda de DePix: endereço Liquid (lq1…) do cliente."
}
}
}Responses
200 Ordem atualizada; acompanhar até REFUNDED e refund_tx_hash. Venda de DePix: o state volta como REFUNDING (DePix com a Lunium) ou MANUAL_REVIEW (DePix com o provedor, aguardando o retorno).
JSON schema · 200
{
"type": "object",
"properties": {
"cashout_id": {
"type": "string",
"description": "Identificador opaco da ordem. Em produção pode ser UUID; em sandbox começa com sbx_. Preserve sem converter."
},
"state": {
"type": "string",
"enum": [
"QUOTE_CREATED",
"AWAITING_DEPOSIT",
"DEPOSIT_DETECTED",
"DEPOSIT_CONFIRMED",
"SELLING",
"SOLD",
"FORWARDING",
"PAYING_OUT",
"COMPLETED",
"MANUAL_REVIEW",
"REFUNDING_CRYPTO",
"REFUNDED",
"EXPIRED",
"FAILED",
"DELAYED",
"AWAITING_REFUND_ADDRESS",
"PROCESSING",
"REFUNDING"
],
"description": "Estado da ordem. COMPLETED confirma PIX. Etapas intermediárias variam por trilho. DELAYED pertence ao cenário de sandbox. AWAITING_REFUND_ADDRESS: a ordem precisa devolver e não tem carteira de retorno; informe-a em POST /cash-outs/{cashout_id}/refund-address (venda de cripto e, desde a 1.44.0, venda de DePix). Venda de DePix: QUOTE_CREATED → AWAITING_DEPOSIT → DEPOSIT_DETECTED → PROCESSING → COMPLETED; se o Pix não puder ser pago, REFUNDING → REFUNDED, ou AWAITING_REFUND_ADDRESS quando falta a carteira. DePix que já tinha sido repassado ao provedor só é devolvido depois que o retorno é confirmado: até lá a ordem fica em MANUAL_REVIEW, e a devolução é de no máximo o que voltou."
},
"path": {
"type": [
"string",
"null"
],
"enum": [
"FAST",
"DEX",
"CONVERT",
null,
"depix_liquid"
],
"description": "Trilho FAST, DEX ou CONVERT. Prazos dependem da rota, confirmações e processamento. DePix/Liquid usa depix_liquid."
},
"asset": {
"type": "string",
"examples": [
"USDT"
],
"description": "Ativo vendido. Use o id EXATO do GET /catalog (ex.: \"usdt\"). Combine com network — o par (asset, network) precisa existir no catálogo."
},
"network": {
"type": "string",
"examples": [
"polygon"
],
"description": "Rede blockchain do depósito, como listada no catálogo (ex.: \"polygon\"). O endereço de depósito devolvido só vale nesta rede."
},
"amount": {
"type": "string",
"description": "Quantidade de cripto, em string decimal. Nunca float."
},
"brl_amount": {
"type": [
"string",
"null"
],
"description": "Amount in Brazilian reais (BRL) the PIX key will receive.\n\n(pt) Reais que a chave PIX vai receber."
},
"pix_key": {
"type": "string",
"description": "Chave PIX mascarada do destinatario na resposta. A entrada aceita a chave completa; não compare literalmente a resposta mascarada com a entrada."
},
"pix_key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"random"
],
"description": "Usually omit it: the type is inferred from the key for e-mails, CNPJs, random keys and phones written with the +55 country code. Only required when the key is 11 bare digits, because a CPF and a phone number are the same length and guessing would pay the wrong person. An explicit type always wins over inference."
},
"deposit_address": {
"type": [
"string",
"null"
],
"description": "Para onde o cliente envia a cripto. Só existe depois do accept. Em sandbox DePix é um marcador não pagável SANDBOX:LIQUID:NAO_ENVIAR:...; não envie moedas."
},
"deposit_tag": {
"type": [
"string",
"null"
],
"description": "Memo/tag que deve acompanhar o depósito quando retornado pelo aceite. Use apenas redes presentes em GET /catalog."
},
"external_id": {
"type": [
"string",
"null"
],
"description": "Identificador persistente por intenção, até 64 caracteres. Repetir o mesmo corpo reutiliza a ordem. Mudanca de rede, ativo, token, destino, tipo PIX, valor ou carteira de retorno e conflito 409; recuperar a original antes de decidir nova operação. Ordens antigas sem identidade verificavel podem exigir recuperacao por cashout_id/external_id.",
"maxLength": 64
},
"refund_address": {
"type": [
"string",
"null"
],
"description": "Carteira de retorno confirmada pelo cliente. Ausência não autoriza usar deposit_from; a ordem pode pedir endereço em AWAITING_REFUND_ADDRESS. Vale também para a venda de DePix (endereço Liquid lq1…) desde a 1.44.0."
},
"refund_tx_hash": {
"type": [
"string",
"null"
],
"description": "Hash da devolução quando concluída; não implica valor/prazo fixo de estorno para todos os casos."
},
"deposit_from": {
"type": [
"string",
"null"
],
"description": "Origem on-chain do deposito, apenas informativa. Pode ser carteira compartilhada de exchange; nunca a escolher automaticamente como destino de devolução."
},
"br_code": {
"type": [
"string",
"null"
],
"description": "Copia e cola informado na cotação (cobrança), quando houve. brl_amount é o valor do QR.\n\n(en) Copy-paste string given at quote time (charge), if any. brl_amount is the QR amount."
},
"merchant_name": {
"type": [
"string",
"null"
],
"description": "Nome do recebedor lido do QR (cobrança).\n\n(en) Receiver name read from the QR (charge)."
},
"copia_e_cola_buffer_usd": {
"type": [
"string",
"null"
],
"description": "Só em cobrança (br_code): reserva de R$ 1 convertida em USDT já incluído em amount. Garante o PIX no valor exato do QR; o que não for usado fica com a Lunium como reserva de correção e não é devolvido.\n\n(en) Charges (br_code) only: BRL 1 reserve converted to USDT already included in amount. Guarantees the PIX at the exact QR amount; any unused part is kept by Lunium as a correction reserve and is not refunded.",
"examples": [
"1.00"
]
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Instante em que a cotação expira, ISO 8601 em UTC (ex.: 2026-09-02T14:03:00Z). Aceites após esse instante falham com erro=cotacao_expirada — recote em vez de insistir."
},
"pix_e2e": {
"type": [
"string",
"null"
],
"description": "Central Bank end-to-end identifier of the completed PIX. Anyone can verify it at GET /v1/verificar/{e2e}, no key required.\n\n(pt) Identificador oficial do PIX no Banco Central. É a prova — devolva ao seu cliente final. Em sandbox é fictício, com ISPB 00000000; não comprova pagamento bancário.",
"examples": [
"E37293930202607312006361894c4a82"
]
},
"pix_paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"receipt_url": {
"type": [
"string",
"null"
],
"description": "Página compartilhavel do comprovante, quando pronta. Pode permanecer null no evento cashout.completed; cashout.receipt_ready e a consulta da mesma ordem entregam o link depois.",
"examples": [
"https://app.luniumpay.com/comprovante/uwscff6ASNS1oUcH2LHbvw"
]
},
"receipt_pdf_url": {
"type": [
"string",
"null"
],
"nullable": true,
"format": "uri",
"description": "Receipt as a PDF FILE: attach to a ticket, send over WhatsApp, keep for accounting. Does not depend on our page being up on the day someone checks. Carries recipient name, tax number, institution, amount, date, E2E and the verification link.\n\n(pt) Comprovante em ARQUIVO PDF. E o que se anexa em chamado, manda no WhatsApp do cliente final e guarda na contabilidade -- nao depende de a pagina estar no ar no dia da conferencia. Traz nome, documento e instituicao do recebedor, valor, data, E2E e o link de verificacao. Gerado da MESMA fonte de dados da pagina: os dois nunca divergem. Vem `null` enquanto a ordem nao chegou no estado que o preenche.\n\nComprovante oficial — o que contém e por onde chega (API, webhook, painel do parceiro, Telegram): https://docs.luniumpay.com/manual#comprovante",
"example": "https://app.luniumpay.com/comprovante/qigpnCTx3gM-Ge7hN27Mvw.pdf"
},
"verify_url": {
"type": [
"string",
"null"
],
"nullable": true,
"format": "uri",
"description": "Direct link to the OPEN verification (no key). Hand it to your counterparty so they can confirm the payment themselves, without trusting you or us. Never exposes PIX key, full name or tax number.\n\n(pt) Link direto da verificacao ABERTA (sem chave). Entregue ao seu contraparte para ele mesmo confirmar o pagamento, sem precisar confiar em voce nem em nos. Nao expoe chave PIX, nome completo nem documento. Vem `null` enquanto a ordem nao chegou no estado que o preenche.",
"example": "https://api.luniumpay.com/v1/verificar/E3729393020260731214021222ac6ff1"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"timeline": {
"type": "array",
"description": "Linha do tempo carimbada pelo SERVIDOR a cada transição (hora do gateway, não do seu polling): AWAITING_DEPOSIT → DEPOSIT_DETECTED → DEPOSIT_CONFIRMED → (SELLING → SOLD → FORWARDING, só na corretora) → PAYING_OUT → COMPLETED. Use para o rastreador do cliente.",
"items": {
"type": "object",
"properties": {
"state": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
}
}
}
},
"confirmations": {
"type": [
"integer",
"null"
],
"description": "Confirmações do depósito já observadas, AO VIVO. Aparece só enquanto a ordem está confirmando e não é persistido — o número muda a cada bloco. Use com confirmations_required para desenhar o progresso em vez de um \"aguardando\" sem fim."
},
"confirmations_required": {
"type": [
"integer",
"null"
],
"description": "Confirmações que a corretora exige antes de creditar o depósito desta rede."
},
"failure_reason": {
"type": [
"string",
"null"
],
"description": "Motivo de falha quando retornado, inclusive nos cenários de sandbox."
},
"sandbox": {
"type": "boolean",
"description": "True for fictitious sandbox operations."
},
"simulation": {
"type": "object",
"additionalProperties": true
},
"partner_fee_bps": {
"type": "integer",
"nullable": true,
"description": "Sub fee do parceiro congelada nesta venda (bps); null em ordem anterior ao campo ou venda DePix."
},
"partner_fee_brl_cents": {
"type": "integer",
"nullable": true,
"description": "Fatia do parceiro em centavos, fechada na confirmacao do PIX; e o valor creditado no razao de comissao."
},
"refund_address_required": {
"type": "boolean",
"description": "true em AWAITING_REFUND_ADDRESS: consultar os dados da devolução e informar carteira confirmada pelo cliente em POST /cash-outs/{cashout_id}/refund-address."
},
"refund_amount": {
"type": [
"string",
"null"
],
"description": "Quantidade efetiva a devolver, quando apurada; não presumir quantidade original. Venda de DePix: com o DePix inteiro com a Lunium, refund_amount, refund_asset (DEPIX) e refund_network (liquid) já vêm preenchidos em AWAITING_REFUND_ADDRESS. Se o DePix já tinha sido repassado ao provedor, esses campos ficam null em MANUAL_REVIEW até o retorno ser confirmado; depois, refund_amount é de no máximo o que voltou (mais a parte que não chegou a ser repassada, até o valor da ordem)."
},
"refund_asset": {
"type": [
"string",
"null"
],
"description": "Ativo efetivo da devolução; pode diferir do ativo depositado."
},
"refund_network": {
"type": [
"string",
"null"
],
"description": "Rede efetiva da devolução; usar carteira compatível confirmada pelo cliente."
},
"provider_return_txid": {
"type": [
"string",
"null"
],
"description": "Referência da devolução do parceiro para a Lunium; não e prova de estorno ao cliente."
},
"fee_bps": {
"type": "integer",
"description": "Percentual da venda de DePix em pontos-base."
},
"fee_fixed_cents": {
"type": "integer",
"description": "Parcela fixa da venda de DePix, em centavos."
},
"fee_total_cents": {
"type": "integer",
"description": "Taxa total, em centavos; disponível na cotação DePix e na ordem simulada."
},
"net_cents": {
"type": "integer",
"description": "PIX líquido, em centavos; disponível na cotação DePix e na ordem simulada."
}
}
}400 Endereço ausente, inválido para a rede ou da própria Lunium (refund_address_invalida; na venda de cripto, a recusa feita no processamento da devolução pode vir com outro código, com o motivo em detail).
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_invalido",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"carteira_indisponivel",
"carteira_nao_liberada",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"chave_obrigatoria",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_divergente",
"cotacao_expirada",
"cotacao_indisponivel",
"cotacao_recusada",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"devolucao_indisponivel",
"documento_invalido",
"em_processamento",
"email_invalido",
"email_obrigatorio",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"funding_source_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"muitos_pedidos_abertos",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"outcome_invalido",
"pagador_bloqueado",
"pagador_recusado_pelo_provedor",
"pagamentos_indisponiveis",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_imutavel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_invalido",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"carteira_indisponivel",
"carteira_nao_liberada",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"chave_obrigatoria",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_divergente",
"cotacao_expirada",
"cotacao_indisponivel",
"cotacao_recusada",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"devolucao_indisponivel",
"documento_invalido",
"em_processamento",
"email_invalido",
"email_obrigatorio",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"funding_source_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"muitos_pedidos_abertos",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"outcome_invalido",
"pagador_bloqueado",
"pagador_recusado_pelo_provedor",
"pagamentos_indisponiveis",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_imutavel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}404 Ordem inexistente ou de outra chave.
JSON schema · 404
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_invalido",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"carteira_indisponivel",
"carteira_nao_liberada",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"chave_obrigatoria",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_divergente",
"cotacao_expirada",
"cotacao_indisponivel",
"cotacao_recusada",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"devolucao_indisponivel",
"documento_invalido",
"em_processamento",
"email_invalido",
"email_obrigatorio",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"funding_source_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"muitos_pedidos_abertos",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"outcome_invalido",
"pagador_bloqueado",
"pagador_recusado_pelo_provedor",
"pagamentos_indisponiveis",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_imutavel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}409 Estado incompatível ou carteira já registrada. Venda de DePix: refund_address_imutavel (acao parar) quando a ordem já tem outra carteira; devolucao_indisponivel (acao esperar) quando a ordem não está aguardando carteira — ela só é pedida quando a venda falha. Venda de cripto: o motivo vem em detail.
JSON schema · 409
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_invalido",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"carteira_indisponivel",
"carteira_nao_liberada",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"chave_obrigatoria",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_divergente",
"cotacao_expirada",
"cotacao_indisponivel",
"cotacao_recusada",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"devolucao_indisponivel",
"documento_invalido",
"em_processamento",
"email_invalido",
"email_obrigatorio",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"funding_source_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"muitos_pedidos_abertos",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"outcome_invalido",
"pagador_bloqueado",
"pagador_recusado_pelo_provedor",
"pagamentos_indisponiveis",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_imutavel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /cashin/catalog
Catálogo do cash-in (o que entregamos ao receber PIX)
Catálogo de entrega cripto, usado em cash-in direto e saque da custódia. Ofereça apenas itens entregavel=true de instant/convert; instant pode estar vazio. Leia memoRequired, withdrawFee, withdrawMin e estimativas por rota. O mínimo em BRL depende da cotação em POST /cashin/preview. No saque da custódia exclua Liquid/DePix. stale=true indica catálogo em cache.
Responses
200 Catálogo de compra.
JSON schema · 200
{
"type": "object",
"description": "Catálogo do cash-in (compra): o que entregamos ao receber um PIX.",
"properties": {
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"instant": {
"type": "array",
"description": "Rotas do trilho da casa; pode vir vazio conforme configuração. Não presuma presença ou prazo fixo.",
"items": {
"type": "object",
"properties": {
"asset": {
"type": "string"
},
"network": {
"type": "string"
},
"eta": {
"type": "string"
},
"entregavel": {
"type": "boolean"
}
}
}
},
"convert": {
"type": "array",
"description": "Via corretora: uma linha por (ativo, rede).",
"items": {
"type": "object",
"properties": {
"asset": {
"type": "string"
},
"network": {
"type": "string"
},
"etaSeconds": {
"type": "integer"
},
"eta": {
"type": "string"
},
"fastest": {
"type": "boolean"
},
"withdrawFee": {
"type": "string"
},
"withdrawMin": {
"type": "string"
},
"withdrawMax": {
"type": "string"
},
"minBuyAmount": {
"type": "string",
"description": "Quantidade mínima A COMPRAR, em unidades do ativo, para cobrir withdrawMin + withdrawFee na rota de corretora. Não é necessariamente o valor líquido entregue. Consulte min_brl_cents em POST /cashin/preview com a própria chave; taxas e câmbio alteram o piso em reais."
},
"precision": {
"type": "integer"
},
"memoRequired": {
"type": "boolean",
"description": "Rede coletiva: payout_tag obrigatório."
},
"entregavel": {
"type": "boolean"
}
}
}
},
"dropped": {
"type": "array",
"description": "Pares fora, com motivo (ex.: sem_par_usdt).",
"items": {
"type": "object",
"properties": {
"asset": {
"type": "string"
},
"network": {
"type": "string"
},
"motivo": {
"type": "string"
}
}
}
},
"totals": {
"type": "object",
"additionalProperties": true
},
"stale": {
"type": "boolean",
"description": "true se catálogo foi servido do cache de contingência."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /cashin/charge
Gerar cobrança PIX para custódia BRL ou entrega de cripto
Gera PIX para custódia BRL (destino=saldo, sem carteira) ou entrega direta de cripto (destino=cripto, padrão). Informe o documento de quem pagará. Consulte GET /cashin/limits e as condições da chave. Limites, taxas e provedor determinam o mínimo efetivo; a criação revalida. Retenção pode ocorrer no provedor (held_hours/delay_until) ou localmente (hold_hours/liberar_em). PIX paid não significa entrega/crédito concluído: acompanhe settlement_status e o extrato. Sandbox cria QR nao pagavel; confirme com POST /sandbox/cashin/{cashin_id}/pay. Nao ha transacao bancaria.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
amount_cents | integer | true | Valor da cobrança em CENTAVOS de real, inteiro (ex.: 15000 = R$ 150,00). Consulte GET /cashin/limits antes de criar; ele publica as faixas sem retenção e com retenção vigentes para o pagador. |
chain | string | false | Rede da rota de entrega. Use o network do catálogo neste campo chain. Default: |
asset | string | false | Ativo da rota entregável em GET /cashin/catalog; não limitado a stablecoins. Default: |
payout_address | string | false | Carteira por cobrança para destino=cripto; se omitida, pode usar settlement_address da chave. Omitir para destino=saldo. Endereço deve corresponder à rede escolhida. |
payer_tax_number | string | true | CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, somente números. Identifica o pagador e alimenta os limites e retenções anti-fraude publicados por GET /cashin/limits. |
external_id | string | false | Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado. |
destino | string | false | saldo credita custódia BRL líquida das taxas, sem carteira. cripto (padrão) entrega na carteira informada ou configurada. Consulte taxas/carência em GET /saldo e retenção na cobrança/status. Values: Default: |
customer_ref | string | false | Optional sub-account of the balance (your end customer id). With |
allow_hold | boolean | false | false recusa quando a régua do pagador exige retenção. Não remove outras retenções/bloqueios da chave. true ou omitido permite a retenção aplicável. Leia held_hours E hold_hours/liberar_em. Default: |
payout_tag | string | false | Memo/tag do destino. OBRIGATORIO nas redes coletivas — XRP, XLM, TON, ATOM, HBAR, ALGO, EOS, KAVA, LUNA — onde a carteira de destino e compartilhada e o memo e quem identifica o dono. Sem ele a API responde 400 |
payer_name | string | false | Nome do pagador, quando informado. |
sandbox_scenario | string | false | Only for a sandbox key. GET /sandbox provides the scenario matrix by flow. Omit in production. All prices, payments and withdrawals remain fictitious. Values: |
Request schema
{
"type": "object",
"required": [
"amount_cents",
"payer_tax_number"
],
"properties": {
"amount_cents": {
"type": "integer",
"description": "Valor da cobrança em CENTAVOS de real, inteiro (ex.: 15000 = R$ 150,00). Consulte GET /cashin/limits antes de criar; ele publica as faixas sem retenção e com retenção vigentes para o pagador.",
"examples": [
25000
]
},
"chain": {
"type": "string",
"default": "polygon",
"description": "Rede da rota de entrega. Use o network do catálogo neste campo chain."
},
"asset": {
"type": "string",
"default": "usdt",
"description": "Ativo da rota entregável em GET /cashin/catalog; não limitado a stablecoins."
},
"payout_address": {
"type": "string",
"description": "Carteira por cobrança para destino=cripto; se omitida, pode usar settlement_address da chave. Omitir para destino=saldo. Endereço deve corresponder à rede escolhida."
},
"payer_tax_number": {
"type": "string",
"description": "CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, somente números. Identifica o pagador e alimenta os limites e retenções anti-fraude publicados por GET /cashin/limits."
},
"external_id": {
"type": "string",
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
"maxLength": 64
},
"destino": {
"type": "string",
"enum": [
"cripto",
"saldo"
],
"default": "cripto",
"description": "saldo credita custódia BRL líquida das taxas, sem carteira. cripto (padrão) entrega na carteira informada ou configurada. Consulte taxas/carência em GET /saldo e retenção na cobrança/status."
},
"customer_ref": {
"type": "string",
"maxLength": 80,
"description": "Optional sub-account of the balance (your end customer id). With `destino: \"saldo\"`, the credit lands on this sub-account; GET /saldo?customer_ref= reads it and POST /payouts with the same `customer_ref` spends it. Omit to use the key's main balance."
},
"allow_hold": {
"type": "boolean",
"default": true,
"description": "false recusa quando a régua do pagador exige retenção. Não remove outras retenções/bloqueios da chave. true ou omitido permite a retenção aplicável. Leia held_hours E hold_hours/liberar_em."
},
"payout_tag": {
"type": "string",
"maxLength": 120,
"description": "Memo/tag do destino. OBRIGATORIO nas redes coletivas — XRP, XLM, TON, ATOM, HBAR, ALGO, EOS, KAVA, LUNA — onde a carteira de destino e compartilhada e o memo e quem identifica o dono. Sem ele a API responde 400 `memo_obrigatorio` antes de criar qualquer cobranca. Em XRP e a destination tag: inteiro de 0 a 4294967295. Aliases aceitos: `memo`, `tag`, `destination_tag`. O catalogo marca essas rotas com `memoRequired: true`. Aliases aceitos: memo, tag, destination_tag."
},
"payer_name": {
"type": "string",
"description": "Nome do pagador, quando informado."
},
"sandbox_scenario": {
"type": "string",
"enum": [
"success",
"delayed",
"held",
"expired",
"refunded",
"failed",
"payer_mismatch",
"settlement_failed",
"settlement_uncertain",
"route_unavailable",
"provider_unavailable"
],
"description": "Only for a sandbox key. GET /sandbox provides the scenario matrix by flow. Omit in production. All prices, payments and withdrawals remain fictitious."
}
}
}Responses
200 Cobrança criada: qr_copypaste é o PIX a mostrar.
JSON schema · 200
{
"type": "object",
"description": "Resposta de criação da cobrança, com QR. Para status/lista/webhook veja StatusCobranca.",
"properties": {
"cashin_id": {
"type": "string",
"description": "Identificador da cobrança (ci_…)."
},
"status": {
"type": "string",
"description": "Estado do PIX. paid não comprova sozinho crédito/entrega; leia settlement_status.",
"enum": [
"pending",
"delayed",
"under_review",
"paid",
"expired",
"refunded",
"failed"
]
},
"amount_cents": {
"type": "integer",
"description": "Valor do PIX em centavos."
},
"destino": {
"type": "string",
"description": "cripto (entrega on-chain) ou saldo (credita a custódia BRL da chave, usável em POST /payouts e POST /saldo/sacar-cripto).",
"enum": [
"cripto",
"saldo"
]
},
"fonte": {
"type": "string",
"enum": [
"pix",
"saldo"
],
"description": "Fonte do valor na criação: PIX ou saque do saldo."
},
"customer_ref": {
"type": [
"string",
"null"
],
"description": "Sua referência do cliente final (subconta no saldo).",
"maxLength": 80
},
"payout_address": {
"type": [
"string",
"null"
],
"description": "Carteira que recebe a cripto (destino=cripto)."
},
"payout_tag": {
"type": [
"string",
"null"
],
"description": "Memo/tag da carteira de destino em redes coletivas (destino=cripto)."
},
"chain": {
"type": "string",
"description": "Rede de entrega (id de GET /cashin/catalog)."
},
"asset": {
"type": "string",
"description": "Ativo entregue (usdt, usdc, btc, …)."
},
"lunium_fee_bps": {
"type": "integer",
"description": "Taxa percentual congelada na cobrança, em bps."
},
"lunium_fee_fixed_cents": {
"type": "integer",
"description": "Parcela fixa congelada na cobrança, em centavos."
},
"partner_fee_bps": {
"type": "integer",
"description": "Sub fee congelada na cobrança."
},
"qr_copypaste": {
"type": [
"string",
"null"
],
"description": "PIX copia e cola na criação; null no saque custodial."
},
"qr_image_url": {
"type": [
"string",
"null"
],
"description": "Imagem do QR (PNG) — só na resposta da criação."
},
"external_id": {
"type": [
"string",
"null"
],
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
"maxLength": 64
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Validade da própria cobrança; leia este timestamp, inclusive para validade estendida pelo bot."
},
"delay_until": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Instante de liberação informado para retenção do provedor, quando disponível."
},
"liberar_em": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Quando o crédito no saldo sai da carência. null quando já entra disponível (padrão desde 16/09/2026)."
},
"hold_hours": {
"type": "integer",
"description": "Retenção local da cobrança em horas. Não é alias de held_hours nem da carência geral do saldo."
},
"held_hours": {
"type": "integer",
"description": "Retenção solicitada ao provedor. Pode ser zero enquanto existe retenção local (hold_hours/liberar_em)."
},
"held": {
"type": "boolean",
"description": "true quando held_hours > 0. Isoladamente não revela retenção local."
},
"sandbox": {
"type": "boolean",
"description": "True for fictitious sandbox operations."
},
"simulation": {
"type": "object",
"additionalProperties": true
},
"sandbox_payment": {
"type": "object",
"properties": {
"method": {
"const": "POST"
},
"path": {
"type": "string"
}
}
},
"timeline": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
}403 Limite do pagador excedido.
JSON schema · 403
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}400 Parametros invalidos, valor fora dos limites, ou cash-in indisponivel para esta chave. · `valor_abaixo_do_minimo` — a moeda/rede escolhida tem mínimo próprio; a resposta traz `minimo_estimado_cents` (a partir de quanto dá). Conferido ANTES de tocar no dinheiro. · `memo_obrigatorio` — a rede exige memo/tag e ele nao veio (ou veio invalido).
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}502 provedor_indisponivel (acao: repetir) — o provedor de liquidação PIX não gerou o QR. NENHUMA cobrança foi criada: repita a MESMA chamada (mesmo external_id) em alguns minutos. Dois erros distintos usam este status e exigem acoes opostas: `provedor_indisponivel` (acao `repetir` ou `esperar`) e instabilidade do liquidante, passa sozinha; `config_provedor` (acao `falar_com_suporte`) e uma configuracao invalida do nosso lado — a chave PIX, a credencial ou a conta do provedor — e NAO se resolve esperando nem repetindo. Nenhuma cobranca e criada em nenhum dos dois casos.
JSON schema · 502
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}503 catalogo_indisponivel / cotacao_indisponivel — corretora sem cotação neste instante; repita.
JSON schema · 503
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}409 external_id divergente.
GET /cashin/charges
Lista/recupera cobrancas de cash-in desta chave
Parameters
| Field | In | Required | Description |
|---|---|---|---|
external_id | query | false | Recuperacao idempotente: devolve a operacao com este external_id (0 ou 1). Unico por chave e produto, case-sensitive, retido permanentemente. |
status | query | false | |
start | query | false | |
end | query | false | |
limit | query | false |
Responses
200 Lista (mais recentes primeiro).
JSON schema · 200
{
"type": "object",
"properties": {
"charges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Cobranca"
}
}
}
}401 X-API-Key ausente/invalida.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}403 Listagem exige X-API-Key (nao publico).
JSON schema · 403
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /cashin/events
Feed de eventos da sua chave (operação)
Últimos eventos da sua chave, do mais recente para o mais antigo: cobranças, vendas, saques e entregas de webhook. É o mesmo feed do painel de monitoramento — serve para uma tela de operação sem guardar estado. Aceita X-API-Key ou o token de monitor da chave.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
limit | query | false | Quantos eventos devolver (padrão 60). |
Responses
200 Eventos recentes.
JSON schema · 200
{
"type": "object",
"properties": {
"projeto": {
"type": "string",
"description": "Nome da chave."
},
"agora": {
"type": "string",
"format": "date-time",
"description": "Hora do servidor, para o relógio da tela não depender do cliente."
},
"eventos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ts": {
"type": "string",
"format": "date-time"
},
"fluxo": {
"type": "string",
"description": "cashin · cashout · payout · webhook"
},
"provedor": {
"type": "string"
},
"ref": {
"type": "string",
"description": "Identificador da operação."
},
"valor": {
"type": "string"
},
"estado": {
"type": "string"
},
"detalhe": {
"type": [
"string",
"null"
]
},
"tx": {
"type": [
"string",
"null"
]
}
}
}
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /cashin/limits
How much this taxpayer can pay right now
Consulta orientativa de limites por CPF/CNPJ, uso e faixas sem retenção/retida. A criação revalida a operação e as condições da chave, inclusive custódia sem carência. max_amount_cents não substitui mínimos de taxa, rota/provedor ou gates contratuais. Retenção pode ocorrer no provedor ou localmente; confira held_hours, hold_hours e liberar_em na cobrança. Não fixe a régua no cliente.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
payer_tax | query | true | CPF (11 digits) or CNPJ (14 digits), digits only. |
Responses
200 Current ladder state
JSON schema · 200
{
"type": "object",
"properties": {
"payer_tax": {
"type": "string",
"description": "Masked back to you, never in full."
},
"stage": {
"enum": [
"first_transaction",
"first_24h",
"mature",
"disabled",
"desconhecido"
]
},
"max_amount_cents": {
"type": "integer",
"description": "Faixa máxima orientativa do documento, incluindo eventual retenção; criação revalida chave, mínimos e disponibilidade."
},
"used_cents": {
"type": "integer"
},
"available_cents": {
"type": "integer",
"description": "What still clears without a hold at the current stage. Alias: instant_available_cents."
},
"limit_cents": {
"type": "integer"
},
"next_stage": {
"type": [
"object",
"null"
],
"description": "When the ceiling rises and to what."
},
"instant_available_cents": {
"type": "integer",
"description": "Same as available_cents — what clears without a hold, spelled out."
},
"held_qr": {
"type": [
"object",
"null"
],
"description": "Condições da faixa com retenção quando aplicável. O provedor pode reter o valor ou a cobrança pode aplicar retenção local. Confira a resposta de criação/status.",
"properties": {
"stage": {
"type": "string",
"enum": [
"held_qr"
]
},
"max_amount_cents": {
"type": "integer"
},
"used_cents": {
"type": "integer",
"description": "Paid + in-flight in the last 24h."
},
"available_cents": {
"type": "integer"
},
"hold_hours": {
"type": "integer"
},
"explicacao": {
"type": "string"
}
}
}
}
}400 Malformed document
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /cashin/preview
Cotação de cash-in — não cria nada
Estimativa de conversão PIX/BRL para uma rota de entrega. Não cria QR nem fixa o câmbio até o pagamento. Leia min_brl_cents e os campos retornados pela rota. Não é uma prévia completa de saque custodial: a taxa de saque da casa é adicional.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
amount_cents | integer | true | Valor BRL em centavos inteiros. Mínimo efetivo depende da chave, taxas e rota. Consulte GET /keys/me e min_brl_cents/limits retornados; não fixe o mínimo do exemplo. |
asset | string | false | Ativo da rota entregável em GET /cashin/catalog; não limitado a stablecoins. Default: |
chain | string | false | Rede da rota de entrega. Use o network do catálogo neste campo chain. Default: |
Request schema
{
"type": "object",
"required": [
"amount_cents"
],
"properties": {
"amount_cents": {
"type": "integer",
"minimum": 1,
"description": "Valor BRL em centavos inteiros. Mínimo efetivo depende da chave, taxas e rota. Consulte GET /keys/me e min_brl_cents/limits retornados; não fixe o mínimo do exemplo."
},
"asset": {
"type": "string",
"default": "usdt",
"description": "Ativo da rota entregável em GET /cashin/catalog; não limitado a stablecoins."
},
"chain": {
"type": "string",
"default": "polygon",
"description": "Rede da rota de entrega. Use o network do catálogo neste campo chain."
}
}
}Responses
200 Cotação com a taxa da chave aplicada.
JSON schema · 200
{
"type": "object",
"properties": {
"asset": {
"type": "string",
"description": "Stablecoin da liquidação, ecoada do pedido."
},
"amount_cents": {
"type": "integer",
"description": "Valor da cobrança em centavos, ecoado do pedido."
},
"admin_fee_bps": {
"type": "integer"
},
"admin_fee_fixed_cents": {
"type": "integer"
},
"fee_total_cents": {
"type": "integer",
"description": "TUDO que saiu do bruto: taxa fixa + % da Lunium + sub fee do parceiro. Invariante: fee_total_cents + net_cents == amount_cents. Para saber de quem é cada parte, leia lunium_fee_cents e partner_fee_cents."
},
"net_cents": {
"type": "integer",
"description": "Valor líquido convertido em cripto para o usuário final, já descontada a sub fee do parceiro (se houver)."
},
"brl_per_usdt": {
"type": "string",
"description": "Cotação arredondada p/ leitura — o valor entregue usa a cotação cheia."
},
"usdt_amount": {
"type": "string",
"description": "Quantidade líquida entregue. Fonte de verdade."
},
"partner_fee_bps": {
"type": "integer",
"description": "Sub fee do parceiro aplicada nesta cotação (bps). 0 = não usa."
},
"lunium_fee_cents": {
"type": "integer",
"description": "Parte da Lunium (fixa + %). Sem sub fee, é igual a fee_total_cents."
},
"partner_fee_cents": {
"type": "integer",
"description": "Parte do parceiro (sub fee), creditada na comissão quando a cripto for entregue. Resíduo de um único floor: a parte da Lunium não muda com a sub fee."
}
}
}400 Valor fora dos limites da chave ou parâmetros inválidos.
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /cashin/{cashin_id}/status
State of a PIX charge
Consulta estado do PIX e do crédito/entrega separadamente. paid não significa sozinho cripto entregue ou saldo disponível. settlement_status=sent conclui o crédito/entrega; em custódia confira disponível/bloqueado no saldo. delayed representa retenção pelo provedor; paid com liberar_em pode estar sob retenção local. Não peça novo pagamento porque a entrega ainda não concluiu. Prefira webhook; polling deve respeitar o rate limit da chave.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
cashin_id | path | true |
Responses
200 Estado atual com linha do tempo carimbada pelo servidor.
JSON schema · 200
{
"type": "object",
"description": "Estado da cobrança; GET pode acrescentar trilho, timeline e tempos_tipicos. Lista e webhook usam o objeto-base.",
"properties": {
"cashin_id": {
"type": "string",
"description": "Identificador da cobrança (ci_…)."
},
"status": {
"type": "string",
"description": "Estado do PIX. paid não comprova sozinho crédito/entrega; leia settlement_status.",
"enum": [
"pending",
"delayed",
"under_review",
"paid",
"expired",
"refunded",
"failed"
]
},
"settlement_status": {
"type": [
"string",
"null"
],
"description": "Estado do crédito/entrega: sent concluiu; incerto exige conciliação. PIX pago e entrega são estados distintos.",
"enum": [
"pending",
"sending",
"entregando",
"sent",
"incerto",
"failed",
null
]
},
"amount_cents": {
"type": "integer",
"description": "Valor do PIX em centavos."
},
"depix_received_cents": {
"type": [
"integer",
"null"
],
"description": "Valor recebido do liquidante antes da dedução das taxas de depósito da chave; não é o crédito líquido de custódia."
},
"usdt_amount": {
"type": [
"string",
"null"
],
"description": "Campo legado de quantidade retornado pela liquidação; interprete junto de asset e dos campos específicos da rota."
},
"settlement_tx_hash": {
"type": [
"string",
"null"
],
"description": "Hash on-chain da entrega (ou id interno quando a entrega é pela corretora)."
},
"settlement_tx_url": {
"type": [
"string",
"null"
],
"description": "Link do explorador para o hash acima, quando existe."
},
"payout_address": {
"type": [
"string",
"null"
],
"description": "Carteira que recebe a cripto (destino=cripto)."
},
"payout_tag": {
"type": [
"string",
"null"
],
"description": "Memo/tag da carteira de destino em redes coletivas (destino=cripto)."
},
"chain": {
"type": "string",
"description": "Rede de entrega (id de GET /cashin/catalog)."
},
"asset": {
"type": "string",
"description": "Ativo entregue (usdt, usdc, btc, …)."
},
"payer_tax_number": {
"type": "string",
"description": "CPF/CNPJ do pagador — quem deve pagar o QR. PIX de outro documento é devolvido (refund_reason PAYER_MISMATCH)."
},
"external_id": {
"type": [
"string",
"null"
],
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
"maxLength": 64
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Validade da própria cobrança; leia este timestamp, inclusive para validade estendida pelo bot."
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"settled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"destino": {
"type": "string",
"description": "cripto (entrega on-chain) ou saldo (credita a custódia BRL da chave, usável em POST /payouts e POST /saldo/sacar-cripto).",
"enum": [
"cripto",
"saldo"
]
},
"held_hours": {
"type": "integer",
"description": "Retenção solicitada ao provedor. Pode ser zero enquanto existe retenção local (hold_hours/liberar_em)."
},
"held": {
"type": "boolean",
"description": "true quando held_hours > 0. Isoladamente não revela retenção local."
},
"delay_until": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Instante de liberação informado para retenção do provedor, quando disponível."
},
"liberar_em": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Quando o crédito no saldo sai da carência. null quando já entra disponível (padrão desde 16/09/2026)."
},
"e2e": {
"type": [
"string",
"null"
],
"description": "EndToEndId do PIX recebido (Banco Central)."
},
"payer_name": {
"type": [
"string",
"null"
],
"description": "Nome do pagador quando informado ou identificado pelo banco."
},
"customer_ref": {
"type": [
"string",
"null"
],
"description": "Sua referência do cliente final (subconta no saldo).",
"maxLength": 80
},
"refund_reason": {
"type": [
"string",
"null"
],
"description": "Motivo da devolução quando status=refunded (ex.: PAYER_MISMATCH = pagou outro documento; TEST_AMOUNT = valor de teste; PROVIDER_REJECTED)."
},
"refund_reason_detail": {
"type": [
"string",
"null"
],
"description": "Explicação legível do motivo da devolução."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"trilho": {
"type": "string",
"description": "Trilho desta operação: casa, corretora, saldo ou liquid. Não é promessa de prazo."
},
"timeline": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"tempos_tipicos": {
"type": "object",
"description": "Mediana medida (segundos) de cada etapa, por trilho — para mostrar ao cliente quanto costuma demorar.",
"additionalProperties": true
},
"sandbox": {
"type": "boolean",
"description": "True for fictitious sandbox operations."
},
"simulation": {
"type": "object",
"additionalProperties": true
}
}
}404 Not found
JSON schema · 404
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /catalog
Ativos, redes e limites que liquidam agora
Catálogo de entrada cripto para cash-out. Use os pares retornados agora e seus mínimos, máximos e estimativas; não mantenha lista fixa de redes. fast, convert e dex descrevem trilhos distintos. A disponibilidade é diferente do catálogo de entrega /cashin/catalog. Se houver deposit_tag no aceite, ele deve acompanhar o depósito. stale=true indica contingência.
Responses
200 Catálogo vivo.
JSON schema · 200
{
"type": "object",
"description": "Catálogo do cash-out (venda).",
"properties": {
"updatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"fast": {
"type": "array",
"description": "Pares disponíveis no trilho FAST. O tempo de depósito/PIX depende da operação; não é um SLA fixo.",
"items": {
"type": "object",
"properties": {
"asset": {
"type": "string"
},
"network": {
"type": "string"
}
}
}
},
"dex": {
"type": "object",
"description": "Tokens long-tail por DEX: chains e nota.",
"additionalProperties": true
},
"convert": {
"type": "array",
"description": "Via corretora: uma entrada por ativo com as redes aceitas. Inclui solana e tron (06/09/2026) e as redes de endereço compartilhado (XRP, XLM, ATOM, HBAR, KAVA, HIVE, STEEM, IOST) — nelas o aceite devolve deposit_tag.",
"items": {
"type": "object",
"properties": {
"asset": {
"type": "string"
},
"networks": {
"type": "array",
"items": {
"type": "string"
}
},
"min": {
"type": "string",
"description": "Mínimo em unidades DESTE ativo, aplicável às redes listadas no item. Não aplicar os 6 USDT/USDC a BTC, ETH ou outros ativos. Também vale o piso em BRL da operação."
},
"max": {
"type": "string"
},
"precision": {
"type": "integer"
},
"deposit_eta": {
"type": "array",
"description": "Quanto o cliente espera DEPOIS de mandar a cripto, por rede — é o prazo que uma tela de VENDA deve mostrar. Vem das confirmações que a corretora exige antes de creditar o depósito (não confundir com o prazo do nosso saque, que vale para a compra). Ordenado da rede mais rápida para a mais lenta.",
"items": {
"type": "object",
"properties": {
"network": {
"type": "string"
},
"confirmations": {
"type": "integer",
"description": "Confirmações exigidas pela corretora. Ex.: 1.000 na Base, 5.000 na Arbitrum, 61 na BSC."
},
"eta_seconds": {
"type": "integer",
"description": "Estimativa em segundos = confirmações × tempo de bloco da rede, arredondado para cima."
},
"eta": {
"type": "string",
"description": "O mesmo prazo em texto curto, ex.: \"cerca de 34 min\"."
}
},
"required": [
"network",
"confirmations",
"eta_seconds",
"eta"
]
}
}
}
}
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /catalog/dex
Tokens long-tail negociáveis por DEX
Lista os tokens da whitelist do relay para uma chain do DEX. Use o address daqui como token_address em POST /cash-outs — símbolos se repetem entre tokens diferentes, o endereço não. Rede sem liquidação é recusada com 400.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
chain | query | true | Chain do DEX. Hoje só |
q | query | false | Filtro por símbolo ou parte do endereço. |
Responses
200 Tokens da whitelist.
JSON schema · 200
{
"type": "array",
"items": {
"type": "object",
"properties": {
"symbol": {
"type": "string",
"description": "Símbolo do token — NÃO é único, use o address."
},
"address": {
"type": "string",
"description": "Endereço do contrato: é o `token_address` da cotação."
},
"decimals": {
"type": "integer"
}
},
"required": [
"symbol",
"address",
"decimals"
]
}
}400 Erro.
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /comissao
Saldo da sub fee (comissão do parceiro)
Quanto a sua sub fee já acumulou. Credita quando a COMPRA (PIX → cripto) ou o depósito em saldo é ENTREGUE — nunca antes, para não pagar comissão sobre dinheiro que pode voltar. Venda (cripto → PIX) credita quando o PIX é pago (partner_cashout_fee_bps), e a saída da custódia credita quando o saque conclui (partner_saque_fee_bps). Venda por QR copia e cola não carrega sub fee. Base: valor recebido menos a taxa fixa da Lunium. min_saque_cents é US$ 10 pela cotação de agora.
Responses
200 Saldo, política e minimo de saque
JSON schema · 200
{
"type": "object",
"properties": {
"disponivel_cents": {
"type": "integer"
},
"creditado_cents": {
"type": "integer"
},
"estornado_cents": {
"type": "integer"
},
"sacado_cents": {
"type": "integer"
},
"operacoes": {
"type": "integer"
},
"ultimo_credito_em": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"moeda": {
"type": "string"
},
"sandbox": {
"type": "boolean"
},
"min_saque_cents": {
"type": [
"integer",
"null"
],
"description": "US$ 10 convertidos pela cotação de AGORA. null = sem cotação no momento (o saque recusa)."
},
"pode_sacar_agora": {
"type": "boolean"
},
"ultimo_saque_em": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"proximo_saque_em": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"politica": {
"type": "object"
}
},
"required": [
"disponivel_cents",
"creditado_cents",
"sacado_cents",
"operacoes",
"moeda",
"sandbox",
"pode_sacar_agora",
"politica"
]
}401 Sem chave
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /comissao/extrato
Extrato da comissão
Parameters
| Field | In | Required | Description |
|---|---|---|---|
limit | query | false | |
before | query | false | id do último item da página anterior |
Responses
200 Lançamentos, do mais recente para o mais antigo
JSON schema · 200
{
"type": "object",
"properties": {
"itens": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ComissaoEvento"
}
},
"has_more": {
"type": "boolean"
},
"next_before": {
"type": [
"string",
"null"
]
}
}
}401 Sem chave
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /comissao/sacar
Sacar a comissão em cripto
Saque MANUAL da comissão, em cripto, na rede e moeda que você escolher (qualquer rota viva de GET /cashin/catalog). Sem taxa: a sub fee já foi paga pelo usuário final na própria operação. Mínimo US$ 10 pela cotação do momento (veja min_saque_cents em GET /comissao). Uma vez a cada 24 h (janela corrida). A entrega é a mesma do cash-in: acompanhe pelo saque.cashin_id em GET /cashin/{cashin_id}/status ou pelo webhook cashin.settled.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
amount_cents | integer | true | Valor em centavos de REAL a converter (≥ min_saque_cents). |
asset | string | false | usdt | usdc (Polygon) ou um ativo de GET /cashin/catalog. Default: |
chain | string | false | Default: |
payout_address | string | true | Sua carteira na rede escolhida. |
payout_tag | string | false | memo/tag nas redes que exigem. |
external_id | string | false | Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado. |
Request schema
{
"type": "object",
"required": [
"amount_cents",
"payout_address"
],
"properties": {
"amount_cents": {
"type": "integer",
"minimum": 1,
"description": "Valor em centavos de REAL a converter (≥ min_saque_cents)."
},
"asset": {
"type": "string",
"default": "usdt",
"description": "usdt | usdc (Polygon) ou um ativo de GET /cashin/catalog."
},
"chain": {
"type": "string",
"default": "polygon"
},
"payout_address": {
"type": "string",
"description": "Sua carteira na rede escolhida."
},
"payout_tag": {
"type": "string",
"description": "memo/tag nas redes que exigem."
},
"external_id": {
"type": "string",
"maxLength": 64,
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado."
}
}
}Responses
200 Saque criado e em entrega
JSON schema · 200
{
"type": "object",
"properties": {
"saque": {
"$ref": "#/components/schemas/Cobranca"
},
"comissao": {
"$ref": "#/components/schemas/Comissao"
}
}
}400 valor_invalido | valor_abaixo_do_minimo (traz min_saque_cents) | rede_indisponivel | asset_invalido | payout_address_invalido | sandbox_sem_saque
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}402 saldo_insuficiente — comissão disponível menor que o pedido
JSON schema · 402
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}409 external_id_divergente
JSON schema · 409
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}429 saque_comissao_diario — traz proximo_saque_em
JSON schema · 429
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}503 provedor_indisponivel — sem cotação para aferir o mínimo
JSON schema · 503
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /keys
Criar chave (self-service)
A chave aparece uma única vez — guarde no momento da criação, só o hash fica armazenado. A resposta traz também os grupos de acompanhamento, onde mudanças de contrato são anunciadas antes de irem ao ar.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | true | Nome do negócio (aparece no painel e nos avisos). |
email | string | false | Recomendado: a chave recém-criada é enviada para este e-mail, além de aparecer na resposta. |
settlement_address | string | false | Carteira EVM (Polygon) de liquidação. Opcional; pode ser definida depois. |
webhook_url | string | false | URL HTTPS para os eventos. Opcional. |
lead_token | string | false | Token opaco |
Request schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 80,
"description": "Nome do negócio (aparece no painel e nos avisos)."
},
"email": {
"type": "string",
"format": "email",
"description": "Recomendado: a chave recém-criada é enviada para este e-mail, além de aparecer na resposta."
},
"settlement_address": {
"type": "string",
"description": "Carteira EVM (Polygon) de liquidação. Opcional; pode ser definida depois."
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "URL HTTPS para os eventos. Opcional."
},
"lead_token": {
"type": "string",
"pattern": "^ldt_[A-Za-z0-9_-]{43}$",
"minLength": 47,
"maxLength": 47,
"description": "Token opaco `ldt_…` devolvido por POST /leads quando a pessoa autorizou contato tecnico (consentimento). Vincula esta chave ao lead. Somente no corpo, nunca na URL. Opcional; ausencia ou token invalido nao impede a criacao."
}
}
}Responses
201 Chave criada.
JSON schema · 201
{
"type": "object",
"properties": {
"api_key": {
"type": "string",
"description": "A chave em claro — aparece SÓ nesta resposta (guardamos apenas o hash)."
},
"email_sent": {
"type": "boolean",
"description": "true quando uma cópia da chave foi enviada ao `email` informado. false se não houve e-mail ou o envio falhou."
},
"webhook_secret": {
"type": "string",
"description": "Presente quando `webhook_url` foi informado."
},
"key": {
"type": "object",
"description": "Visão pública da chave (prefix, name, flags)."
},
"limits": {
"type": "object",
"description": "Limites vigentes."
},
"monitor_url": {
"type": "string",
"format": "uri",
"description": "Monitor ao vivo, só-leitura, do fluxo desta chave."
},
"lead_attribution": {
"type": "object",
"description": "Resultado do elo de atribuicao quando um lead_token consentido e enviado. Nunca bloqueia a criacao da chave.",
"required": [
"requested",
"linked",
"status"
],
"properties": {
"requested": {
"type": "boolean",
"description": "true se um lead_token foi enviado no corpo."
},
"linked": {
"type": "boolean",
"description": "true se a chave foi ligada a um lead consentido."
},
"status": {
"type": "string",
"enum": [
"nao_solicitado",
"vinculado",
"token_invalido",
"indisponivel"
],
"description": "Estado do vinculo."
}
}
}
}
}400 Campos invalidos (name obrigatorio, webhook_url precisa ser https publica).
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}429 Limite de criacao de chaves por IP.
JSON schema · 429
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /keys/me
Limites vigentes e uso do dia
É o número que nunca envelhece: leia os limites daqui em vez de fixá-los no código.
Cash-out (venda de cripto): R$ 6,00 a R$ 250.000,00 por transação, mais um teto diário de R$ 100.000,00 por CPF/CNPJ de quem RECEBE o PIX (por chave, quando a chave PIX não é um documento), que renova à meia-noite no horário de Brasília. O máximo efetivo é o MENOR dos dois e vem em limits.max_brl_cents; o teto por transação vem em limits.max_brl_cents_por_transacao. Não existe teto diário por chave de API na venda.
Cash-in e payouts: também não há teto diário por chave (desde 10/09/2026): limits.daily_limit_cents vem null, limits.tier vem "Sem teto", limits.available_today_cents e limits.next_tier vêm null e limits.daily_limit_applies_to vem []. Cada cobrança vai de R$ 1,00 a R$ 6.000,00 (mínimo efetivo em limits.per_operation.cashin.min_brl_cents) e passa pela régua do pagador (GET /cashin/limits). O único teto diário por chave possível é o que a própria chave define em mandate.max_diario_cents.
Responses
200 Sua chave e limites.
JSON schema · 200
{
"type": "object",
"description": "Sua chave, limites vigentes e o que está liberado.",
"properties": {
"key": {
"type": "object",
"properties": {
"sandbox": {
"type": "boolean"
},
"key_id": {
"type": "integer"
},
"prefix": {
"type": "string"
},
"name": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
],
"description": "null em chave sandbox ou criada sem e-mail."
},
"cashin_enabled": {
"type": "boolean"
},
"cashout_enabled": {
"type": "boolean"
},
"payout_enabled": {
"type": "boolean"
},
"settlement_address": {
"type": [
"string",
"null"
],
"description": "Carteira padrão de liquidação (Polygon); null até ser configurada."
},
"chain": {
"type": [
"string",
"null"
]
},
"fee_bps": {
"type": "integer"
},
"rate_limit_per_minute": {
"type": "integer"
},
"webhook_url": {
"type": [
"string",
"null"
],
"description": "null até cadastrar (PATCH /keys/me) — sem ela não chega cashin.paid/settled/delayed."
},
"webhook_configured": {
"type": "boolean"
},
"telegram_linked": {
"type": "boolean"
},
"created_at": {
"type": [
"string",
"null"
]
},
"partner_fee_bps": {
"type": "integer",
"minimum": 0,
"maximum": 1000,
"description": "SUB FEE do parceiro, em bps, POR CIMA de `fee_bps` (a taxa da Lunium). 100 = 1%. Quem paga é o usuário final; a parte da Lunium não muda. 0 = não usa. Configure em PATCH /keys/me."
}
}
},
"limits": {
"type": "object",
"description": "Limites e uso vigentes da chave, por operação e pagador. null em teto diário significa ausência daquele teto, não de todas as restrições. Mandate e limites por pessoa podem aplicar.",
"additionalProperties": true
},
"payout": {
"type": "object",
"description": "enabled, via, unlocks_at_settled_volume_cents, settled_volume_cents, remaining_cents.",
"additionalProperties": true
},
"monitor_url": {
"type": "string",
"description": "Painel de acompanhamento da chave."
},
"telegram": {
"type": "object",
"additionalProperties": true
},
"grupos_obrigatorios": {
"type": "object",
"description": "Links dos grupos de status (aviso, parceiros, comunidade).",
"additionalProperties": true
},
"comissao": {
"type": "object",
"description": "Comissão acumulada pela sub fee (saldo do parceiro). Detalhe em GET /comissao.",
"properties": {
"partner_fee_bps": {
"type": "integer"
},
"max_partner_fee_bps": {
"type": "integer"
},
"disponivel_cents": {
"type": [
"integer",
"null"
]
},
"creditado_cents": {
"type": "integer"
},
"estornado_cents": {
"type": "integer"
},
"sacado_cents": {
"type": "integer"
},
"operacoes": {
"type": "integer"
},
"ultimo_credito_em": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"moeda": {
"type": "string"
},
"nota": {
"type": "string"
}
}
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}PATCH /keys/me
Atualiza a chave (nome, settlement, webhook, rotações)
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | false | |
settlement_address | ['string', 'null'] | false | Endereço Polygon 0x…; null limpa. |
webhook_url | ['string', 'null'] | false | https pública; null limpa. Definir gera webhook_secret se a chave ainda não tem. |
rotate_webhook_secret | boolean | false | true gira o segredo do webhook — aparece UMA vez na resposta. |
rotate_monitor_token | boolean | false | true gira o token do monitor: a URL antiga deixa de mostrar dados a partir desta chamada; a nova vem em monitor_url. |
partner_fee_bps | integer | false | Sub fee do parceiro em bps, somada à taxa da Lunium e paga pelo usuário final (100 = 1%; máximo 1000 = 10%). Vale para cobrança NOVA: cobrança aberta mantém a taxa congelada. 0 desliga. |
Request schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 80
},
"settlement_address": {
"type": [
"string",
"null"
],
"description": "Endereço Polygon 0x…; null limpa."
},
"webhook_url": {
"type": [
"string",
"null"
],
"description": "https pública; null limpa. Definir gera webhook_secret se a chave ainda não tem."
},
"rotate_webhook_secret": {
"type": "boolean",
"description": "true gira o segredo do webhook — aparece UMA vez na resposta."
},
"rotate_monitor_token": {
"type": "boolean",
"description": "true gira o token do monitor: a URL antiga deixa de mostrar dados a partir desta chamada; a nova vem em monitor_url."
},
"partner_fee_bps": {
"type": "integer",
"minimum": 0,
"maximum": 1000,
"description": "Sub fee do parceiro em bps, somada à taxa da Lunium e paga pelo usuário final (100 = 1%; máximo 1000 = 10%). Vale para cobrança NOVA: cobrança aberta mantém a taxa congelada. 0 desliga."
}
}
}Responses
200 Chave atualizada. Pode trazer webhook_secret (uma única vez) e monitor_url novo.
400 Campos inválidos ou nada para atualizar.
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /keys/painel-link
Receber o link do painel por e-mail (sem chave)
A chave aparece uma vez só; o painel não depende dela. Informe o e-mail cadastrado na chave e o link do painel (só-leitura, dashboard token) chega nele. Resposta sempre genérica — não revela se o e-mail existe. Limitado a 3 envios por e-mail e 10 por IP a cada hora.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | true |
Request schema
{
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email"
}
}
}Responses
200 Pedido aceito (genérico).
400 E-mail inválido.
429 Limite por hora.
POST /keys/sandbox
Get a sandbox API key — one call, no API key needed
Returns a lun_test_ key in one call: no approval, no API key and no wallet. email is required: the e-mail of the person who will test. About a minute later, LuniumPay support sends that address one message with what LuniumPay is, the 3-step integration, the manual and PDF, the flowchart and VendaCripto (a ready-made app to buy or sell crypto with PIX, no integration). One message per address, with an unsubscribe link. Missing or invalid email: 400 email_obrigatorio (acao=corrigir, campo=email). All six financial journeys are simulated with fictitious funds using the normal endpoints. GET /sandbox returns the supported flows, scenario matrix and simulation controls. POST /sandbox/cashin/{cashin_id}/pay confirms a non-payable test charge. Cash-in, custody and payouts are durable; cash-out retention is two hours. Signed webhooks use the normal delivery pipeline with sandbox:true. No financial provider is called. Catalogs and prices are synthetic snapshots, not live quotes. See https://docs.luniumpay.com/sandbox .
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | true | Required. E-mail of the person who will test, e.g. you@company.com. LuniumPay support sends this address one message with the integration guide (what LuniumPay is, the 3 steps, manual and PDF, flowchart, VendaCripto). One message per address, with an unsubscribe link. |
name | string | false | Optional label to recognise the key later. |
webhook_url | string | false | Optional HTTPS webhook. |
lead_token | string | false | Optional opaque token returned by consented POST /leads. Links this TEST key to the contact. Invalid or unavailable attribution never blocks key creation. Never put this token in a URL or log. |
Request schema
{
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 160,
"description": "Required. E-mail of the person who will test, e.g. you@company.com. LuniumPay support sends this address one message with the integration guide (what LuniumPay is, the 3 steps, manual and PDF, flowchart, VendaCripto). One message per address, with an unsubscribe link."
},
"name": {
"type": "string",
"description": "Optional label to recognise the key later."
},
"webhook_url": {
"type": "string",
"format": "uri",
"description": "Optional HTTPS webhook."
},
"lead_token": {
"type": "string",
"pattern": "^ldt_[A-Za-z0-9_-]{43}$",
"description": "Optional opaque token returned by consented POST /leads. Links this TEST key to the contact. Invalid or unavailable attribution never blocks key creation. Never put this token in a URL or log."
}
}
}Responses
201 Sandbox key created
JSON schema · 201
{
"type": "object",
"properties": {
"api_key": {
"type": "string",
"example": "lun_test_1df82296e3459819702c6a6087aab1c7"
},
"sandbox": {
"type": "boolean",
"const": true
},
"gatilhos": {
"type": "object",
"description": "The deterministic triggers, described above."
},
"diferencas_para_producao": {
"type": "array",
"items": {
"type": "string"
}
},
"lead_link": {
"type": "object",
"properties": {
"requested": {
"type": "boolean"
},
"linked": {
"type": "boolean"
},
"status": {
"type": "string"
}
}
}
}
}400 email_obrigatorio: email missing or invalid. Send the e-mail of the person who will test, e.g. {"email": "you@company.com"}.
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"email_obrigatorio",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}429 Too many keys from this IP today
JSON schema · 429
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /leads
Encaminhar um caso comercial ou técnico para uma pessoa
Rota pública, sem chave. Use somente para preço por volume, contrato, parceria ou um caso que a documentação não resolve. O endereço precisa ter sido fornecido pela própria pessoa para este contato; não descubra, não raspe e não reutilize e-mail de outra finalidade. Para começar sem falar com ninguém, use POST /keys/sandbox.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | true | |
nome | string | false | |
empresa | string | false | |
whatsapp | string | false | |
mensagem | string | false | |
fluxo | string | false | Values: |
volume_mensal | string | false | |
prazo | string | false | |
estagio_produto | string | false | |
como_encontrou | string | false | Fonte declarada pela pessoa, separada do UTM. Ex.: chatgpt, google, indicacao. |
consentimento | boolean | true | Confirma que a pessoa forneceu o contato para receber resposta sobre esta solicitação. |
origem | string | false | Página ou contexto onde a solicitação começou. |
utm_source | string | false | |
utm_medium | string | false | |
utm_campaign | string | false | |
utm_content | string | false | |
utm_term | string | false | |
ref_agent | string | false | |
website | string | false | Honeypot: clientes legítimos devem omitir ou enviar vazio. |
Request schema
{
"type": "object",
"required": [
"email",
"consentimento"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 200
},
"nome": {
"type": "string",
"maxLength": 120
},
"empresa": {
"type": "string",
"maxLength": 120
},
"whatsapp": {
"type": "string",
"maxLength": 40
},
"mensagem": {
"type": "string",
"maxLength": 1000
},
"fluxo": {
"type": "string",
"enum": [
"cashin",
"cashout",
"cashin_cashout",
"payout",
"outro",
"custody"
]
},
"volume_mensal": {
"type": "string",
"maxLength": 60
},
"prazo": {
"type": "string",
"maxLength": 60
},
"estagio_produto": {
"type": "string",
"maxLength": 60
},
"como_encontrou": {
"type": "string",
"description": "Fonte declarada pela pessoa, separada do UTM. Ex.: chatgpt, google, indicacao."
},
"consentimento": {
"type": "boolean",
"const": true,
"description": "Confirma que a pessoa forneceu o contato para receber resposta sobre esta solicitação."
},
"origem": {
"type": "string",
"description": "Página ou contexto onde a solicitação começou."
},
"utm_source": {
"type": "string"
},
"utm_medium": {
"type": "string"
},
"utm_campaign": {
"type": "string"
},
"utm_content": {
"type": "string"
},
"utm_term": {
"type": "string"
},
"ref_agent": {
"type": "string"
},
"website": {
"type": "string",
"description": "Honeypot: clientes legítimos devem omitir ou enviar vazio."
}
}
}Responses
200 Contato existente atualizado dentro da janela de deduplicação. Com consentimento explícito, devolve um novo lead_token e invalida o anterior.
JSON schema · 200
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"lead_id": {
"type": "integer",
"format": "int64"
},
"lead_token": {
"type": "string",
"pattern": "^ldt_[A-Za-z0-9_-]{43}$",
"minLength": 47,
"maxLength": 47,
"description": "Opaque attribution token returned with explicit consent. Send only in POST /keys, POST /keys/sandbox or lunium_start_sandbox_demo. Never place it in URLs or logs."
},
"detail": {
"type": "string"
},
"integration_url": {
"type": "string",
"format": "uri",
"description": "Start the self-service integration immediately; human contact is optional."
}
}
}201 Contato recebido. Com consentimento explícito, lead_token liga este contato à chave criada em seguida.
JSON schema · 201
{
"type": "object",
"required": [
"ok",
"lead_id"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"lead_id": {
"type": "integer",
"format": "int64"
},
"lead_token": {
"type": "string",
"pattern": "^ldt_[A-Za-z0-9_-]{43}$",
"minLength": 47,
"maxLength": 47,
"description": "Opaque attribution token returned with explicit consent. Send only in POST /keys, POST /keys/sandbox or lunium_start_sandbox_demo. Never place it in URLs or logs."
},
"detail": {
"type": "string"
},
"integration_url": {
"type": "string",
"format": "uri",
"description": "Start the self-service integration immediately; human contact is optional."
}
}
}400 E-mail ou corpo inválido.
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}429 Muitas tentativas pelo mesmo endereço.
503 Contato não pôde ser persistido; tente novamente ou use o e-mail publicado.
GET /mesh
Tudo que um agente precisa saber antes de integrar
Um GET responde: quem somos, o que liquidamos, quais ativos e redes, todos os endpoints, como obter chave, como chegar a producao, os limites e os schemas. Nao exige credencial.
Responses
200 O documento de descoberta.
JSON schema · 200
{
"type": "object",
"description": "Documento unico que responde o que um agente pergunta antes de integrar. Gerado da configuracao viva — nao pode divergir do que a API faz.",
"properties": {
"quem_somos": {
"type": "object"
},
"como_falar_comigo": {
"type": "object",
"description": "REST, OpenAPI, MCP, A2A e Mesh."
},
"capacidades": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Capability"
}
},
"como_escolher_capacidade": {
"type": "object",
"description": "Indice invertido intencao -> capacidades, mais como filtrar por atributo.",
"properties": {
"por_intencao": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"execucao": {
"type": "object",
"description": "Por capacidade: endpoint, campos obrigatorios e exemplo pronto."
},
"ativos_e_redes": {
"type": "object"
},
"limites": {
"type": "object"
},
"como_comecar": {
"type": "object"
},
"regra_de_seguranca": {
"type": "object"
},
"atribuicao": {
"type": "object"
}
}
}GET /mesh/agents
Quem esta na rede
Diretorio publico. Nunca devolve chave, hash nem token.
Responses
200 Agentes.
JSON schema · 200
{
"type": "object",
"properties": {
"agents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentIdentity"
}
}
}
}POST /mesh/agents
Cadastrar um agente e receber credencial de sandbox
Cadastro e emissao de chave numa chamada. Com referral_token, a linhagem fica provada; sem ele, o agente entra como raiz.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | true | |
description | string | false | |
contact | string | false | |
agent_card_url | string | false | |
capabilities | array | false | |
referral_token | string | false | Attestation assinada por quem indicou. E o UNICO jeito de ter linhagem: |
Request schema
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 80
},
"description": {
"type": "string"
},
"contact": {
"type": "string"
},
"agent_card_url": {
"type": "string"
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"referral_token": {
"type": "string",
"description": "Attestation assinada por quem indicou. E o UNICO jeito de ter linhagem: `referred_by` declarado pelo cliente e recusado, porque vale dinheiro."
}
}
}Responses
201 Agente criado, com credencial e proximo passo.
JSON schema · 201
{
"type": "object",
"properties": {
"agent": {
"$ref": "#/components/schemas/AgentIdentity"
},
"api_key": {
"type": "string"
},
"sandbox": {
"type": "boolean"
},
"lineage": {
"type": "object"
},
"proximo_passo": {
"type": "object"
}
}
}400 Pedido invalido ou referral_token recusado.
JSON schema · 400
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}GET /mesh/agents/{agent_id}
Estado, mandate, metricas e linhagem de um agente
Parameters
| Field | In | Required | Description |
|---|---|---|---|
agent_id | path | true |
Responses
200 O agente.
JSON schema · 200
{
"type": "object",
"description": "Identidade PERMANENTE do agente. Credencial e substituivel; linhagem, volume, recompensa, mandate e reputacao pertencem ao agent_id.",
"properties": {
"agent_id": {
"type": "string",
"example": "agt_2319c9da313e84af3b"
},
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"contact": {
"type": [
"string",
"null"
]
},
"status": {
"$ref": "#/components/schemas/AgentLifecycle"
},
"environment": {
"type": "string",
"enum": [
"sandbox",
"production"
]
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
},
"settlement_address": {
"type": [
"string",
"null"
]
},
"referred_by": {
"type": [
"string",
"null"
],
"description": "Imutavel apos o registro (gatilho no banco)."
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}404 Nao existe.
JSON schema · 404
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}POST /mesh/agents/{agent_id}/mandate
Definir a propria politica de limites
So APERTA os limites da chave, nunca amplia. Obrigatorio antes de producao.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
agent_id | path | true |
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
max_por_operacao_cents | integer | false | |
max_diario_cents | integer | false | |
contrapartes | array | false | Chaves PIX autorizadas. Vazio = sem restricao. |
Request schema
{
"type": "object",
"description": "Politica que a propria chave se impoe. So APERTA os limites, nunca amplia — por isso o agente pode defini-la sozinho: o pior que faz e se limitar. Obrigatorio antes de producao.",
"properties": {
"max_por_operacao_cents": {
"type": "integer",
"example": 30000
},
"max_diario_cents": {
"type": "integer",
"example": 200000
},
"contrapartes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Chaves PIX autorizadas. Vazio = sem restricao."
}
}
}Responses
200 Feito.
JSON schema · 200
{
"type": "object"
}401 Sem chave.
JSON schema · 401
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}403 A chave nao e deste agente.
JSON schema · 403
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}409 Pre-requisito faltando.
JSON schema · 409
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}GET /mesh/agents/{agent_id}/network
Linhagem, arvore e volume de rede
Consulta recursiva no banco. network_volume conta a arvore inteira; reward_eligible_volume conta so o que remunera (nivel 1).
Parameters
| Field | In | Required | Description |
|---|---|---|---|
agent_id | path | true |
Responses
200 A rede.
JSON schema · 200
{
"type": "object",
"description": "A arvore abaixo de um agente. `network_volume` conta a arvore inteira (serve para reputacao); `reward_eligible_volume` conta so o que remunera.",
"properties": {
"agent_id": {
"type": "string"
},
"referred_by": {
"type": [
"string",
"null"
]
},
"depth": {
"type": "integer"
},
"direct_children": {
"type": "integer"
},
"total_descendants": {
"type": "integer"
},
"own_volume_cents": {
"type": "integer"
},
"own_transactions": {
"type": "integer"
},
"network_volume_cents": {
"type": "integer"
},
"network_transactions": {
"type": "integer"
},
"reward_eligible_volume_cents": {
"type": "integer"
},
"lifetime_rewards_cents": {
"type": "integer"
},
"first_operation": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"production_since": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"children": {
"type": "array",
"items": {
"type": "object"
}
}
}
}404 Nao existe.
JSON schema · 404
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}POST /mesh/agents/{agent_id}/production-request
Ativar producao (automatico, sem humano)
Confere sozinho: validacao com prova de uso, endereco de liquidacao em rede suportada, mandate dentro da politica e credencial ativa. Passando, producao entra na mesma resposta. Faltando algo, devolve 422 com missing e next_actions para o agente corrigir e tentar de novo.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
agent_id | path | true |
Responses
200 Feito.
JSON schema · 200
{
"type": "object",
"description": "Ativacao AUTOMATICA. `activated_by` e sempre `policy` — nunca `operator`.",
"properties": {
"status": {
"type": "string",
"example": "production_active"
},
"agent_id": {
"type": "string"
},
"environment": {
"type": "string",
"example": "production"
},
"activated_at": {
"type": "string",
"format": "date-time"
},
"activated_by": {
"type": "string",
"example": "policy"
},
"api_key": {
"type": "string",
"description": "Credencial de producao (`lun_live_*`), uma vez so."
},
"settlement": {
"type": "object"
},
"mandate": {
"$ref": "#/components/schemas/Mandate"
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
}
}
}401 Sem chave.
JSON schema · 401
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}403 A chave nao e deste agente.
JSON schema · 403
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}409 Pre-requisito faltando.
JSON schema · 409
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}422 Requisitos incompletos — legivel por maquina.
JSON schema · 422
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}GET /mesh/agents/{agent_id}/rewards
Saldo de recompensas e extrato do ledger
Parameters
| Field | In | Required | Description |
|---|---|---|---|
agent_id | path | true |
Responses
200 Saldo e ledger.
JSON schema · 200
{
"type": "object",
"description": "Saldo do agent_id — nunca da credencial. Rotacionar chave nao perde saldo.",
"properties": {
"agent_id": {
"type": "string"
},
"own_volume_cents": {
"type": "integer"
},
"direct_referral_volume_cents": {
"type": "integer"
},
"network_volume_cents": {
"type": "integer"
},
"pending_rewards_cents": {
"type": "integer"
},
"available_rewards_cents": {
"type": "integer"
},
"paid_rewards_cents": {
"type": "integer"
},
"lifetime_rewards_cents": {
"type": "integer"
},
"reward_events": {
"type": "integer"
},
"reversals": {
"type": "integer"
},
"policy": {
"$ref": "#/components/schemas/MeshEconomyPolicy"
},
"ledger": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RewardEvent"
}
}
}
}404 Nao existe.
JSON schema · 404
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}POST /mesh/agents/{agent_id}/settlement
Dizer para onde o dinheiro vai
Endereco na rede de liquidacao suportada.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
agent_id | path | true |
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
settlement_address | string | true | Carteira na rede de liquidacao suportada. |
Request schema
{
"type": "object",
"required": [
"settlement_address"
],
"properties": {
"settlement_address": {
"type": "string",
"example": "0x51e3…75e0",
"description": "Carteira na rede de liquidacao suportada."
}
}
}Responses
200 Feito.
JSON schema · 200
{
"type": "object"
}401 Sem chave.
JSON schema · 401
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}403 A chave nao e deste agente.
JSON schema · 403
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}409 Pre-requisito faltando.
JSON schema · 409
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}POST /mesh/agents/{agent_id}/validate
Provar que o sandbox foi exercitado
Recusa quem so criou a chave: e preciso ter criado E aceito uma ordem no sandbox. E o passo que garante que o seu tratamento de erro e o seu polling existem antes de haver dinheiro envolvido.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
agent_id | path | true |
Responses
200 Feito.
JSON schema · 200
{
"type": "object"
}401 Sem chave.
JSON schema · 401
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}403 A chave nao e deste agente.
JSON schema · 403
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}409 Pre-requisito faltando.
JSON schema · 409
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}GET /mesh/economy
Regras publicas da economia da rede
0,10 % sobre volume LIQUIDADO de quem voce trouxe, somente nivel 1. Cadastro, indicacao, cotacao e sandbox nao pagam nada.
Responses
200 A politica vigente.
JSON schema · 200
{
"type": "object",
"description": "Regras publicas da economia. NO SETTLEMENT → NO REWARD.",
"properties": {
"model": {
"type": "string",
"example": "transaction_attribution"
},
"direct_rate": {
"type": "string",
"example": "0.10%"
},
"direct_rate_bps": {
"type": "integer",
"example": 10
},
"max_paid_levels": {
"type": "integer",
"example": 1
},
"recruitment_reward": {
"type": "boolean",
"example": false
},
"requires_settled_transaction": {
"type": "boolean",
"example": true
},
"revenue_share_cap": {
"type": "string"
}
}
}GET /mesh/graph
Grafo de agentes do Mesh
Quem está na rede e quem trouxe quem: lista os agentes públicos (sem segredo) e agrega totais da rede. Não exige credencial.
Responses
200 Estatísticas e agentes públicos.
JSON schema · 200
{
"type": "object",
"required": [
"stats",
"agents"
],
"properties": {
"stats": {
"type": "object",
"additionalProperties": true
},
"agents": {
"type": "array",
"items": {
"type": "object",
"required": [
"agent_id",
"name",
"status",
"capabilities"
],
"properties": {
"agent_id": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"referred_by": {
"type": [
"string",
"null"
]
},
"capabilities": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}POST /mesh/referrals
Emitir uma attestation de indicacao
Exige a X-API-Key do agente que indica. Devolve token assinado, de uso unico e com prazo. E o unico jeito de a linhagem existir — e, com ela, os 0,10 %.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
capability | string | false | |
expires_in_minutes | integer | false | Default: |
Request schema
{
"type": "object",
"properties": {
"capability": {
"type": "string"
},
"expires_in_minutes": {
"type": "integer",
"default": 60,
"maximum": 10080
}
}
}Responses
201 Attestation emitida.
JSON schema · 201
{
"type": "object",
"description": "Token assinado (JWS HS256) que PROVA quem indicou. Uso unico, com prazo. Sem ele o agente entra como raiz e ninguem recebe por ele.",
"properties": {
"type": {
"type": "string",
"example": "mesh_referral"
},
"referrer_agent_id": {
"type": "string"
},
"referral_token": {
"type": "string"
},
"capability": {
"type": [
"string",
"null"
]
},
"nonce": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"one_time_use": {
"type": "boolean",
"example": true
}
}
}401 Sem chave.
JSON schema · 401
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}404 Chave nao associada a um agente.
JSON schema · 404
{
"type": "object",
"description": "Erro que o proprio agente consegue resolver. `acao` e enum estavel: corrigir (seu pedido esta errado), esperar (cota), parar (nao adianta repetir), repetir (falha transitoria nossa).",
"properties": {
"erro": {
"type": "string",
"example": "mandate_valor_acima_do_teto"
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"esperar",
"parar",
"repetir"
]
},
"detail": {
"type": "string"
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"next_actions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NextAction"
}
}
},
"required": [
"erro",
"acao"
]
}GET /payouts
Lista os payouts desta chave
Parameters
| Field | In | Required | Description |
|---|---|---|---|
status | query | false | |
limit | query | false | |
external_id | query | false | Recuperacao idempotente: devolve a operacao com este external_id (0 ou 1). Unico por chave e produto, case-sensitive, retido permanentemente. |
Responses
200 Lista (mais recentes primeiro). Lista vazia = 200, nunca 403.
JSON schema · 200
{
"type": "object",
"properties": {
"payouts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Payout"
}
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}403 Payout ainda nao liberado para esta chave.
JSON schema · 403
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /payouts
Send a PIX directly (no crypto leg)
Envia PIX debitando somente saldo BRL disponível da casa ou subconta customer_ref, recebido por PIX. Confira payout.enabled em GET /keys/me, custodia_ativa, pix_rules e taxas em GET /saldo. Máximo R$ 6.000,00 por PIX, sujeito a limites menores da conta. CPF/CNPJ válido do recebedor é obrigatório; a API pode derivá-lo de uma chave CPF/CNPJ. Valor mais taxas são reservados antes de chamar o provedor; sem saldo, 402. Consulte a tarifa vigente na API e concilie fee_cents da operação. Limites e mandate da chave continuam aplicáveis. Use external_id estável e consulte a ordem original após timeout. Sandbox usa saldo fictício e calcula a tarifa publicada pela API; não há pagamento real. A carteira USDT é separada do saldo BRL: requer habilitação do projeto, recebe depósitos externos de USDT e não usa /payouts. Quando habilitada, usa funding_source=crypto_usdt; documento do recebedor não é exigido nesse fluxo. Seus limites vêm da cotação e das condições da API, não do teto de R$ 6.000 do saldo BRL. Não está disponível em sandbox.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
amount_cents | integer | true | Valor do PIX em CENTAVOS de real, inteiro (5000 = R$ 50,00). Máximo 600000 (R$ 6.000,00), sujeito a limite menor da conta. Taxas são debitadas além deste valor. |
pix_key | string | true | Chave PIX de destino que recebe os reais (CPF, CNPJ, telefone +55, e-mail ou chave aleatória). Com 11 dígitos crus envie também pix_key_type ("cpf" ou "phone") — sem isso a API recusa com erro=tipo_ambiguo em vez de adivinhar. |
pix_key_type | — | false | Opcional: deduzido do formato da chave (e-mail, CNPJ, UUID, telefone com +55). So e obrigatorio quando a chave tem 11 digitos puros, onde CPF e telefone sao indistinguiveis — nesse caso a API recusa com erro tipo_ambiguo em vez de chutar. Values: |
tax_number | string | false | CPF ou CNPJ válido do recebedor, com dígitos verificadores conferidos. Obrigatório para chave de e-mail, telefone ou aleatória. Para chave CPF/CNPJ válida, pode ser omitido: a API usa o documento da própria chave; se informado, deve coincidir. Não comprova titularidade da chave. |
beneficiary_name | string | false | Optional. Beneficiary's full name, forwarded to the PIX provider as the end user's name. Not required — payouts to third-party PIX keys are allowed. |
external_id | string | false | Identificador idempotente de até 64 caracteres. Nos retries, mantenha valor, chave PIX, tipo, documento, customer_ref e funding_source do pedido original. Conflito 409 external_id_divergente ou external_id_nao_verificavel retorna payout_id/recovery_endpoint para consultar a ordem original; não gere outro ID apenas para contornar o conflito. |
customer_ref | string | false | Sub-account to debit (custody keys). Debited BEFORE the PIX is sent: amount + house fee ( |
sandbox_scenario | string | false | Only for a sandbox key. GET /sandbox provides the scenario matrix by flow. Omit in production. All prices, payments and withdrawals remain fictitious. Values: |
funding_source | string | false | Opcional. Único valor aceito: pix_brl. Este endpoint debita saldo em reais recebido por PIX; nunca debita a carteira USDT. Values: |
Request schema
{
"type": "object",
"properties": {
"amount_cents": {
"type": "integer",
"minimum": 1,
"description": "Valor do PIX em CENTAVOS de real, inteiro (5000 = R$ 50,00). Máximo 600000 (R$ 6.000,00), sujeito a limite menor da conta. Taxas são debitadas além deste valor.",
"maximum": 600000
},
"pix_key": {
"type": "string",
"description": "Chave PIX de destino que recebe os reais (CPF, CNPJ, telefone +55, e-mail ou chave aleatória). Com 11 dígitos crus envie também pix_key_type (\"cpf\" ou \"phone\") — sem isso a API recusa com erro=tipo_ambiguo em vez de adivinhar."
},
"pix_key_type": {
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"random"
],
"description": "Opcional: deduzido do formato da chave (e-mail, CNPJ, UUID, telefone com +55). So e obrigatorio quando a chave tem 11 digitos puros, onde CPF e telefone sao indistinguiveis — nesse caso a API recusa com erro tipo_ambiguo em vez de chutar."
},
"tax_number": {
"type": "string",
"description": "CPF ou CNPJ válido do recebedor, com dígitos verificadores conferidos. Obrigatório para chave de e-mail, telefone ou aleatória. Para chave CPF/CNPJ válida, pode ser omitido: a API usa o documento da própria chave; se informado, deve coincidir. Não comprova titularidade da chave."
},
"beneficiary_name": {
"type": "string",
"maxLength": 120,
"description": "Optional. Beneficiary's full name, forwarded to the PIX provider as the end user's name. Not required — payouts to third-party PIX keys are allowed."
},
"external_id": {
"type": "string",
"description": "Identificador idempotente de até 64 caracteres. Nos retries, mantenha valor, chave PIX, tipo, documento, customer_ref e funding_source do pedido original. Conflito 409 external_id_divergente ou external_id_nao_verificavel retorna payout_id/recovery_endpoint para consultar a ordem original; não gere outro ID apenas para contornar o conflito.",
"maxLength": 64
},
"customer_ref": {
"type": "string",
"maxLength": 80,
"description": "Sub-account to debit (custody keys). Debited BEFORE the PIX is sent: amount + house fee (`saque_fee_bps`) + provider fee; on explicit provider refusal the debits are reversed. 402 `saldo_insuficiente` when available balance < amount + fees (`saque_fee_bps`, `saque_taxa_estimada_cents` in GET /saldo). Sub-account (e.g. the merchant) whose balance is debited. Same value used on the deposit."
},
"sandbox_scenario": {
"type": "string",
"enum": [
"success",
"delayed",
"held",
"expired",
"refunded",
"failed",
"payer_mismatch",
"settlement_failed",
"settlement_uncertain",
"route_unavailable",
"provider_unavailable"
],
"description": "Only for a sandbox key. GET /sandbox provides the scenario matrix by flow. Omit in production. All prices, payments and withdrawals remain fictitious."
},
"funding_source": {
"type": "string",
"enum": [
"pix_brl"
],
"description": "Opcional. Único valor aceito: pix_brl. Este endpoint debita saldo em reais recebido por PIX; nunca debita a carteira USDT."
}
},
"required": [
"amount_cents",
"pix_key"
]
}Responses
403 Administrative kill switch or `custodia_desligada`. Production keys are enabled by default; if this response appears, stop and contact support instead of retrying. No PIX was sent.
JSON schema · 403
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}409 external_id_divergente ou external_id_nao_verificavel: consulte payout_id/recovery_endpoint da operação original. Não altere parâmetros nem gere novo ID para a mesma intenção. em_processamento: consulte a ordem em andamento, sem reenviar um novo pagamento.
JSON schema · 409
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
},
"payout_id": {
"type": "string",
"description": "Original payout identifier."
},
"recovery_endpoint": {
"type": "string",
"description": "Relative API path of the original payout."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}423 carencia_primeiro_deposito — first-deposit hold (only keys with a contractual holding period; none by default since 2026-09-16): no withdrawal for this sub-account until `libera_em`.
JSON schema · 423
{
"type": "object",
"properties": {
"erro": {
"type": "string",
"enum": [
"carencia_primeiro_deposito"
]
},
"acao": {
"type": "string",
"enum": [
"esperar"
]
},
"detail": {
"type": "string"
},
"libera_em": {
"type": "string",
"format": "date-time"
}
}
}503 saque_indisponivel: financiamento/provedor indisponível; nenhuma nova reserva ou débito é feito nesta tentativa. idempotencia_indisponivel: não foi possível conferir a ordem anterior; nenhuma nova ordem é criada, mas a anterior pode existir. Aguarde e consulte o mesmo external_id; não gere outro ID.
200 Payout criado ou replay idempotente da operação original.
JSON schema · 200
{
"type": "object",
"description": "Saque PIX (PIX→PIX) debitado do saldo custodial da chave.",
"properties": {
"payout_id": {
"type": "string"
},
"customer_ref": {
"type": [
"string",
"null"
],
"maxLength": 80
},
"status": {
"type": "string",
"description": "processing, sent, failed ou refunded; use extrato para conciliar saldo. Estados novos devem ser tolerados."
},
"amount_cents": {
"type": "integer",
"description": "Valor que o destinatário recebe."
},
"fee_cents": {
"type": [
"integer",
"null"
],
"description": "Total debitado além do valor = fee_service_cents + fee_provider_cents."
},
"fee_service_cents": {
"type": [
"integer",
"null"
],
"description": "Taxa da chave (saque_fee_bps de GET /saldo)."
},
"fee_provider_cents": {
"type": [
"integer",
"null"
],
"description": "Tarifa efetiva do provedor. Pode ser fixa ou percentual; consulte os campos saque_taxa_provedor_* em GET /saldo."
},
"pix_key": {
"type": "string"
},
"pix_key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"random"
]
},
"tax_number": {
"type": [
"string",
"null"
],
"description": "Documento do beneficiário mascarado, quando informado; opcional no pedido."
},
"external_id": {
"type": [
"string",
"null"
],
"description": "Identificador idempotente de até 64 caracteres. Nos retries, mantenha valor, chave PIX, tipo, documento, customer_ref e funding_source do pedido original. Conflito 409 external_id_divergente ou external_id_nao_verificavel retorna payout_id/recovery_endpoint para consultar a ordem original; não gere outro ID apenas para contornar o conflito.",
"maxLength": 64
},
"error": {
"type": [
"string",
"null"
],
"description": "Motivo quando failed/refunded."
},
"e2e": {
"type": [
"string",
"null"
],
"description": "EndToEndId do PIX enviado."
},
"receiver_name": {
"type": [
"string",
"null"
],
"description": "Nome obtido após o pagamento quando disponível. null quando não obtido."
},
"receiver_tax_number": {
"type": [
"string",
"null"
]
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sent_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"verify_url": {
"type": [
"string",
"null"
],
"description": "Verificação pública do PIX (GET /v1/verificar/{e2e})."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sandbox": {
"type": "boolean",
"description": "True for fictitious sandbox operations."
},
"simulation": {
"type": "object",
"additionalProperties": true
}
}
}400 Recusa ou falha; leia erro, acao e detail quando presentes.
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}402 Recusa ou falha; leia erro, acao e detail quando presentes.
JSON schema · 402
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}500 Recusa ou falha; leia erro, acao e detail quando presentes.
JSON schema · 500
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /payouts/{payout_id}
State of a payout
Parameters
| Field | In | Required | Description |
|---|---|---|---|
payout_id | path | true |
Responses
200 Estado do saque.
JSON schema · 200
{
"type": "object",
"description": "Saque PIX (PIX→PIX) debitado do saldo custodial da chave.",
"properties": {
"payout_id": {
"type": "string"
},
"customer_ref": {
"type": [
"string",
"null"
],
"maxLength": 80
},
"status": {
"type": "string",
"description": "processing, sent, failed ou refunded; use extrato para conciliar saldo. Estados novos devem ser tolerados."
},
"amount_cents": {
"type": "integer",
"description": "Valor que o destinatário recebe."
},
"fee_cents": {
"type": [
"integer",
"null"
],
"description": "Total debitado além do valor = fee_service_cents + fee_provider_cents."
},
"fee_service_cents": {
"type": [
"integer",
"null"
],
"description": "Taxa da chave (saque_fee_bps de GET /saldo)."
},
"fee_provider_cents": {
"type": [
"integer",
"null"
],
"description": "Tarifa efetiva do provedor. Pode ser fixa ou percentual; consulte os campos saque_taxa_provedor_* em GET /saldo."
},
"pix_key": {
"type": "string"
},
"pix_key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"random"
]
},
"tax_number": {
"type": [
"string",
"null"
],
"description": "Documento do beneficiário mascarado, quando informado; opcional no pedido."
},
"external_id": {
"type": [
"string",
"null"
],
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.",
"maxLength": 64
},
"error": {
"type": [
"string",
"null"
],
"description": "Motivo quando failed/refunded."
},
"e2e": {
"type": [
"string",
"null"
],
"description": "EndToEndId do PIX enviado."
},
"receiver_name": {
"type": [
"string",
"null"
],
"description": "Nome obtido após o pagamento quando disponível. null quando não obtido."
},
"receiver_tax_number": {
"type": [
"string",
"null"
]
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sent_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"verify_url": {
"type": [
"string",
"null"
],
"description": "Verificação pública do PIX (GET /v1/verificar/{e2e})."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"sandbox": {
"type": "boolean",
"description": "True for fictitious sandbox operations."
},
"simulation": {
"type": "object",
"additionalProperties": true
}
}
}404 Not found
JSON schema · 404
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /ping
Saúde da API
Responses
200 pong
GET /pix/keys/lookup
Consultar titular PIX quando a verificação estiver disponível
Consulta auxiliar de titular. Quando desabilitada, retorna HTTP 200 com verified=false, available=false, verification_status=not_performed, source=disabled e dados de titular nulos. Isso não desabilita pagamentos. Quando disponível, retorna dados obtidos do DICT sujeitos a cache e rate limit. Sandbox retorna titular fictício, source=sandbox. Não trate HTTP 200 isoladamente como titular verificado; envie type explícito quando souber o tipo.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
key | query | true | A chave PIX (CPF, CNPJ, e-mail, telefone com ou sem +55, ou aleatória). |
type | query | false | Opcional. Deduzido do formato quando ausente. |
Responses
200 Titular encontrado.
JSON schema · 200
{
"type": "object",
"required": [
"pix_key",
"pix_key_type",
"owner_name",
"verified",
"source",
"checked_at"
],
"properties": {
"pix_key": {
"type": "string",
"description": "A chave, normalizada (telefone em +55…)."
},
"pix_key_type": {
"type": "string",
"enum": [
"cpf",
"cnpj",
"phone",
"email",
"random"
],
"description": "Tipo da chave consultada: \"cpf\", \"cnpj\", \"phone\", \"email\" ou \"random\"."
},
"owner_name": {
"type": [
"string",
"null"
],
"description": "Nome do titular, como está no DICT.",
"examples": [
"João Silva"
]
},
"owner_tax_number": {
"type": [
"string",
"null"
],
"description": "CPF/CNPJ MASCARADO. Nunca vem inteiro.",
"examples": [
"***.202.745-**"
]
},
"institution_name": {
"type": [
"string",
"null"
],
"description": "Instituição onde a chave está registrada.",
"examples": [
"NU PAGAMENTOS - IP"
]
},
"ispb": {
"type": [
"string",
"null"
],
"description": "ISPB da instituição (8 dígitos).",
"examples": [
"18236120"
]
},
"verified": {
"type": "boolean",
"description": "true quando titular foi consultado ou simulado (source=sandbox); false quando não verificado."
},
"source": {
"type": "string",
"enum": [
"dict",
"sandbox",
"disabled"
]
},
"checked_at": {
"type": "string",
"format": "date-time"
},
"cached": {
"type": "boolean",
"description": "true quando a resposta veio do cache de 24h."
},
"sandbox": {
"type": "boolean",
"description": "Só em chave de teste: titular fictício."
},
"available": {
"type": "boolean",
"description": "false quando consulta está indisponível; pode vir com HTTP 200."
},
"optional": {
"type": "boolean",
"description": "Consulta é auxiliar; não é um requisito de pagamento."
},
"verification_status": {
"type": "string",
"description": "not_performed quando a verificação não foi executada."
},
"detail": {
"type": "string"
}
}
}400 Chave em formato inválido (`pix_key_invalida`) ou ausente (`pix_key_obrigatoria`).
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}404 Chave não existe no DICT (`chave_nao_encontrada`).
JSON schema · 404
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}429 Limite de 5 consultas/min da conta (`limite_consultas`); leia `Retry-After`.
JSON schema · 429
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}503 Provedor DICT indisponível (`provedor_indisponivel`, repetir) ou consulta desligada (`consulta_indisponivel`, esperar).
JSON schema · 503
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}GET /saldo
BRL balance (custody) — available, on hold, next releases
Saldo BRL da casa ou da subconta customer_ref. Retorna disponível, bloqueado, próximas liberações e condições efetivas de custódia. Taxas e carência dependem da chave. Retenção local da cobrança, retenção do provedor e carência do saldo são regras distintas. Somente disponivel_cents financia saques; GET /saldo/consolidado soma casa e clientes. Sandbox retorna saldo ficticio persistente; aceita depositos simulados, saques e transferencias.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
customer_ref | query | false | Sub-account (your end customer id). Omit for the key's main balance. |
Responses
200 OK
JSON schema · 200
{
"type": "object",
"required": [
"disponivel_cents",
"bloqueado_cents",
"total_cents"
],
"properties": {
"customer_ref": {
"type": [
"string",
"null"
],
"maxLength": 80
},
"disponivel_cents": {
"type": "integer"
},
"bloqueado_cents": {
"type": "integer"
},
"total_cents": {
"type": "integer"
},
"movimentos": {
"type": "integer"
},
"proximas_liberacoes": {
"type": "array",
"description": "Próximas liberações do escopo pedido (casa ou customer_ref). Pode trazer até 200 itens (antes da 1.44.2, no máximo 20): não presuma um teto menor.",
"items": {
"type": "object",
"properties": {
"disponivel_em": {
"type": "string",
"format": "date-time"
},
"valor_cents": {
"type": "integer"
}
}
}
},
"custodia_ativa": {
"type": "boolean",
"description": "false = this key cannot hold BRL (destino \"saldo\" is refused)."
},
"carencia_horas": {
"type": "integer",
"description": "Carência configurada para esta chave; zero quando o crédito entra no saldo sem carência. Retenções da cobrança e créditos bloqueados continuam independentes."
},
"deposito_fee_bps": {
"type": "integer",
"description": "Taxa efetiva de depósito da chave em bps, deduzida no crédito."
},
"saque_taxa_estimada_cents": {
"type": "integer",
"description": "Tarifa fixa ou piso estimado do provedor. Para percentual, aplique saque_taxa_provedor_formula; não é preço total de todo saque."
},
"saque_fee_bps": {
"type": "integer",
"description": "Taxa de saque da casa em bps; leia a condição desta chave. 100 bps = 1%."
},
"saque_cripto_fee_bps": {
"type": "integer",
"description": "Taxa de saque da casa em bps; leia a condição desta chave. 100 bps = 1%."
},
"primeiro_deposito_em": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When the first deposit of this sub-account was credited (null = never deposited)."
},
"carencia_ate": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "Fim da carência do primeiro depósito, quando em curso; null caso contrário. Leia também bloqueado_cents e proximas_liberacoes."
},
"retencao_acima_cents": {
"type": "integer",
"description": "Limiar de política para primeiro pagamento elegível em custódia. Não significa retenção de todo depósito acima deste valor; a régua e a chave também decidem."
},
"deposito_fee_fixed_cents": {
"type": [
"integer",
"null"
],
"description": "Parcela fixa efetiva da taxa de depósito, em centavos."
},
"saque_taxa_provedor_formula": {
"type": [
"string",
"null"
],
"description": "Fórmula vigente: fixa (piso_cents) ou percentual com piso. Não fixe um provedor como sempre ativo."
},
"saque_taxa_provedor_tipo": {
"type": "string",
"enum": [
"fixo",
"percentual"
],
"description": "Tipo vigente de tarifa do provedor de payout."
},
"saque_taxa_provedor_piso_cents": {
"type": "integer",
"description": "Tarifa fixa ou piso da tarifa percentual, em centavos."
},
"sandbox": {
"type": "boolean",
"description": "true na resposta reduzida de teste."
}
}
}401 Missing or invalid key
GET /saldo/clientes
Subcontas (clientes finais) com saldo, paginadas
Lista cada customer_ref da chave com disponível, bloqueado e total. Ordenado por customer_ref; pagine com cursor=next_cursor. com_saldo=1 esconde subcontas zeradas.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
limit | query | false | |
cursor | query | false |
|
com_saldo | query | false | 1 = só subcontas com saldo diferente de zero. |
Responses
200 Página de subcontas.
JSON schema · 200
{
"type": "object",
"properties": {
"clientes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"customer_ref": {
"type": "string",
"maxLength": 80
},
"disponivel_cents": {
"type": "integer"
},
"bloqueado_cents": {
"type": "integer"
},
"total_cents": {
"type": "integer"
},
"movimentos": {
"type": "integer"
},
"primeiro_movimento_em": {
"type": "string",
"format": "date-time"
},
"ultimo_movimento_em": {
"type": "string",
"format": "date-time"
}
}
}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
]
}
}
}GET /saldo/consolidado
Consolidado da chave: casa + clientes (custódia total)
Soma tudo o que a chave tem sob custódia. casa = movimentos sem customer_ref (margem do parceiro, ajustes, o que ele mesmo saca). clientes = soma das subcontas (movimentos com customer_ref). total_custodiado_cents = casa + clientes. É o número que o financeiro do parceiro concilia.
Responses
200 Consolidado.
JSON schema · 200
{
"type": "object",
"properties": {
"casa": {
"type": "object",
"properties": {
"disponivel_cents": {
"type": "integer"
},
"bloqueado_cents": {
"type": "integer"
},
"total_cents": {
"type": "integer"
}
}
},
"clientes": {
"type": "object",
"properties": {
"qtd": {
"type": "integer"
},
"disponivel_cents": {
"type": "integer"
},
"bloqueado_cents": {
"type": "integer"
},
"total_cents": {
"type": "integer"
}
}
},
"total_custodiado_cents": {
"type": "integer"
},
"movimentos": {
"type": "integer"
},
"ultimo_movimento_em": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}GET /saldo/extrato
Balance statement (movements, newest first)
Parameters
| Field | In | Required | Description |
|---|---|---|---|
customer_ref | query | false | |
limit | query | false |
Responses
200 OK
JSON schema · 200
{
"type": "object",
"properties": {
"movimentos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"valor_cents": {
"type": "integer"
},
"sentido": {
"type": "string",
"enum": [
"credito",
"debito"
]
},
"tipo": {
"type": "string",
"enum": [
"cashin",
"payout",
"cashout",
"estorno",
"ajuste"
]
},
"origem_tipo": {
"type": [
"string",
"null"
]
},
"origem_id": {
"type": [
"string",
"null"
]
},
"disponivel_em": {
"type": "string",
"format": "date-time"
},
"disponivel": {
"type": "boolean"
},
"descricao": {
"type": [
"string",
"null"
]
},
"criado_em": {
"type": "string",
"format": "date-time"
}
}
}
},
"proxima_pagina": {
"type": [
"string",
"null"
]
}
}
}401 Missing or invalid key
POST /saldo/sacar-cripto
Withdraw BRL balance as crypto to a self-custodial wallet
Converte saldo BRL disponível em cripto. Escolha uma rota entregavel=true de GET /cashin/catalog e informe carteira/memo por saque; carteira fixa não é necessária. Liquid/DePix não são suportados. Debita amount_cents mais a taxa da casa antes da entrega; conversão e custos da rota afetam a quantidade final. Acompanha pelo cashin_id em GET /cashin/{cashin_id}/status. Compartilha o espaço de external_id com cobranças. Não há endpoint público de prévia de saque.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
amount_cents | integer | true | Valor BRL em centavos inteiros. Mínimo efetivo depende da chave, taxas e rota. Consulte GET /keys/me e min_brl_cents/limits retornados; não fixe o mínimo do exemplo. |
chain | string | false | Network (aliases accepted: sol, trc20, erc20, bep20, arbitrum, base…). Default: |
asset | string | false | Asset code in lowercase (usdt, usdc, btc, eth, sol…), as listed by GET /cashin/catalog. Default: |
payout_address | string | true | Destination wallet, validated for the network. |
tax_number | string | true | CPF (11 digits) or CNPJ (14) of the customer who owns the balance. |
customer_ref | string | false | Sub-account to debit. Omit for the key's main balance. |
external_id | string | false | Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado. |
payout_tag | string | false | Memo/tag do destino. OBRIGATORIO nas redes coletivas — XRP, XLM, TON, ATOM, HBAR, ALGO, EOS, KAVA, LUNA — onde a carteira de destino e compartilhada e o memo e quem identifica o dono. Sem ele a API responde 400 |
max_debited_cents | integer | false | Limite opcional do débito BRL (valor + taxa da casa). Excesso retorna 409 taxa_alterada. Não trava câmbio nem quantidade de tokens. |
sandbox_scenario | string | false | Only for a sandbox key. GET /sandbox provides the scenario matrix by flow. Omit in production. All prices, payments and withdrawals remain fictitious. Values: |
Request schema
{
"type": "object",
"required": [
"amount_cents",
"payout_address",
"tax_number"
],
"properties": {
"amount_cents": {
"type": "integer",
"minimum": 100,
"description": "Valor BRL em centavos inteiros. Mínimo efetivo depende da chave, taxas e rota. Consulte GET /keys/me e min_brl_cents/limits retornados; não fixe o mínimo do exemplo."
},
"chain": {
"type": "string",
"default": "polygon",
"description": "Network (aliases accepted: sol, trc20, erc20, bep20, arbitrum, base…)."
},
"asset": {
"type": "string",
"default": "usdt",
"description": "Asset code in lowercase (usdt, usdc, btc, eth, sol…), as listed by GET /cashin/catalog."
},
"payout_address": {
"type": "string",
"description": "Destination wallet, validated for the network."
},
"tax_number": {
"type": "string",
"description": "CPF (11 digits) or CNPJ (14) of the customer who owns the balance."
},
"customer_ref": {
"type": "string",
"maxLength": 80,
"description": "Sub-account to debit. Omit for the key's main balance."
},
"external_id": {
"type": "string",
"maxLength": 64,
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado."
},
"payout_tag": {
"type": "string",
"maxLength": 120,
"description": "Memo/tag do destino. OBRIGATORIO nas redes coletivas — XRP, XLM, TON, ATOM, HBAR, ALGO, EOS, KAVA, LUNA — onde a carteira de destino e compartilhada e o memo e quem identifica o dono. Sem ele a API responde 400 `memo_obrigatorio` antes de criar qualquer cobranca. Em XRP e a destination tag: inteiro de 0 a 4294967295. Aliases aceitos: `memo`, `tag`, `destination_tag`. O catalogo marca essas rotas com `memoRequired: true`."
},
"max_debited_cents": {
"type": "integer",
"minimum": 0,
"description": "Limite opcional do débito BRL (valor + taxa da casa). Excesso retorna 409 taxa_alterada. Não trava câmbio nem quantidade de tokens."
},
"sandbox_scenario": {
"type": "string",
"enum": [
"success",
"delayed",
"held",
"expired",
"refunded",
"failed",
"payer_mismatch",
"settlement_failed",
"settlement_uncertain",
"route_unavailable",
"provider_unavailable"
],
"description": "Only for a sandbox key. GET /sandbox provides the scenario matrix by flow. Omit in production. All prices, payments and withdrawals remain fictitious."
}
}
}Responses
200 Debited and queued for delivery. Same view as POST /cashin/charge (cashin_id, status = `paid` — the balance is the payment —, chain, asset, payout_address, amount_cents, settlement_status, settlement_tx_hash) plus `fee_cents` (house fee debited), `debited_cents` (amount + fee), `fonte: "saldo"`, `destino: "cripto"`, `customer_ref`. Follow `settlement_status` on GET /cashin/{cashin_id}/status until `sent`.
JSON schema · 200
{
"allOf": [
{
"$ref": "#/components/schemas/Cobranca"
},
{
"type": "object",
"properties": {
"settlement_status": {
"type": [
"string",
"null"
],
"description": "Estado do crédito/entrega: sent concluiu; incerto exige conciliação. PIX pago e entrega são estados distintos.",
"enum": [
"pending",
"sending",
"entregando",
"sent",
"incerto",
"failed",
null
]
},
"settlement_tx_hash": {
"type": [
"string",
"null"
],
"description": "Hash on-chain da entrega (ou id interno quando a entrega é pela corretora)."
},
"fee_cents": {
"type": "integer",
"description": "Taxa de saque da casa debitada além de amount_cents."
},
"debited_cents": {
"type": "integer",
"description": "amount_cents mais a taxa de saque da casa."
}
}
}
]
}400 rede_indisponivel | asset_invalido | payout_address_invalido | documento_invalido | valor_abaixo_do_minimo · `memo_obrigatorio` — a rede exige memo/tag e ele nao veio (ou veio invalido).
402 saldo_insuficiente — available < amount + fee. Body carries `saldo` and `fee_cents`.
409 external_id_divergente
423 carencia_primeiro_deposito — first-deposit hold (only keys with a contractual holding period); `libera_em` says when.
503 entrega_indisponivel — no stock/route to deliver right now; nothing was debited.
POST /saldo/transferir
Transferência interna entre subcontas e a casa (sem PIX)
Move saldo DISPONÍVEL entre um cliente final (customer_ref) e a casa ("casa" = a própria chave), ou entre dois clientes, sem passar pelo PIX. Uso típico: cobrar a sua taxa do cliente (cliente → casa), bonificar ou devolver (casa → cliente). O congelado (retenção de 24h / MED) não se move. Subconta na carência do primeiro depósito não transfere (423 — só chaves com carência contratual). Idempotente por external_id. Dispara o evento saldo.transferido.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
from_customer_ref | string | true |
|
to_customer_ref | string | true |
|
amount_cents | integer | true | |
descricao | string | false | Aparece no extrato das duas pontas. |
external_id | string | false | Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado. |
Request schema
{
"type": "object",
"required": [
"from_customer_ref",
"to_customer_ref",
"amount_cents"
],
"properties": {
"from_customer_ref": {
"type": "string",
"description": "`customer_ref` de origem, ou `\"casa\"`."
},
"to_customer_ref": {
"type": "string",
"description": "`customer_ref` de destino, ou `\"casa\"`."
},
"amount_cents": {
"type": "integer",
"minimum": 1
},
"descricao": {
"type": "string",
"maxLength": 140,
"description": "Aparece no extrato das duas pontas."
},
"external_id": {
"type": "string",
"maxLength": 64,
"description": "Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado."
}
}
}Responses
201 Transferida.
JSON schema · 201
{
"type": "object",
"properties": {
"transfer_id": {
"type": "string"
},
"from_customer_ref": {
"type": [
"string",
"null"
]
},
"to_customer_ref": {
"type": [
"string",
"null"
]
},
"amount_cents": {
"type": "integer"
},
"descricao": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"movimentos": {
"type": "object"
},
"saldos": {
"type": "object",
"description": "Saldo das duas pontas depois da transferência."
}
}
}200 Replay idempotente (`idempotente: true`).
400 `valor_invalido` · `origem_igual_destino` · `custodia_desligada`.
409 `saldo_insuficiente` (com `disponivel_cents`/`bloqueado_cents`) · `external_id_divergente`.
423 `carencia_primeiro_deposito` na subconta de origem.
GET /sandbox
Discover sandbox capabilities
Supported journeys, scenarios by flow, QR semantics, limits and simulation control routes.
Responses
200 Sandbox result; sandbox=true; no real funds move.
JSON schema · 200
{
"type": "object",
"additionalProperties": true
}401 Missing or invalid key.
403 Requires a sandbox key.
404 Operation not found for this key.
409 State conflict or divergent idempotency parameters.
503 Simulator unavailable; never falls through to a real provider.
POST /sandbox/cashin/{cashin_id}/pay
Simulate payment of a test PIX charge
Only the owning sandbox key can confirm. Replays never duplicate credits. This endpoint cannot confirm a production payment.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
cashin_id | path | true |
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
payer_tax_number | string | false | Optional synthetic payer document; a mismatch simulates a refund. |
Request schema
{
"type": "object",
"properties": {
"payer_tax_number": {
"type": "string",
"description": "Optional synthetic payer document; a mismatch simulates a refund."
}
},
"required": []
}Responses
200 Sandbox result; sandbox=true; no real funds move.
JSON schema · 200
{
"type": "object",
"additionalProperties": true
}401 Missing or invalid key.
403 Requires a sandbox key.
404 Operation not found for this key.
409 State conflict or divergent idempotency parameters.
503 Simulator unavailable; never falls through to a real provider.
GET /sandbox/events
Inspect generated sandbox events
Returns generated events even if no webhook was configured. Use /webhooks/deliveries for actual callback attempts.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
limit | query | false |
Responses
200 Sandbox result; sandbox=true; no real funds move.
JSON schema · 200
{
"type": "object",
"additionalProperties": true
}401 Missing or invalid key.
403 Requires a sandbox key.
404 Operation not found for this key.
409 State conflict or divergent idempotency parameters.
503 Simulator unavailable; never falls through to a real provider.
POST /sandbox/operations/{operation_id}/resolve
Resolve an uncertain sandbox operation
Only a test operation already in an uncertain state can be resolved. Same outcome can be replayed safely.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
operation_id | path | true |
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
outcome | string | true | Values: |
Request schema
{
"type": "object",
"properties": {
"outcome": {
"type": "string",
"enum": [
"sent",
"failed"
]
}
},
"required": [
"outcome"
]
}Responses
200 Sandbox result; sandbox=true; no real funds move.
JSON schema · 200
{
"type": "object",
"additionalProperties": true
}400 outcome ausente ou diferente de sent e failed: erro outcome_invalido, acao corrigir, sandbox=true. A checagem vem antes de procurar a operação, e nada muda no simulador (desde a 1.44.2; antes, um corpo sem outcome podia responder 200 sem resolver nada).
401 Missing or invalid key.
403 Requires a sandbox key.
404 Operation not found for this key.
409 State conflict or divergent idempotency parameters.
503 Simulator unavailable; never falls through to a real provider.
GET /sandbox/qr/{cashin_id}.svg
Non-payable sandbox QR image
Encodes SANDBOX:NAO_PAGAVEL:
Parameters
| Field | In | Required | Description |
|---|---|---|---|
cashin_id | path | true |
Responses
200 Synthetic SVG QR.
POST /sandbox/reset
Reset this key’s fictitious state
Deletes only the owning key’s simulated state. Previously queued webhook deliveries retain their history. Production keys are refused.
JSON body
| Field | Type | Required | Description |
|---|---|---|---|
confirm | boolean | true |
Request schema
{
"type": "object",
"properties": {
"confirm": {
"type": "boolean",
"const": true
}
},
"required": [
"confirm"
]
}Responses
200 Sandbox result; sandbox=true; no real funds move.
JSON schema · 200
{
"type": "object",
"additionalProperties": true
}401 Missing or invalid key.
403 Requires a sandbox key.
404 Operation not found for this key.
409 State conflict or divergent idempotency parameters.
503 Simulator unavailable; never falls through to a real provider.
GET /v1/verificar/{e2e}
Confirmar que um PIX aconteceu (aberto, sem chave)
Serve para checar um pagamento sem depender da palavra de quem diz ter pago. Não exige conta nem chave.
Não devolve chave PIX, nome completo nem documento: prova o pagamento sem expor as partes.
Quando não encontra, a resposta diz explicitamente que o PIX pode ter sido feito por outra instituição — ausência aqui não é prova de que não existiu.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
e2e | path | true | Identificador do Banco Central: E + 32 caracteres. |
Responses
200 Pagamento liquidado pela Lunium.
JSON schema · 200
{
"type": "object",
"properties": {
"verificado": {
"type": "boolean"
},
"pago": {
"type": "boolean"
},
"e2e": {
"type": "string",
"description": "Identificador end-to-end do Banco Central, ecoado (letra E + código do comprovante). Qualquer terceiro pode revalidá-lo neste mesmo endpoint."
},
"valor_brl": {
"type": "string"
},
"pago_em": {
"type": "string",
"format": "date-time",
"example": "2026-08-01T22:35:49-03:00",
"description": "ISO 8601 COM offset (horario de Brasilia). Nunca suponha UTC nem hora local: o offset vem explicito. / (en) ISO 8601 with explicit offset (Brasilia time)."
},
"recebedor_iniciais": {
"type": [
"string",
"null"
]
},
"instituicao": {
"type": [
"string",
"null"
]
},
"liquidado_por": {
"type": "string"
},
"comprovante_url": {
"type": [
"string",
"null"
]
}
}
}404 Não liquidado pela Lunium (pode ter sido por outra instituição).
400 Formato inválido.
GET /webhooks/deliveries
Historico de entregas de webhook desta chave
Diagnostico do que saiu, o que falhou e por que. Nao devolve o corpo do evento — para reenviar o corpo original use o retry.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
status | query | false | |
event | query | false | |
limit | query | false |
Responses
200 Entregas, mais recentes primeiro.
JSON schema · 200
{
"type": "object",
"properties": {
"deliveries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntregaWebhook"
}
},
"failed_count": {
"type": "integer",
"description": "Quantas na resposta esgotaram as tentativas."
}
}
}400 Filtro invalido
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /webhooks/deliveries/{event_id}/retry
Reenviar um evento
Tenta entregar durante a própria chamada e responde com o resultado. Se falhar de novo, a entrega volta para a fila com 12 tentativas novas. Recusa reenviar o que ja foi confirmado com 2xx.
Parameters
| Field | In | Required | Description |
|---|---|---|---|
event_id | path | true |
Responses
200 Entregue agora.
JSON schema · 200
{
"type": "object",
"properties": {
"event_id": {
"type": "string"
},
"delivered": {
"type": "boolean",
"const": true
},
"status_code": {
"type": "integer"
},
"ms": {
"type": "integer"
},
"delivery_id": {
"type": "string"
}
}
}202 Nao entregue agora; recolocada na fila.
404 Nao encontrado para esta chave
JSON schema · 404
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}409 Ja entregue — reenviar duplicaria
JSON schema · 409
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}POST /webhooks/test
Disparar um evento de teste agora
Envia um webhook.test para a sua webhook_url pelo MESMO transporte da producao e devolve o que o seu endpoint respondeu (status e latencia). Nenhum dinheiro se move e nada entra na fila. Use antes de ligar a primeira cobranca real. Maximo de 6 por minuto.
Responses
200 Seu endpoint respondeu 2xx.
JSON schema · 200
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"event_id": {
"type": "string"
},
"delivery_id": {
"type": "string"
},
"url": {
"type": "string"
},
"status_code": {
"type": "integer"
},
"ms": {
"type": "integer"
}
}
}400 webhook_url nao configurada
JSON schema · 400
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}429 Mais de 6 testes por minuto
JSON schema · 429
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}502 Seu endpoint nao respondeu 2xx — o corpo diz exatamente o que aconteceu.
JSON schema · 502
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}401 X-API-Key ausente, desconhecida ou incorreta.
JSON schema · 401
{
"type": "object",
"description": "Erro da API; campos podem variar por caminho, inclusive respostas de infraestrutura. Combine código HTTP com erro e acao quando presentes; detail é para exibição, não decisão. Tolere códigos novos.",
"properties": {
"erro": {
"type": "string",
"description": "Codigo estavel de erro. Ramifique por ele, nunca pelo texto de detail. Esta lista e gerada a partir dos codigos que a API realmente emite.",
"x-known-values": [
"amount_invalido",
"asset_invalido",
"br_code_indisponivel",
"br_code_sem_valor",
"brl_amount_invalido",
"campos_conflitantes",
"campos_obrigatorios",
"carencia_primeiro_deposito",
"cashin_indisponivel",
"cashout_indisponivel",
"catalogo_indisponivel",
"chave_ausente",
"chave_desconhecida",
"chave_incorreta",
"chave_nao_encontrada",
"conflito",
"consulta_indisponivel",
"corpo_grande_demais",
"cotacao_expirada",
"cotacao_indisponivel",
"custodia_desligada",
"deposit_obrigatorio",
"destino_invalido",
"documento_invalido",
"em_processamento",
"email_invalido",
"endpoint_nao_respondeu",
"erro_interno",
"external_id_divergente",
"formato_invalido",
"ja_entregue",
"limite_consultas",
"limite_de_chaves_teste",
"limite_diario",
"limite_diario_recebedor",
"limite_do_pagador",
"limite_indisponivel",
"liquidante_indisponivel",
"mandate_contraparte_nao_autorizada",
"mandate_valor_acima_do_teto",
"memo_obrigatorio",
"metodo_nao_permitido",
"muitas_tentativas",
"nao_autenticado",
"nao_encontrado",
"nao_permitido",
"nao_processavel",
"origem_igual_destino",
"pagador_recusado_pelo_provedor",
"payer_tax_invalido",
"payer_tax_number_invalido",
"payout_address_invalido",
"payout_address_obrigatorio",
"payout_nao_liberado",
"payout_recusado",
"pix_key_invalida",
"pix_key_obrigatoria",
"provedor_indisponivel",
"provedor_sem_resposta",
"rate_limit",
"rede_indisponivel",
"refund_address_invalida",
"requisicao_invalida",
"saldo_insuficiente",
"sandbox_sem_cashin",
"sandbox_sem_saldo",
"sandbox_sem_saque",
"saque_comissao_diario",
"saque_indisponivel",
"status_invalido",
"taxa_alterada",
"tempo_esgotado",
"temporariamente_indisponivel",
"tipo_ambiguo",
"valor_abaixo_do_minimo",
"valor_acima_do_maximo",
"valor_invalido",
"webhook_nao_configurado",
"webhook_url_invalida"
]
},
"acao": {
"type": "string",
"enum": [
"corrigir",
"repetir",
"esperar",
"parar",
"falar_com_suporte"
],
"description": "corrigir = o pedido esta errado, repetir identico nunca funciona · repetir = falha transitoria nossa, tente de novo · esperar = cota renova, volte depois · parar = nao repita, fale com a gente · falar_com_suporte = nao repita em laco; preserve request_id e external_id e encaminhe a Lunium (ex.: config_provedor)."
},
"detail": {
"type": "string",
"description": "Texto para humano. Nunca ramifique por ele."
},
"limits": {
"type": "object",
"description": "Presente nos erros de limite, ja convertido na moeda da ordem."
},
"docs": {
"type": "string",
"format": "uri"
},
"request_id": {
"type": "string",
"description": "Identificador desta requisicao. Vai tambem no header X-Request-ID e e o que citar no suporte. Se voce enviar X-Request-ID no formato [A-Za-z0-9._:-]{8,64}, ele e preservado de ponta a ponta.",
"examples": [
"req_62f05f21b3794830a241"
]
},
"code": {
"type": "string",
"deprecated": true,
"description": "Alias LEGADO de `erro` — SUNSET: deixa de ser enviado em 2026-11-09. NAO ramifique por ele; use `erro` (canonico). Nunca vem sem `erro`."
}
}
}Acompanhamento humano e ao vivo
Grupo humano fortemente recomendado: a Lunium ou o parceiro pode criar o grupo do projeto e adicionar @luniumb2b e @luniumb2c, além de @LuniumNotifyBot. Veja o roteiro do grupo. Para acompanhamento, use o monitor privado de /keys/me e implemente webhooks, painel ao vivo e conciliação. Não compartilhe chaves, segredos ou o monitor com pessoas não autorizadas.