DiscordStatus
Guias / Guides

Eventos para transferências

Escute os eventos do Asaas para ter sua integração em dia.

Use os eventos de transferência para acompanhar automaticamente o processamento de transferências para outras instituições e entre contas Asaas.

Cada notificação informa o evento ocorrido em event e os dados atuais da transferência no objeto transfer.

Eventos disponíveis

EventoQuando ocorre
TRANSFER_CREATEDUma nova transferência é criada.
TRANSFER_PENDINGA transferência está pendente de execução.
TRANSFER_IN_BANK_PROCESSINGA transferência está em processamento bancário.
TRANSFER_BLOCKEDA transferência está bloqueada.
TRANSFER_DONEA transferência é realizada.
TRANSFER_FAILEDA transferência falha.
TRANSFER_CANCELLEDA transferência é cancelada.

Os eventos disponíveis não representam uma sequência obrigatória. O processamento depende do tipo e das condições da transferência.

Como interpretar os eventos

EventoTratamento na integração
TRANSFER_CREATEDRegistre a transferência e associe o transfer.id à operação no seu sistema.
TRANSFER_PENDINGMantenha a operação como pendente.
TRANSFER_IN_BANK_PROCESSINGIndique que a transferência está em processamento bancário.
TRANSFER_BLOCKEDNão considere a transferência concluída enquanto permanecer bloqueada.
TRANSFER_DONEConfirme a conclusão e utilize transactionReceiptUrl quando o comprovante estiver disponível.
TRANSFER_FAILEDMarque a operação como falha e consulte failReason, quando preenchido.
TRANSFER_CANCELLEDAtualize a operação como cancelada.
👍

Retorno do Webhook com tipagem e ENUMs

Caso você queira saber qual o tipo de cada campo e os retornos de ENUMs disponíveis, confira a resposta 200 no endpoint "Recuperar uma única transferência" na documentação.

Campos importantes do payload

CampoFinalidade
idIdentificador único do evento. Utilize-o para idempotência.
eventIdentifica o evento recebido.
transfer.idIdentificador da transferência.
transfer.statusStatus atual da transferência.
transfer.typeTipo da transferência.
transfer.operationTypeMeio utilizado na transferência.
transfer.valueValor transferido.
transfer.effectiveDateData efetiva da transferência.
transfer.failReasonMotivo da falha, quando existir.
transfer.transactionReceiptUrlURL do comprovante, quando disponível.

event identifica a alteração notificada pelo Webhook. transfer.status representa o estado atual da transferência no payload.

Exemplos de payload

Transferência bancária via TED

{
    "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
    "event": "TRANSFER_CREATED",
    "dateCreated": "2024-06-12 16:45:03",
    "account": {
        "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
        "ownerId": null
    },
    "transfer": {
        "object": "transfer",
        "id": "777eb7c8-b1a2-4356-8fd8-a1b0644b5282",
        "dateCreated": "2019-05-02",
        "status": "PENDING",
        "effectiveDate": null,
        "endToEndIdentifier": null,
        "type": "BANK_ACCOUNT",
        "value": 1000,
        "netValue": 1000,
        "transferFee": 0,
        "scheduleDate": "2019-05-02",
        "authorized": true,
        "failReason": null,
        "transactionReceiptUrl": null,
        "bankAccount": {
            "bank": {
                "ispb": "00000000",
                "code": "001",
                "name": "Banco do Brasil"
            },
            "accountName": "Conta Banco do Brasil",
            "ownerName": "Marcelo Almeida",
            "cpfCnpj": "***.143.689-**",
            "agency": "1263",
            "agencyDigit": "1",
            "account": "26544",
            "accountDigit": "1",
            "pixAddressKey": null
        },
        "operationType": "TED",
        "description": null
    }
}

Transferência via Pix sem chave cadastrada

