luniumpay-com Keys API

openapi: 3.2.0
info:
  title: Luniumpay Com Keys 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 Keys 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: Keys
paths:
  /keys/me:
    patch:
      summary: Atualiza a chave (nome, settlement, webhook, rotações)
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            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.'
                partner_cashout_fee_bps:
                  type: integer
                  minimum: 0
                  maximum: 1000
                  description: Sub fee do parceiro na VENDA (cripto -> PIX), em basis points, POR CIMA da taxa da Lunium. Congelada em cada ordem no momento da criacao; vale para ordem nova. Nao se aplica a venda por QR copia e cola. 0 desliga.
                partner_saque_fee_bps:
                  type: integer
                  minimum: 0
                  maximum: 1000
                  description: Sub fee do parceiro na SAIDA DA CUSTODIA (saque por PIX em POST /payouts e saque em cripto em POST /saldo/sacar-cripto), em basis points, debitada do saldo POR CIMA da taxa da Lunium. Credita quando o saque conclui. 0 desliga.
                partner_deposito_fee_bps:
                  type: integer
                  minimum: 0
                  maximum: 1000
                  default: 0
                  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).
      responses:
        '200':
          description: Chave atualizada. Pode trazer webhook_secret (uma única vez) e monitor_url novo.
        '400':
          description: Campos inválidos ou nada para atualizar.
          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'
      operationId: updateMyKey
      description: 'Quatro subfees independentes: compra (partner_fee_bps), depósito Pix em saldo BRL (partner_deposito_fee_bps), venda (partner_cashout_fee_bps) e saída da custódia (partner_saque_fee_bps). Configure via PATCH /keys/me. Depósito credita comissão somente após Pix liberado e saldo creditado (paid/sent), uma vez por cobrança, com a taxa congelada na criação. Venda exige PIX pago; saída exige saque concluído. Não há cobrança retroativa. Limite e política de saque em politica.saque e min_saque_cents.'
      tags:
      - Keys
    servers:
    - url: https://api.luniumpay.com
      description: Produção
  /keys/sandbox:
    post:
      summary: Get a sandbox API key — one call, no API key needed
      description: '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 .'
      requestBody:
        required: true
        content:
          application/json:
            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':
          description: Sandbox key created
          content:
            application/json:
              schema:
                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':
          description: 'email_obrigatorio: email missing or invalid. Send the e-mail of the person who will test, e.g. {"email": "you@company.com"}.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
              example:
                erro: email_obrigatorio
                acao: corrigir
                campo: email
                detail: 'Informe o e-mail de quem vai testar: {"email": "voce@empresa.com"}. É por ele que mandamos o manual, o fluxograma e o passo a passo da integração.'
        '429':
          description: Too many keys from this IP today
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
      operationId: createSandboxKey
      tags:
      - Keys
    servers:
    - url: https://api.luniumpay.com
      description: Produção
  /keys/painel-link:
    post:
      summary: Receber o link do painel por e-mail (sem chave)
      description: 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.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: Pedido aceito (genérico).
        '400':
          description: E-mail inválido.
        '429':
          description: Limite por hora.
      tags:
      - Keys
      operationId: postKeysPainelLink
      x-operation-id-source: derived
    servers:
    - url: https://api.luniumpay.com
      description: Produção
components:
  schemas:
    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`.'
  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