DiscordStatus
Guias / Guides

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

Uma forma de confirmar transferências via um Webhook especial.

Suggest Edits

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 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.

Fluxo para autorização de saques

O fluxo de autorização de saques funciona da seguinte forma:

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":"Marcelo da Silva",
         "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"
   }
}

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 4 months ago