{
    "event": "TRANSFER_CREATED",
    "transfer": {
        "object": "transfer",
        "id": "777eb7c8-b1a2-4356-8fd8-a1b0644b5282",
        "dateCreated": "2019-05-02",
        "status": "PENDING",
        "effectiveDate": null,
        "endToEndIdentifier": null,
        "type": "BANK_ACCOUNT",
        "value": 1000,
        "netValue": 1000,
        "transferFee": 0,
        "scheduleDate": "2019-05-02",
        "authorized": true,
        "failReason": null,
        "transactionReceiptUrl": null,
        "bankAccount": {
            "bank": {
                "ispb": "00000000",
                "code": "001",
                "name": "Banco do Brasil"
            },
            "accountName": "Conta Banco do Brasil",
            "ownerName": "Marcelo Almeida",
            "cpfCnpj": "***.143.689-**",
            "agency": "1263",
            "agencyDigit": "1",
            "account": "26544",
            "accountDigit": "1",
            "pixAddressKey": null
        },
        "operationType": "PIX",
        "description": "Transferência efetuada via Pix manual"
    }
}

Transferência via Pix utilizando chave Pix

{
    "event": "TRANSFER_CREATED",
    "transfer": {
        "object": "transfer",
        "id": "777eb7c8-b1a2-4356-8fd8-a1b0644b5282",
        "dateCreated": "2019-05-02",
        "status": "PENDING",
        "effectiveDate": null,
        "endToEndIdentifier": null,
        "type": "BANK_ACCOUNT",
        "value": 1000,
        "netValue": 1000,
        "transferFee": 0,
        "scheduleDate": "2019-05-02",
        "authorized": true,
        "failReason": null,
        "transactionReceiptUrl": null,
        "bankAccount": {
            "bank": {
                "ispb": "00000000",
                "code": "001",
                "name": "Banco do Brasil"
            },
            "accountName": "Conta Banco do Brasil",
            "ownerName": "Marcelo Almeida",
            "cpfCnpj": "***.143.689-**",
            "agency": "1263",
            "agencyDigit": "1",
            "account": "26544",
            "accountDigit": "1",
            "pixAddressKey": "09413412375"
        },
        "operationType": "PIX",
        "description": "Transferência efetuada via Pix com chave"
    }
}

Transferências entre contas Asaas

Os mesmos eventos também permitem acompanhar transferências entre contas Asaas vinculadas.

Para entender a operação e os dados necessários para realizar esse tipo de transferência, consulte Transferência para conta Asaas.

Como tratar os eventos

Ao receber um evento de transferência:

  1. identifique a alteração pelo campo event;
  2. persista o id do evento para impedir processamento duplicado;
  3. utilize transfer.id para localizar a transferência no seu sistema;
  4. atualize a operação conforme o evento e os dados presentes em transfer;
  5. responda HTTP 200 após confirmar a persistência;
  6. processe regras adicionais de forma assíncrona.

Os Webhooks seguem o modelo at least once, portanto o mesmo evento pode ser enviado mais de uma vez.

Consulte como implementar idempotência em Webhooks.

Para acompanhar mudanças de estado, prefira esses eventos em vez de consultar repetidamente a transferência pela API.

🚧

Atenção

  • Transferências entre contas Asaas são realizadas instantaneamente. Caso a validação de evento crítico via Token APP ou Token SMS esteja habilitada para o agendamento de transferências, a transferência ficará pendente até que a validação seja realizada.
  • Transferências via Pix não agendadas são realizadas instantaneamente. O Token APP e Token SMS devem estar desabilitados.
🚧

Atenção

  • Com a entrada de novos produtos e funções dentro do Asaas, é possível que novos atributos sejam incluídos no Webhook. É muito importante que seu código esteja preparado para não gerar exceções caso o Asaas devolva novos atributos não tratados pela sua aplicação, pois isso poderá causar interrupção na fila de sincronização.
  • Enviaremos um e-mail e avisaremos em nosso Discord quando novos campos forem incluídos no Webhook. O disparo será feito para o e-mail de notificação definido nas configurações do Webhook.

Próximos passos

Updated about 8 hours ago

Did this page help you?