Webhook

Webhook de transação

​

Evento enviado quando o status de uma transação muda.

Body·
required
application/json

Estrutura padrão do payload de webhook enviado para clientes

  • data
    required

    Dados específicos do evento (estrutura varia conforme o tipo)

    Dados de webhook para eventos de transação

    • amount
      Type: integer

      Valor em centavos

    • companyId
      Type: string

      ID da empresa

    • createdAt
      Type: string Format: date-time

      Data de criação em horário de Brasília (America/Sao_Paulo), contrato ISO com sufixo Z

    • currency
      enum
      const:  
      BRL

      Moeda (sempre BRL)

      values
      • BRL
    • description
      Type: string nullable

      Descrição da transação

    • id
      Type: string

      ID da transação

    • installments
      Type: integer

      Número de parcelas

    • netTransactionAmount
      Type: integer

      Valor líquido em centavos (após taxas)

    • paidAt
      Type: string Format: date-timenullable

      Data de pagamento (ISO 8601)

    • paymentMethod
      Type: string enum

      Método de pagamento (UPPERCASE)

      values
      • PIX
      • CREDIT_CARD
      • BOLETO
    • status
      Type: string enum

      Status da transação (UPPERCASE)

      values
      • PENDING
      • PROCESSING
      • PAID
      • FAILED
      • CANCELED
      • BLOCKED
      • REFUNDED
      • PRE_CHARGEBACK
      • CHARGEBACK
  • event
    Type: string enum
    required

    Tipo do evento

    values
    • transaction.completed
    • transaction.failed
    • transaction.pending
    • transaction.refunded
    • withdrawal.completed
    • withdrawal.failed
    • withdrawal.canceled
  • eventId
    Type: string Pattern: ^(tx|wd):[^:]+:[A-Z_]+$|^resend:.+$|^evt_.+$
    required

    ID estável do evento de negócio para idempotência. Transação: tx:{transactionId}:{STATUS} (ex. tx:cmxyz:PENDING). Saque: wd:{withdrawalId}:{STATUS}. Reenvio em lote: resend:{entityId}:{STATUS}:{batchId}. Entregas antigas podem usar o formato legado evt_....

  • signature
    Type: string
    required

    Assinatura HMAC-SHA256 do payload (futuro - atualmente vazio)

  • source
    Type: string
    required

    Origem do webhook

  • timestamp
    Type: string Format: date-time
    required

    Timestamp do evento em ISO 8601

  • version
    Type: string
    required

    Versão do formato do webhook

  • retryCount
    Type: integer
    min:  
    0
    max:  
    5

    Número de tentativas de envio (apenas em retries)

Responses
  • 200

    Webhook recebido com sucesso

Request Example for posttransaction.event
{
  "event": "transaction.completed",
  "timestamp": "",
  "data": {
    "id": "",
    "companyId": "",
    "amount": 1,
    "currency": "BRL",
    "status": "PENDING",
    "paymentMethod": "PIX",
    "description": "",
    "netTransactionAmount": 1,
    "installments": 1,
    "createdAt": "",
    "paidAt": ""
  },
  "signature": "",
  "version": "1.0",
  "eventId": "tx:cmk4lcpeb00om3l07aju1c0qb:PAID",
  "retryCount": 0,
  "source": "podpay-gateway"
}
No Body

Webhook recebido com sucesso