EVENT:SUBACCOUNT_PIX_KEY_REJECTED — chave PIX da subconta recusada - Dotfy

Evento entregue nos endpoints do MASTER (a subconta é headless). Para recebê-lo, o endpoint do master precisa estar inscrito em EVENT:SUBACCOUNT_PIX_KEY_REJECTED.

Disparado quando o time da Dotfy recusa uma chave PIX cadastrada pela subconta — em geral por divergência de titularidade (a chave precisa pertencer ao mesmo CNPJ da subconta, regra PIX_KEY_OWNERSHIP_MISMATCH). A chave não fica disponível para saques; cadastre outra via POST {{base_url}}/api/subaccounts/{{subaccount_id}}/pix-keys.

Payload (data):

subaccount.id / subaccount.correlationId / subaccount.name — identificação da subconta.

pixKey (objeto) — a chave recusada (id, type, key).

rejectionReason (string) — presente apenas em eventos de recusa; motivo legível da rejeição.

processedAt (string ISO 8601) — quando a decisão foi processada.

Sigilo: o payload não expõe comissão nem decomposição de taxa do master.

Idempotência: trate X-Webhook-ID como chave de deduplicação (até 5 tentativas com backoff exponencial).

Cobranças da subconta também chegam aos seus endpoints (master): os eventos EVENT:CHARGE_CREATED, EVENT:CHARGE_PAID e EVENT:CHARGE_EXPIRED de uma cobrança emitida por uma subconta são entregues nos endpoints do master e trazem um bloco adicional subaccount em data, identificando a origem:

{
  "event": "EVENT:CHARGE_PAID",
  "timestamp": "2026-05-07T15:10:00.000Z",
  "data": {
    "id": "clxxx0042",
    "amount": 2990,
    "status": "PAID",
    "paidAt": "2026-05-07T15:10:00.000Z",
    "subaccount": {
      "id": "sub_clev0a1b2c3d4e5f6g7h8i9j0",
      "correlationId": "loja-parceira-001",
      "name": "Loja Parceira LTDA"
    }
  }
}

O bloco subaccount é puramente aditivo: cobranças de contas comuns (sem subconta) seguem sem ele. Valores continuam em centavos e a taxa exibida é sempre a gatewayFee cheia — a comissão do master nunca aparece aqui.

Forneça seu token bearer no cabeçalho

Authorization

ao fazer requisições para recursos protegidos.

Exemplo:

Authorization: Bearer ********************

curl --location 'https://seu-dominio.com/webhooks/dotfy?event=subaccount-pix-key-rejected' \ --header 'X-Webhook-Signature: t=1714000403000,v1=<hex_de_HMAC_SHA256(secret, timestamp + '\''.'\'' + body)>' \ --header 'X-Webhook-Event: EVENT:SUBACCOUNT_PIX_KEY_REJECTED' \ --header 'X-Webhook-ID: EVENT:SUBACCOUNT_PIX_KEY_REJECTED:sub_clev0a1b2c3d4e5f6g7h8i9j0:1' \ --header 'X-Webhook-Timestamp: 2026-05-07T14:43:00.000Z' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "event": "EVENT:SUBACCOUNT_PIX_KEY_REJECTED", "timestamp": "2026-05-07T14:43:00.000Z", "data": { "subaccount": { "id": "sub_clev0a1b2c3d4e5f6g7h8i9j0", "correlationId": "loja-parceira-001", "name": "Loja Parceira LTDA" }, "pixKey": { "id": "pk_clev0k1l2m3n4o5p6q7r8s9t0", "type": "CNPJ", "key": "12.345.678/0001-90" }, "rejectionReason": "A titularidade da chave não confere com o CNPJ da subconta.", "processedAt": "2026-05-07T14:43:00.000Z" } }'

EVENT:SUBACCOUNT_PIX_KEY_REJECTED — chave PIX da subconta recusada

Requisição

Respostas