Eventos para transferências

É possível utilizar Webhooks para que seu sistema seja notificado sobre alterações que ocorram nas transferências bancárias e transferências entre contas Asaas.

Os eventos que o Asaas notifica são:

TRANSFER_CREATED - Geração de nova transferência.
TRANSFER_PENDING - Transferência pendente de execução.
TRANSFER_IN_BANK_PROCESSING - Transferência em processamento bancário.
TRANSFER_BLOCKED - Transferência bloqueada.
TRANSFER_DONE - Transferência realizada.
TRANSFER_FAILED - Transferência falhou.
TRANSFER_CANCELLED - Transferência cancelada.

Quando utilizar

Os Webhooks de transferências são recomendados quando sua aplicação precisa acompanhar automaticamente o processamento das transferências realizadas pelo Asaas.

Alguns exemplos:

atualização de ERP ou sistema financeiro;
acompanhamento do status das transferências;
envio automático de comprovantes;
auditoria financeira;
sincronização de saldos e movimentações.

Comportamentos importantes

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

Por esse motivo, recomenda-se implementar idempotência utilizando o campo:

id

do evento recebido.

Além disso:

respostas HTTP fora da família 2xx podem provocar novas tentativas de entrega;
a fila poderá ser interrompida após falhas consecutivas;
os eventos permanecem armazenados por até 14 dias;
novos atributos poderão ser adicionados ao payload futuramente.

👍
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

Campo	Finalidade
`event`	Tipo do evento recebido
`id`	Identificador único do evento
`transfer.id`	Identificador da transferência
`transfer.status`	Status atual da transferência
`transfer.type`	Tipo da transferência
`transfer.operationType`	Meio utilizado na transferência
`transfer.value`	Valor transferido
`transfer.effectiveDate`	Data efetiva da transferência
`transfer.failReason`	Motivo da falha, quando existir
`transfer.transactionReceiptUrl`	URL do comprovante

Exemplo de JSON a ser recebido para transferências bancárias [POST]

A notificação consiste em um POST contendo um JSON, conforme este exemplo:

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

Exemplo de JSON para 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"
    }
}

Exemplo de JSON para 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"
    }
}

Exemplo de JSON a ser recebido para transferências entre contas Asaas [POST]

(Manter o exemplo atual)

Segurança e boas práticas

Recomenda-se:

validar o header asaas-access-token;
responder rapidamente com HTTP 2xx;
implementar idempotência utilizando o campo id;
processar os eventos de forma assíncrona;
monitorar os Logs de Webhooks;
preparar a aplicação para novos campos adicionados futuramente.

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