Mecanismo para validação de saque via webhooks
Uma forma de confirmar transferências via um Webhook especial.
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.
Ativando mecanismo via interface
Para ativar o mecanismo na sua conta, acesse o Menu do usuário > Integrações > Mecanismos de segurança.

A configuração é bem simples, você precisa apenas adicionar qual será a URL do seu Webhook, o e-mail para receber notificações de erros e o token de autenticação, ele é opcional, porém sugerimos sempre utilizar. Este token será enviado no header asaas-access-token
e você pode validá-lo para saber que se trata de uma requisição legítima do Asaas.
Atenção
Ao realizar a configuração, todas as transferências e saques realizados via API serão tratadas por este mecanismo de segurança.
Configuração para estornos Pix
Para habilitar a configuração de estornos Pix, marque a opção "Ativar autorização de saque para estornos Pix". Vale ressaltar que essa configuração não é obrigatória para saques.
Configuração para subcontas
A configuração é feita automaticamente para todas as subcontas de acordo com a configuração realizada na conta raiz, sejam elas white label ou não.
Você tem a opção de validar também os saques via interface, dessa forma qualquer novo saque realizado na sua conta, seja via API ou via interface irá passar pelo fluxo de validação.
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 (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
}
}
Exemplo de requisição que o Asaas irá realizar (Pague Contas)
{
"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"
}
}
}
Exemplo de requisição que o Asaas irá realizar (Pagamento de QRCode)
{
"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
}
}
Exemplo de requisição que o Asaas irá realizar (Recarga de telefone)
{
"type":"MOBILE_PHONE_RECHARGE",
"mobilePhoneRecharge":{
"id":"d29f7fdb-4cf9-4524-a44e-d1f3fd9ec0d3",
"value":20,
"phoneNumber":"47999999999",
"status":"PENDING",
"canBeCancelled":true,
"operatorName":"Claro"
}
}
Exemplo de requisição que o Asaas irá realizar (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,
"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
}
}
Como validar uma transferência
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.
Updated 3 days ago