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.

🚧

Este mecanismo não é habilitado por padrão, precisando você entrar em contato com o suporte técnico para habilitá-lo e é, principalmente, recomendado para usos em contas White Label.

A liberação do uso está sujeito à análise.

❗️

Importante

Após ativado o mecanismo de validação via Webhooks, todas as formas de cash-out (transferências, pagamento de QRCodes, pagamento de contas e recargas de telefone) devem ser realizadas exclusivamente via API.

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

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.

Caso optem por seguir com a habilitação desse recurso, você precisa entrar em contato e informar a URL que será configurada para envio do POST, e também o authToken (obrigatório). Ao habilitar, essa funcionalidade será replicada para todas as subcontas da operação automaticamente.

Updated 1 day ago