Configure a validação de saques por Webhook

Este mecanismo permite que sua aplicação autorize ou recuse operações de saída antes que elas sejam processadas pelo Asaas.

Mesmo que uma solicitação tenha sido autenticada com uma chave de API válida, a operação somente será executada após a aprovação da sua aplicação.

📘
Ao concluir este guia, você terá configurado um Webhook para validar operações de saída e saberá responder com a aprovação ou recusa.

Quando utilizar

Utilize este mecanismo para aplicar controles adicionais, como:

validação da origem da operação;
conferência de valores e favorecidos;
limites operacionais;
regras antifraude;
identificação de uso indevido da chave de API.

O mecanismo pode ser aplicado a transferências, pagamentos de contas, pagamentos de QR Codes Pix, recargas de celular e, opcionalmente, estornos Pix.

Como funciona

Sua aplicação solicita a operação e armazena os dados retornados pelo Asaas.
Aproximadamente cinco segundos depois, o Asaas envia um POST para a URL configurada.
Sua aplicação compara o payload recebido com a operação registrada.
Sua aplicação responde com APPROVED ou REFUSED.
O Asaas executa ou cancela a operação conforme a resposta.

⚠️
Caso a chamada ao seu Webhook falhe três vezes ou não retorne um status válido, a operação será cancelada.

1. Ative o mecanismo

Acesse Menu do usuário > Integrações > Mecanismos de segurança.

Informe:

a URL que receberá as solicitações de validação;
o e-mail para notificações de erro;
um token de autenticação.

O token é opcional, mas recomendamos sua utilização. Ele será enviado pelo Asaas no header:

asaas-access-token: seu_token

Sua aplicação deve validar esse valor antes de processar a solicitação.

🚧
Atenção
Após a ativação, todas as transferências e demais operações de saque realizadas pela API serão submetidas à validação.

Operações realizadas pela interface

Você também pode habilitar a validação para operações solicitadas pela interface web.

Nesse caso, tanto as operações realizadas pela API quanto pela interface passarão pelo mesmo fluxo.

Estornos Pix

📘
Para validar também estornos Pix, marque a opção Ativar autorização de saque para estornos Pix.
Essa configuração é opcional e independente da validação dos demais saques.

Subcontas

📘
A configuração da conta raiz é aplicada automaticamente às subcontas, incluindo operações BaaS e não BaaS.

2. Prepare sua aplicação

Antes de aprovar uma operação, valide:

se a solicitação foi originada pelo seu sistema;
se o ID recebido corresponde à operação registrada;
se o valor, favorecido e demais informações permanecem íntegros;
se a operação atende aos limites e às regras internas;
se o token enviado no header é válido;
se existem indícios de uso indevido da chave de API.

⚠️
Não aprove uma operação apenas porque o payload possui uma estrutura válida.
Compare os dados recebidos com a solicitação previamente registrada pela sua aplicação.

3. Identifique o tipo de operação

O campo type indica qual operação precisa ser validada.

Operação	Valor de `type`	Objeto enviado
Transferência	`TRANSFER`	`transfer`
Pagamento de conta	`BILL`	`bill`
Pagamento de QR Code Pix	`PIX_QR_CODE`	`pixQrCode`
Recarga de celular	`MOBILE_PHONE_RECHARGE`	`mobilePhoneRecharge`
Estorno Pix	`PIX_REFUND`	`pixRefund`

Exemplos de payload

Transferência

{
  "type": "TRANSFER",
  "transfer": {
    "object": "transfer",
    "id": "0bed986c-737d-49bf-a1cc-beca916797c4",
    "dateCreated": "2022-05-27",
    "status": "PENDING",
    "effectiveDate": null,
    "type": "BANK_ACCOUNT",
    "value": 22,
    "netValue": 22,
    "transferFee": 0,
    "scheduleDate": "2022-05-27",
    "confirmedDate": null,
    "failReason": null,
    "bankAccount": {
      "bank": {
        "code": null,
        "ispb": "00000000",
        "name": null
      },
      "accountName": "ASAAS GESTAO FINANCEIRA S.A.",
      "ownerName": "ASAAS GESTAO FINANCEIRA S.A.",
      "cpfCnpj": "70609293000194",
      "agency": "4124",
      "agencyDigit": null,
      "account": "42142",
      "accountDigit": "1",
      "pixAddressKey": null
    },
    "transactionReceiptUrl": null,
    "operationType": "PIX",
    "description": null
  }
}

Pagamento de conta

{
  "type": "BILL",
  "bill": {
    "object": "bill",
    "id": 623471,
    "status": "PENDING",
    "value": 20.0,
    "discount": 0,
    "interest": 0,
    "fine": 0,
    "identificationField": "23793381286001234107143000012345890460000002000",
    "dueDate": "2024-01-01",
    "scheduleDate": "2024-01-01",
    "paymentDate": null,
    "fee": 0,
    "description": null,
    "companyName": null,
    "transactionReceiptUrl": null,
    "canBeCancelled": true,
    "failReasons": null,
    "bankId": 4,
    "awaitingCriticalActionAuthorization": false,
    "bank": {
      "object": "bank",
      "id": 4,
      "code": "237",
      "name": "Bradesco"
    }
  }
}

