Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Luniumpay Com Cash In API
version: 1.48.0
contact:
name: Lunium
email: contato@luniumpay.com
url: https://luniumpay.com/integrar?utm_source=openapi&utm_medium=spec
x-documentation-revision: 2026-09-17.4
x-lunium-partners:
name: Lunium Partners — comunidade oficial de integradores
url: https://t.me/+FerOZMRRP_g5MDk5
description: Avisos operacionais, mudanças de contrato e troca entre parceiros. Nunca publique uma chave de API no grupo.
description: 'Operations tagged Cash-in across 2 of this provider''s published API definitions: api.json, luniumpay-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.luniumpay.com
description: Produção
security:
- ApiKey: []
tags:
- name: Cash-in
description: PIX entra, cripto sai.
paths:
/cashin/charge:
post:
tags:
- Cash-in
operationId: criarCobranca
summary: Gerar cobrança PIX para custódia BRL ou entrega de cripto
description: '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.
Subfee exclusiva do depósito Pix em saldo BRL, em basis points (100 = 1%). Padrão 0, máximo 1000. Aplicada ao valor recebido após a taxa fixa Lunium, descontada antes do crédito no saldo. Independente de compra, venda e saque. Congelada na criação; comissão creditada somente após liberação e crédito concluído (paid/sent).'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- amount_cents
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. Vale para qualquer rota do catálogo: BTC na rede Bitcoin = asset "btc" + chain "btc" (apelido "bitcoin" aceito).'
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. Obrigatório no nível Padrão. No nível VIP Master (GET /keys/me → nivel_conta.nivel = "vip_master") é opcional; se informado, continua validado e sujeito a contestação ou bloqueio.
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: 'Legado: campo ignorado. A retenção exigida pela faixa do pagador é automática, inclusive com false. Não bloqueie a criação pelo limite sem retenção; consulte max_amount_cents/held_qr e mostre held_hours e hold_hours/liberar_em antes do pagamento.'
deprecated: true
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.
delivery_mode:
type: string
enum:
- full
- split
default: full
description: 'Somente para chain="liquid" (DePix). "full" (padrão) entrega o DePix direto na carteira informada, com o valor cheio — a taxa da chave não é descontada. "split" faz o caminho receber-e-repassar: a Lunium recebe o DePix, desconta a taxa da chave (fixa + percentual) e envia o líquido para payout_address; net_cents na resposta é exatamente o que o destinatário recebe. Em split, payout_address é obrigatório. Sem o campo, vale o padrão da sua chave.'
responses:
'200':
description: 'Cobrança criada: qr_copypaste é o PIX a mostrar.'
content:
application/json:
schema:
$ref: '#/components/schemas/Cobranca'
'403':
description: 'Limite do pagador excedido (limite_do_pagador) ou pagador bloqueado pela Lunium para esta integração (pagador_bloqueado: nenhuma cobrança é criada; não repita com o mesmo CPF/CNPJ).'
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
'400':
description: 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). · `valor_acima_do_maximo` — o valor passou do teto por operação; a resposta traz `max_brl_cents` (o maior valor aceito). No VIP Master o teto é o do projeto (GET /keys/me → nivel_conta.beneficios.teto_por_cobranca_cents).
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
'401':
description: X-API-Key ausente, desconhecida ou incorreta.
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
'502':
description: '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.'
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
'503':
description: catalogo_indisponivel / cotacao_indisponivel — corretora sem cotação neste instante; repita.
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
'409':
description: external_id divergente.
security:
- ApiKeyAuth: []
x-lunium-capability:
- pix_to_usdt
- pix_to_usdc
x-lunium-intents:
- buy_crypto
- onramp
- fiat_to_crypto
x-lunium-reward-eligible: true
servers:
- url: https://api.luniumpay.com
description: Produção
/cashin/catalog:
get:
tags:
- Cash-in
operationId: catalogoCompra
security:
- ApiKeyAuth: []
summary: Catálogo do cash-in (o que entregamos ao receber PIX)
description: 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':
description: Catálogo de compra.
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogoCompra'
'401':
description: X-API-Key ausente, desconhecida ou incorreta.
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
servers:
- url: https://api.luniumpay.com
description: Produção
/cashin/events:
get:
tags:
- Cash-in
operationId: eventosDaChave
security:
- ApiKeyAuth: []
summary: Feed de eventos da sua chave (operação)
description: 'Ú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:
- name: limit
in: query
required: false
schema:
type: integer
default: 60
maximum: 200
description: Quantos eventos devolver (padrão 60).
responses:
'200':
description: Eventos recentes.
content:
application/json:
schema:
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':
description: X-API-Key ausente, desconhecida ou incorreta.
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
servers:
- url: https://api.luniumpay.com
description: Produção
components:
schemas:
CatalogoCompra:
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
min_brl_cents:
type: integer
description: Menor cobranca em REAIS que esta rota entrega, ja com as taxas desta chave. E o mesmo numero de POST /cashin/preview (min_brl_cents) e o mesmo que aceita ou recusa a cobranca. Ausente quando ainda nao foi calculado para a rota; nesse caso leia a previa. Publicado desde 24/09/2026 para USDT e USDC.
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
description: Taxa de retirada da corretora nesta rede, em unidades do ativo. Distinta das taxas da Lunium e do parceiro; já participa de minBuyAmount.
withdrawMin:
type: string
description: Mínimo de retirada da corretora nesta rede, em unidades do ativo. Não é o mínimo de depósito cripto do cash-out.
withdrawMax:
type: string
description: Teto de retirada publicado para a rede, em unidades do ativo. Não substitui o teto em BRL por operação, limites do pagador, saldo ou mandate. Ausência não significa ilimitado.
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
min_brl_cents:
type: integer
description: Menor cobranca em REAIS que esta rota entrega, ja com as taxas desta chave. E o mesmo numero de POST /cashin/preview (min_brl_cents) e o mesmo que aceita ou recusa a cobranca. Ausente quando ainda nao foi calculado para a rota; nesse caso leia a previa. Publicado desde 24/09/2026 para USDT e USDC.
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.
Erro:
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
- criacao_recusada
- custodia_desligada
- deposit_obrigatorio
- destino_invalido
- devolucao_indisponivel
- documento_invalido
- em_conciliacao
- 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
- referencia_recusada
- 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
- tax_number_obrigatorio
- 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`.'
Cobranca:
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: Subfee exclusiva do depósito Pix em saldo BRL, em basis points (100 = 1%). Padrão 0, máximo 1000. Aplicada ao valor recebido após a taxa fixa Lunium, descontada antes do crédito no saldo. Independente de compra, venda e saque. Congelada na criação; comissão creditada somente após liberação e crédito concluído (paid/sent). Para compra direta, este campo congela partner_fee_bps.
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
delivery_mode:
type: string
enum:
- full
- split
description: 'Só em chain="liquid": como o DePix foi entregue. Ausente nas outras redes.'
net_cents:
type: integer
description: 'Só em chain="liquid" com delivery_mode="split": quanto o destinatário recebe em DePix, já sem a taxa. É este valor que a Lunium envia on-chain.'
fee_total_cents:
type: integer
description: 'Só em chain="liquid" com delivery_mode="split": tudo que saiu do bruto (taxa fixa + percentual). net_cents + fee_total_cents == amount_cents.'
lunium_fee_cents:
type: integer
minimum: 0
description: Parte da taxa em centavos para depósito Pix em saldo BRL; calculada com os valores congelados da cobrança.
partner_fee_cents:
type: integer
minimum: 0
description: Parte da taxa em centavos para depósito Pix em saldo BRL; calculada com os valores congelados da cobrança.
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-API-Key
description: Chave criada em `POST /keys`. Aparece uma única vez — guarde no momento da criação.
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your key. `lun_test_…` is sandbox (moves nothing); `lun_…` is production.
externalDocs:
description: Mínimos e máximos por moeda e rede
url: https://docs.luniumpay.com/minimos
x-refined-from:
- api.json
- luniumpay-com-openapi.json