luniumpay-com Payouts API

openapi: 3.2.0
info:
  title: Luniumpay Com Payouts 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 Payouts 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: Payouts
paths:
  /payouts:
    post:
      summary: Send a PIX directly (no crypto leg)
      description: '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.'
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            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':
          description: 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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '409':
          description: '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.'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Erro'
                - type: object
                  properties:
                    payout_id:
                      type: string
                      description: Original payout identifier.
                    recovery_endpoint:
                      type: string
                      description: Relative API path of the original payout.
        '401':
          description: X-API-Key ausente, desconhecida ou incorreta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '423':
          description: '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`.'
          content:
            application/json:
              schema:
                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':
          description: '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':
          description: Payout criado ou replay idempotente da operação original.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '400':
          description: Recusa ou falha; leia erro, acao e detail quando presentes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '402':
          description: Recusa ou falha; leia erro, acao e detail quando presentes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '500':
          description: Recusa ou falha; leia erro, acao e detail quando presentes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
      operationId: createPixPayout
      tags:
      - Payouts
    get:
      summary: Lista os payouts desta chave
      security:
      - ApiKeyAuth: []
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - processing
          - sent
          - failed
          - refunded
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
      - name: external_id
        in: query
        schema:
          type: string
          maxLength: 64
        description: 'Recuperacao idempotente: devolve a operacao com este external_id (0 ou 1). Unico por chave e produto, case-sensitive, retido permanentemente.'
      responses:
        '200':
          description: Lista (mais recentes primeiro). Lista vazia = 200, nunca 403.
          content:
            application/json:
              schema:
                type: object
                properties:
                  payouts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payout'
        '401':
          description: X-API-Key ausente, desconhecida ou incorreta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '403':
          description: Payout ainda nao liberado para esta chave.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
      operationId: listPixPayouts
      tags:
      - Payouts
    servers:
    - url: https://api.luniumpay.com
      description: Produção
  /payouts/{payout_id}:
    get:
      summary: State of a payout
      security:
      - ApiKeyAuth: []
      parameters:
      - name: payout_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Estado do saque.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payout'
        '404':
          description: Not found
          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: getPixPayout
      tags:
      - Payouts
    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`.'
    Payout:
      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 fees beyond amount_cents: fee_service_total_cents + fee_provider_cents. Includes partner commission already; do not add it again.'
        fee_service_cents:
          type:
          - integer
          - 'null'
          description: Lunium-only service fee in recorded cents; accounting component. For customer UI and notifications use fee_service_total_cents.
        fee_provider_cents:
          type:
          - integer
          - 'null'
          description: 'Tarifa do provedor: fee_cents menos fee_service_cents menos fee_partner_cents.'
        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
        fee_partner_cents:
          type: integer
          nullable: true
          description: Sub fee do parceiro debitada do saldo neste saque (centavos). Parte de fee_cents.
        fee_service_total_cents:
          type:
          - integer
          - 'null'
          minimum: 0
          description: 'Combined customer service fee: recorded Lunium fee plus partner commission. Preserves original cent rounding and historical pricing; null when the legacy house component is unknown. Included in payout responses and payout.* webhook data, production and sandbox. Add fee_provider_cents once to get fee_cents; do not add fee_partner_cents again.'
  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