DiscordStatus
Guias / Guides

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. Com base nessa diretriz, disponibilizamos o mecanismo de validação de saque via webhooks.

Este mecanismo adiciona uma camada adicional de segurança às operações de saque realizadas via API.

Após uma solicitação de saque ser autenticada por meio de uma API Key válida, o Asaas consulta a sua aplicação para confirmar se aquela operação deve ou não ser executada. Dessa forma, a autenticação da requisição, por si só, não é suficiente para autorizar uma transferência.

A decisão final sobre a execução do saque permanece sob controle da aplicação do cliente, que poderá aplicar seus próprios critérios de negócio, validações antifraude, limites operacionais e demais controles de segurança antes de autorizar ou rejeitar a operação. Somente após o recebimento de uma resposta positiva do webhook é que o Asaas prossegue com a efetivação da transferência.

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 BaaS 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.
  • Verifique se as informações recebidas no payload correspondem exatamente à solicitação de saque registrada em seu sistema antes de autorizar a operação.
  • Responderá se aprova ou não a transferência.
    ⚠️

    Antes de responder autorizando uma transferência, recomendamos que sua aplicação valide, no mínimo:

    • que a solicitação de saque foi efetivamente originada pelo seu sistema;
    • que o payload recebido corresponde exatamente à operação previamente registrada;
    • que os valores, favorecido e demais informações da transferência permanecem íntegros;
    • que a operação atende às políticas internas de segurança, limites e prevenção à fraude;
    • que não há indícios de utilização indevida das credenciais de API;

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.