DiscordStatus
Guias / Guides

Mechanism for validating withdrawals via webhooks

A way to confirm transfers via a special Webhook.

Suggest Edits

Asaas is constantly investing in security and developing methods to make your transactions with us increasingly secure and reliable.

In this documentation, you'll find details on how to validate transfers using Webhooks.

Enabling the mechanism via the interface

To enable the mechanism in your account, go to User Menu > Integrations > Security Mechanisms.

The setup is very simple. You just need to add your Webhook URL, the email address to receive error notifications, and the authentication token. This is optional, but we always recommend using it. This token will be sent in the asaas-access-token header, and you can validate it to ensure it's a legitimate Asaas request.

🚧

Attention

When configuring, all transfers and withdrawals made via the API will be handled by this security mechanism.

📘

Pix Refund Configuration

To enable Pix refund configuration, select the "Enable withdrawal authorization for Pix refunds" option. It's worth noting that this configuration is not required for withdrawals.

📘

Subaccount Configuration

The configuration is automatically configured for all subaccounts according to the configuration of the root account, whether white-labeled or not.

You also have the option to validate withdrawals via the interface. This means that any new withdrawals made from your account, whether via API or interface, will go through the validation process.

Withdrawal Authorization Flow

The withdrawal authorization flow works as follows:


How does the mechanism work?

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

Example of a request that Asaas will make (Transfer)

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

Example of a request that Asaas will make (Pay Bills)

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

Example of a request that Asaas will make (QRCode Payment)

{
   "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,
      "canBeCanceled":true,
      "originalTransaction":null,
      "externalAccount":{
         "ispb":18236120,
         "ispbName":"NU PAGAMENTOS S.A. - INSTITUI\u00c7\u00c3O 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
   }
}

Example of a request that Asaas will perform (Phone recharge)

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

Example of a request that Asaas will make (Pix Refund)

{
  "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,
    "canBeCanceled": 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
  }
}

How to validate a transfer

When you receive the POST, you'll need to respond to it, stating whether you recognize the transfer as a response to the POST itself. To do this, you must return a payload with a status.

The possible statuses are:

APPROVED

REFUSED

You can also provide the reason for the refusal by returning the refuseReason along with the payload, for example:

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

If the transfer is recognized and approved, you must respond as follows::

{ 
    "status": "APPROVED" 
}

If neither status is returned or the request fails 3 times in a row, we will consider the request as failed and the transfer will be canceled.

Updated 1 day ago