luniumpay-com Webhooks API

openapi: 3.2.0
info:
  title: Luniumpay Com Webhooks 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 Webhooks 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: Webhooks
paths:
  /webhooks/deliveries:
    get:
      summary: Historico de entregas de webhook desta chave
      description: Diagnostico do que saiu, o que falhou e por que. Nao devolve o corpo do evento — para reenviar o corpo original use o retry.
      security:
      - ApiKeyAuth: []
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - pending
          - sent
          - failed
      - name: event
        in: query
        schema:
          type: string
          enum:
          - cashin.paid
          - cashin.delayed
          - cashin.held
          - cashin.settled
          - cashin.settlement_failed
          - cashin.expired
          - cashin.refunded
          - cashin.failed
          - cashout.awaiting_deposit
          - cashout.deposit_detected
          - cashout.confirming
          - cashout.processing
          - cashout.under_review
          - cashout.awaiting_refund_address
          - cashout.refunding
          - cashout.completed
          - cashout.receipt_ready
          - cashout.refunded
          - cashout.expired
          - cashout.failed
          - payout.sent
          - payout.failed
          - payout.refunded
          - webhook.test
          - saldo.liberado
          - saldo.congelado
          - saldo.transferido
          - wallet.deposit_credited
          - wallet.payment_completed
          - wallet.payment_failed
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      responses:
        '200':
          description: Entregas, mais recentes primeiro.
          content:
            application/json:
              schema:
                type: object
                properties:
                  deliveries:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntregaWebhook'
                  failed_count:
                    type: integer
                    description: Quantas na resposta esgotaram as tentativas.
        '400':
          description: Filtro invalido
          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: listWebhookDeliveries
      tags:
      - Webhooks
    servers:
    - url: https://api.luniumpay.com
      description: Produção
  /webhooks/deliveries/{event_id}/retry:
    post:
      summary: Reenviar um evento
      description: 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.
      security:
      - ApiKeyAuth: []
      parameters:
      - name: event_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Entregue agora.
          content:
            application/json:
              schema:
                type: object
                properties:
                  event_id:
                    type: string
                  delivered:
                    type: boolean
                    const: true
                  status_code:
                    type: integer
                  ms:
                    type: integer
                  delivery_id:
                    type: string
        '202':
          description: Nao entregue agora; recolocada na fila.
        '404':
          description: Nao encontrado para esta chave
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '409':
          description: Ja entregue — reenviar duplicaria
          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: retryWebhookDelivery
      tags:
      - Webhooks
    servers:
    - url: https://api.luniumpay.com
      description: Produção
  /webhooks/test:
    post:
      summary: Disparar um evento de teste agora
      description: 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.
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Seu endpoint respondeu 2xx.
          content:
            application/json:
              schema:
                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':
          description: webhook_url nao configurada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '429':
          description: Mais de 6 testes por minuto
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Erro'
        '502':
          description: Seu endpoint nao respondeu 2xx — o corpo diz exatamente o que aconteceu.
          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: testWebhook
      tags:
      - Webhooks
    servers:
    - url: https://api.luniumpay.com
      description: Produção
components:
  schemas:
    EntregaWebhook:
      type: object
      properties:
        event_id:
          type: string
        event:
          type: string
          enum:
          - cashin.paid
          - cashin.delayed
          - cashin.held
          - cashin.settled
          - cashin.settlement_failed
          - cashin.expired
          - cashin.refunded
          - cashin.failed
          - cashout.awaiting_deposit
          - cashout.deposit_detected
          - cashout.confirming
          - cashout.processing
          - cashout.under_review
          - cashout.awaiting_refund_address
          - cashout.refunding
          - cashout.completed
          - cashout.receipt_ready
          - cashout.refunded
          - cashout.expired
          - cashout.failed
          - payout.sent
          - payout.failed
          - payout.refunded
          - webhook.test
          - saldo.liberado
          - saldo.congelado
          - saldo.transferido
          - wallet.deposit_credited
          - wallet.payment_completed
          - wallet.payment_failed
          - wallet.withdrawal.completed
          - wallet.withdrawal.failed
        operation_id:
          type: string
          description: Id da operacao que gerou o evento.
        status:
          type: string
          enum:
          - pending
          - sent
          - failed
          description: failed = esgotou as 12 tentativas. Use o retry para recuperar.
        attempts:
          type: integer
        last_error:
          type:
          - string
          - 'null'
        url:
          type: string
          format: uri
        next_attempt_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    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