Mecanismo para validação de transferências via webhooks

O Asaas está constantemente investindo em segurança, e também criando métodos para tornar a sua operação conosco cada vez mais segura e confiável.

Nessa documentação, você encontrará o detalhamento do método de validação de transferências através de Webhooks.

🚧

Este mecanismo não é habilitado por padrão, precisando você entrar em contato com o suporte técnico para habilitá-lo e é, principalmente, recomendado para usos em contas White Label.

A liberação do uso está sujeito à análise.

❗️

Importante

Após ativado o mecanismo de validação via Webhooks, todas as transferências devem ser realizadas exclusivamente via API.

Como o mecanismo funciona?

• Você solicitará a transferência via API e armazenará o ID ou mais dados do retorno em sua base de dados.
• O Asaas fará um POST cinco segundos após a criação da transferência para a URL configurada com o payload da transferência (os payloads sempre serão os mesmos enviados no retorno da criação).
• Essa requisição pode falhar no máximo três vezes, após a terceira falha a transferência será cancelada automaticamente.
• Você deve verificar se o payload recebido bate com o que possui armazenado.
• Responderá se aprova ou não a transferência.

Exemplo de requisição que o Asaas irá realizar

{
   "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
   }
}

Ao receber o POST, você precisará respondê-lo informando se reconhece a transferência como resposta do próprio POST. Para isso é necessário que você retorne um payload com um status.

Os possíveis status são:

APPROVED

REFUSED

Também é possível informar o motivo da recusa, retornando junto do payload o refuseReason, exemplo:

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

Caso a transferência seja reconhecida e aprovada, é preciso responder da seguinte forma:

{ 
    "status": "APPROVED" 
}

Caso não seja retornado nenhum dos dois status ou a requisição apresente falha por 3 vezes consecutivas, daremos a solicitação como falha e a transferência será cancelada.

Caso optem por seguir com a habilitação desse recurso, você precisa entrar em contato e informar a URL que será configurada para envio do POST, e também o authToken caso seja necessário. Ao habilitar, essa funcionalidade será replicada para todas as subcontas da operação automaticamente.