Pagamento de QR Code Pix

{
  "type": "PIX_QR_CODE",
  "pixQrCode": {
    "id": "aa10c444-3f02-40e7-a248-2d00cff5a45d",
    "endToEndIdentifier": "E1954055020220714160403012347510",
    "finality": null,
    "value": 2,
    "changeValue": null,
    "refundedValue": 0,
    "effectiveDate": "2022-07-14 13:04:03",
    "scheduledDate": null,
    "status": "AWAITING_REQUEST",
    "type": "DEBIT",
    "originType": "STATIC_QRCODE",
    "conciliationIdentifier": null,
    "description": null,
    "transactionReceiptUrl": null,
    "refusalReason": null,
    "canBeCancelled": true,
    "originalTransaction": null,
    "externalAccount": {
      "ispb": 18236120,
      "ispbName": "NU PAGAMENTOS S.A. - INSTITUIÇÃO DE PAGAMENTO",
      "name": "John Doe",
      "cpfCnpj": "***.123.456-**",
      "addressKey": "[email protected]",
      "addressKeyType": "EMAIL"
    },
    "qrCode": {
      "payer": null,
      "conciliationIdentifier": null,
      "originalValue": 1.00,
      "dueDate": null,
      "interest": 0,
      "fine": 0,
      "discount": 0,
      "expirationDate": null
    },
    "payment": null
  }
}

Recarga de celular

{
  "type": "MOBILE_PHONE_RECHARGE",
  "mobilePhoneRecharge": {
    "id": "d29f7fdb-4cf9-4524-a44e-d1f3fd9ec0d3",
    "value": 20,
    "phoneNumber": "47999999999",
    "status": "PENDING",
    "canBeCancelled": true,
    "operatorName": "Claro"
  }
}

Estorno Pix

{
  "type": "PIX_REFUND",
  "pixRefund": {
    "id": "06391ba9-cbf9-4926-8988-374ac5d71cae",
    "transferId": "f3956d6d-6dbb-4882-8146-9df82288d95b",
    "endToEndIdentifier": null,
    "finality": null,
    "value": 200,
    "changeValue": null,
    "refundedValue": 0,
    "dateCreated": "17/12/2024 15:27:42",
    "effectiveDate": "17/12/2024 15:27:42",
    "scheduledDate": null,
    "status": "AWAITING_REQUEST",
    "type": "CREDIT_REFUND",
    "originType": null,
    "conciliationIdentifier": null,
    "description": null,
    "transactionReceiptUrl": null,
    "chargedFeeValue": 0,
    "canBeRefunded": false,
    "refundDisabledReason": "O tipo desta transação não permite que ela seja estornada.",
    "refusalReason": null,
    "canBeCancelled": false,
    "originalTransaction": {
      "id": "b9852968-7825-4458-b069-d266ce8455c9",
      "endToEndIdentifier": "6709a838-7422-4198-94ed-76166a70c595",
      "value": 1000,
      "effectiveDate": "17/12/2024 15:26:57"
    },
    "externalAccount": {
      "ispb": 19540550,
      "ispbName": "ASAAS GESTÃO FINANCEIRA INSTITUIÇÃO DE PAGAMENTO S.A.",
      "name": "John Doe",
      "agency": "0",
      "account": "0000000",
      "accountDigit": "0",
      "accountType": "CHECKING_ACCOUNT",
      "cpfCnpj": "***.138.240-**",
      "addressKey": null,
      "addressKeyType": null
    },
    "qrCode": null,
    "payment": "pay_e4xnd1cc04w2n33n",
    "addressKey": null,
    "addressKeyType": null,
    "externalReference": null
  }
}

4. Responda à validação

Após analisar o payload, responda ao próprio POST com um dos seguintes status:

Status	Resultado
`APPROVED`	A operação foi reconhecida e pode continuar
`REFUSED`	A operação deve ser recusada

Aprovar uma operação

{
  "status": "APPROVED"
}

Recusar uma operação

Você também pode informar o motivo da recusa no campo refuseReason:

{
  "status": "REFUSED",
  "refuseReason": "Transferência não encontrada no nosso banco"
}

Como confirmar o resultado

Quando sua aplicação retorna APPROVED, o Asaas prossegue com o processamento da operação.

A operação será cancelada quando:

sua aplicação retornar REFUSED;
a resposta não contiver APPROVED ou REFUSED;
o Webhook falhar três vezes consecutivas.

Cuidados para a implementação

registre a operação antes de receber a validação;
utilize o ID para evitar aprovações duplicadas;
valide o token recebido em asaas-access-token;
não aprove operações desconhecidas;
mantenha logs das decisões tomadas;
monitore falhas no endpoint configurado;
responda somente após concluir todas as validações necessárias.