Events for transfers

Listen to Asaas events to keep your integration up to date.

You can use Webhooks so that your system is notified about changes that occur in bank transfers and transfers between Asaas accounts.

The events notified by Asaas are:

TRANSFER_CREATED - New transfer created.
TRANSFER_PENDING - Transfer pending execution.
TRANSFER_IN_BANK_PROCESSING - Transfer under bank processing.
TRANSFER_BLOCKED - Transfer blocked.
TRANSFER_DONE - Transfer completed.
TRANSFER_FAILED - Transfer failed.
TRANSFER_CANCELLED - Transfer canceled.

When to use

Transfer Webhooks are recommended when your application needs to automatically track transfers performed through Asaas.

Some examples:

updating an ERP or financial system;
tracking transfer status;
automatically sending receipts;
financial auditing;
synchronizing balances and transactions.

Important behaviors

Webhooks use the at least once delivery model, which means the same event may be sent more than once.

For this reason, it is recommended to implement idempotency using the field:

id

from the received event.

In addition:

HTTP responses outside the 2xx range may trigger new delivery attempts;
the queue may be interrupted after consecutive failures;
events remain stored for up to 14 days;
new attributes may be added to the payload in the future.

👍
Webhook response with typing and ENUMs
If you want to know the type of each field and the available ENUM values, check the 200 response of the endpoint "Retrieve a single transfer" in the documentation.

Important fields

Field	Purpose
`event`	Type of the received event
`id`	Unique event identifier
`transfer.id`	Transfer identifier
`transfer.status`	Current transfer status
`transfer.type`	Transfer type
`transfer.operationType`	Transfer method used
`transfer.value`	Transferred amount
`transfer.effectiveDate`	Effective transfer date
`transfer.failReason`	Failure reason, when applicable
`transfer.transactionReceiptUrl`	Receipt URL

Example JSON received for bank transfers [POST]

The notification consists of a POST containing a JSON, as shown below:

{
    "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": "Banco do Brasil Account",
            "ownerName": "Marcelo Almeida",
            "cpfCnpj": "***.143.689-**",
            "agency": "1263",
            "agencyDigit": "1",
            "account": "26544",
            "accountDigit": "1",
            "pixAddressKey": null
        },
        "operationType": "TED",
        "description": null
    }
}

Example JSON for Pix transfer without a registered Pix key

{
    "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": "Banco do Brasil Account",
            "ownerName": "Marcelo Almeida",
            "cpfCnpj": "***.143.689-**",
            "agency": "1263",
            "agencyDigit": "1",
            "account": "26544",
            "accountDigit": "1",
            "pixAddressKey": null
        },
        "operationType": "PIX",
        "description": "Transfer performed via manual Pix"
    }
}

Example JSON for Pix transfer using a Pix key

{
    "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": "Banco do Brasil Account",
            "ownerName": "Marcelo Almeida",
            "cpfCnpj": "***.143.689-**",
            "agency": "1263",
            "agencyDigit": "1",
            "account": "26544",
            "accountDigit": "1",
            "pixAddressKey": "09413412375"
        },
        "operationType": "PIX",
        "description": "Transfer performed via Pix key"
    }
}

Example JSON received for transfers between Asaas accounts [POST]

(Keep the current example)

Security and best practices

It is recommended to:

validate the asaas-access-token header;
respond quickly with HTTP 2xx;
implement idempotency using the id field;
process events asynchronously;
monitor Webhook Logs;
prepare the application for new fields that may be added in the future.

🚧
Attention

Transfers between Asaas accounts are processed instantly. If critical event validation through APP Token or SMS Token is enabled for scheduled transfers, the transfer will remain pending until validation is completed.

Non-scheduled Pix transfers are processed instantly. APP Token and SMS Token must be disabled.

🚧
Attention

As new products and features are introduced in Asaas, new attributes may be added to the Webhook. It is very important that your code is prepared not to throw exceptions if Asaas returns new attributes not handled by your application, as this may cause interruption of the synchronization queue.

We will send an email and notify our Discord whenever new fields are added to the Webhook. Notifications will be sent to the email address configured in the Webhook settings.