DiscordStatus
Guias / Guides

Mecanismo para validação de saque via webhooks

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

Configure a validação de saques por Webhook

Este mecanismo permite que sua aplicação autorize ou recuse operações de saída antes que elas sejam processadas pelo Asaas.

Mesmo que uma solicitação tenha sido autenticada com uma chave de API válida, a operação somente será executada após a aprovação da sua aplicação.

📘

Ao concluir este guia, você terá configurado um Webhook para validar operações de saída e saberá responder com a aprovação ou recusa.

Quando utilizar

Utilize este mecanismo para aplicar controles adicionais, como:

  • validação da origem da operação;
  • conferência de valores e favorecidos;
  • limites operacionais;
  • regras antifraude;
  • identificação de uso indevido da chave de API.

O mecanismo pode ser aplicado a transferências, pagamentos de contas, pagamentos de QR Codes Pix, recargas de celular e, opcionalmente, estornos Pix e liquidação de Splits de Pagamento.

Como funciona

  1. Sua aplicação solicita a operação e armazena os dados retornados pelo Asaas.
  2. Aproximadamente cinco segundos depois, o Asaas envia um POST para a URL configurada.
  3. Sua aplicação compara o payload recebido com a operação registrada.
  4. Sua aplicação responde com APPROVED ou REFUSED.
  5. O Asaas executa ou cancela a operação conforme a resposta.
⚠️

Caso a chamada ao seu Webhook falhe três vezes ou não retorne um status válido, a operação será cancelada.

1. Ative o mecanismo

Acesse Menu do usuário > Integrações > Mecanismos de segurança.

Informe:

  • a URL que receberá as solicitações de validação;
  • o e-mail para notificações de erro;
  • um token de autenticação.

O token é opcional, mas recomendamos sua utilização. Ele será enviado pelo Asaas no header:

asaas-access-token: seu_token

Sua aplicação deve validar esse valor antes de processar a solicitação.

🚧

Atenção

Após a ativação, todas as transferências e demais operações de saque realizadas pela API serão submetidas à validação.

Operações realizadas pela interface

Você também pode habilitar a validação para operações solicitadas pela interface web.

Nesse caso, tanto as operações realizadas pela API quanto pela interface passarão pelo mesmo fluxo.

Estornos Pix

📘

Para validar também estornos Pix, marque a opção Ativar autorização de saque para estornos Pix.

Essa configuração é opcional e independente da validação dos demais saques.

Liquidação de Splits de Pagamento

📘

Para validar também a liquidação de Splits de Pagamento, marque a opção Ativar autorização de saque para Splits de Pagamento.

Essa configuração é opcional e independente da validação dos demais saques.

Nesse caso, o Webhook de validação é enviado aproximadamente cinco segundos após a liquidação do Split, que ocorre quando a cobrança é paga.

Enquanto a opção estiver ativa, todas as liquidações de Splits de Pagamento passam pela validação, independentemente da configuração de operações realizadas pela interface.

Subcontas

📘

A configuração da conta raiz é aplicada automaticamente às subcontas, incluindo operações BaaS e não BaaS.

2. Prepare sua aplicação

Antes de aprovar uma operação, valide:

  • se a solicitação foi originada pelo seu sistema;
  • se o ID recebido corresponde à operação registrada;
  • se o valor, favorecido e demais informações permanecem íntegros;
  • se a operação atende aos limites e às regras internas;
  • se o token enviado no header é válido;
  • se existem indícios de uso indevido da chave de API.
⚠️

Não aprove uma operação apenas porque o payload possui uma estrutura válida.

Compare os dados recebidos com a solicitação previamente registrada pela sua aplicação.

3. Identifique o tipo de operação

O campo type indica qual operação precisa ser validada.

OperaçãoValor de typeObjeto enviado
TransferênciaTRANSFERtransfer
Pagamento de contaBILLbill
Pagamento de QR Code PixPIX_QR_CODEpixQrCode
Recarga de celularMOBILE_PHONE_RECHARGEmobilePhoneRecharge
Estorno PixPIX_REFUNDpixRefund
Liquidação de Split de PagamentoPAYMENT_SPLITpaymentSplit

Exemplos de payload

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

Pagamento de conta

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

Pagamento de QR Code Pix

{
  "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,
    "canBeCancelled": true,
    "originalTransaction": null,
    "externalAccount": {
      "ispb": 18236120,
      "ispbName": "NU PAGAMENTOS S.A. - INSTITUIÇÃO 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
  }
}

Recarga de celular

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

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

Liquidação de Split de Pagamento

{
  "type": "PAYMENT_SPLIT",
  "paymentSplit": {
    "id": "157ac22a-6edd-4c46-8094-d78ca03f16a9",
    "status": "AWAITING_CREDIT",
    "payment": {
      "id": "pay_wnv5k3idzzbm1rte",
      "confirmedDate": "23/09/2026",
      "invoiceNumber": "00174367",
      "externalReference": null
    },
    "walletId": "64e8b366-903f-4112-aaff-da2220df0b62",
    "creditDate": null,
    "fixedValue": 40,
    "totalValue": 45.3,
    "description": "Descrição do Split",
    "originAccountId": "09ab105a-8f47-4dd2-bb45-4fcec3d8eb1a",
    "percentualValue": 5.5,
    "externalReference": "teste0002",
    "cancellationReason": null,
    "destinationAccountId": "6bbdd5f3-e224-4a0a-b9fc-330815117f0a"
  }
}
🚧

Cancelamento do Split na validação

O Split é cancelado quando sua aplicação retorna REFUSED, não retorna um status válido ou o Webhook falha três vezes consecutivas. Nesse caso, o valor retorna para a conta de origem do Split.

O motivo do cancelamento pode ser consultado no campo cancellationReason pelos endpoints de consulta de splits, como Listar splits pagos e Listar splits recebidos:

  • para a conta de origem do Split (quem criou o Split), o motivo é EXTERNAL_AUTHORIZATION_REFUSED;
  • para a conta de destino do Split (conta favorecida), o cancelamento é exibido de forma genérica como PAYMENT_SPLIT_VALIDATION_FAILED, sem detalhar que a causa foi a autorização externa.

Não é enviado Webhook informando o cancelamento e o evento PAYMENT_SPLIT_CANCELLED não é disparado. O refuseReason informado na resposta também não é exibido no Split.

4. Responda à validação

Após analisar o payload, responda ao próprio POST com um dos seguintes status:

StatusResultado
APPROVEDA operação foi reconhecida e pode continuar
REFUSEDA operação deve ser recusada

Aprovar uma operação

{
  "status": "APPROVED"
}

Recusar uma operação

Você também pode informar o motivo da recusa no campo refuseReason:

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

Como confirmar o resultado

Quando sua aplicação retorna APPROVED, o Asaas prossegue com o processamento da operação.

A operação será cancelada quando:

  • sua aplicação retornar REFUSED;
  • a resposta não contiver APPROVED ou REFUSED;
  • o Webhook falhar três vezes consecutivas.

Cuidados para a implementação

  • registre a operação antes de receber a validação;
  • utilize o ID para evitar aprovações duplicadas;
  • valide o token recebido em asaas-access-token;
  • não aprove operações desconhecidas;
  • mantenha logs das decisões tomadas;
  • monitore falhas no endpoint configurado;
  • responda somente após concluir todas as validações necessárias.

Updated 4 days ago

Did this page help you?