Mechanism for validating transfers via webhooks

Asaas is constantly investing in security and also creating methods to make your operation with us increasingly secure and reliable.

In this documentation, you will find details of the method for validating transfers through Webhooks.

🚧

This mechanism is not enabled by default, and you will need to contact technical support to enable it. It is mainly recommended for White Label account uses.

The release of use is subject to analysis.

❗️

Important

Once the validation mechanism via Webhooks is activated, all transfers must be made exclusively via API.

How does the mechanism work?

• You will request the transfer via API and store the ID or more data from the return in your database.
• Asaas will make a POST five seconds after the creation of the transfer to the configured URL with the transfer payload (the payloads will always be the same as sent in the return of the creation).
• This request can fail a maximum of three times, after the third failure, the transfer will be automatically canceled.
• You must verify if the received payload matches what you have stored.
• You will respond whether you approve the transfer or not.

Example of the request Asaas will make

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

Upon receiving the POST, you will need to respond to it indicating whether you recognize the transfer as a response from the POST itself. For this, it is necessary to return a payload with a status.

The possible statuses are:

APPROVED

REFUSED

It is also possible to inform the reason for the refusal, returning the refuseReason along with the payload, example:

{ 
    "status": "REFUSED", 
    "refuseReason": "Transfer not found in our bank" 
}

If the transfer is recognized and approved, it must be responded as follows:

{ 
    "status": "APPROVED" 
}

If neither of the two statuses is returned or the request fails 3 consecutive times, we will consider the request as a failure, and the transfer will be canceled.

If you opt to proceed with enabling this feature, you need to contact and inform the URL that will be configured for the POST sending, and also the authToken if necessary. Upon enabling, this functionality will be automatically replicated to all subaccounts of the operation.