luniumpay-com Comissão (sub fee) API

openapi: 3.2.0
info:
  title: Luniumpay Com Comissão (sub fee) 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 Comissão (sub fee) 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: Comissão (sub fee)
  description: A taxa que um parceiro põe por cima da taxa da Lunium, paga pelo usuário final dele, e o saque dessa comissão em cripto.
paths:
  /comissao:
    get:
      tags:
      - Comissão (sub fee)
      summary: Saldo da sub fee (comissão do parceiro)
      security:
      - ApiKey: []
      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.'
      responses:
        '200':
          description: Saldo, política e minimo de saque
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comissao'
        '401':
          description: Sem chave
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
      operationId: getComissao
      x-operation-id-source: derived
    servers:
    - url: https://api.luniumpay.com
      description: Produção
  /comissao/extrato:
    get:
      tags:
      - Comissão (sub fee)
      summary: Extrato da comissão
      security:
      - ApiKey: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      - name: before
        in: query
        schema:
          type: string
        description: id do último item da página anterior
      responses:
        '200':
          description: Lançamentos, do mais recente para o mais antigo
          content:
            application/json:
              schema:
                type: object
                properties:
                  itens:
                    type: array
                    items:
                      $ref: '#/components/schemas/ComissaoEvento'
                  has_more:
                    type: boolean
                  next_before:
                    type:
                    - string
                    - 'null'
        '401':
          description: Sem chave
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
      operationId: getComissaoExtrato
      x-operation-id-source: derived
    servers:
    - url: https://api.luniumpay.com
      description: Produção
  /comissao/sacar:
    post:
      tags:
      - Comissão (sub fee)
      summary: Sacar a comissão em cripto
      security:
      - ApiKey: []
      description: '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.'
      requestBody:
        required: true
        content:
          application/json:
            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':
          description: Saque criado e em entrega
          content:
            application/json:
              schema:
                type: object
                properties:
                  saque:
                    $ref: '#/components/schemas/Cobranca'
                  comissao:
                    $ref: '#/components/schemas/Comissao'
        '400':
          description: valor_invalido | valor_abaixo_do_minimo (traz min_saque_cents) | rede_indisponivel | asset_invalido | payout_address_invalido | sandbox_sem_saque
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '402':
          description: saldo_insuficiente — comissão disponível menor que o pedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '409':
          description: external_id_divergente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '429':
          description: saque_comissao_diario — traz proximo_saque_em
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '503':
          description: provedor_indisponivel — sem cotação para aferir o mínimo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
      operationId: postComissaoSacar
      x-operation-id-source: derived
    servers:
    - url: https://api.luniumpay.com
      description: Produção
components:
  schemas:
    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.
    Comissao:
      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
          properties:
            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).
      required:
      - disponivel_cents
      - creditado_cents
      - sacado_cents
      - operacoes
      - moeda
      - sandbox
      - pode_sacar_agora
      - politica
    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`.'
    ComissaoEvento:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
          enum:
          - credito
          - estorno
          - saque
          - saque_estorno
        valor_cents:
          type: integer
          description: 'Com sinal: crédito +, estorno −, saque −, saque_estorno +.'
        sentido:
          type: string
          enum:
          - credito
          - debito
        origem_id:
          type: string
          description: ci_... da cobranca de compra ou do saque em cripto, po_... do saque por PIX, uuid da ordem de venda, ou o id do saque de comissao (kind saque).
        base_cents:
          type: integer
        partner_fee_bps:
          type: integer
        status:
          type: string
        motivo:
          type:
          - string
          - 'null'
          description: 'Origem do lancamento: vazio (compra), ''venda: cripto -> PIX'', ''saida: saque por PIX'', ''saida: saque em cripto'', ou o motivo do estorno.'
        criado_em:
          type: string
          format: date-time
  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