Transfer events

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

Use transfer events to automatically track the processing of transfers to other institutions and between Asaas accounts.

Each notification indicates the event that occurred in event and the current transfer data in the transfer object.

Available events

Event	When it occurs
`TRANSFER_CREATED`	A new transfer is created.
`TRANSFER_PENDING`	The transfer is pending execution.
`TRANSFER_IN_BANK_PROCESSING`	The transfer is in bank processing.
`TRANSFER_BLOCKED`	The transfer is blocked.
`TRANSFER_DONE`	The transfer is completed.
`TRANSFER_FAILED`	The transfer fails.
`TRANSFER_CANCELLED`	The transfer is cancelled.

The available events do not represent a mandatory sequence. Processing depends on the type and conditions of the transfer.

How to interpret the events

Event	Handling in the integration
`TRANSFER_CREATED`	Record the transfer and associate the `transfer.id` with the operation in your system.
`TRANSFER_PENDING`	Keep the operation as pending.
`TRANSFER_IN_BANK_PROCESSING`	Indicate that the transfer is in bank processing.
`TRANSFER_BLOCKED`	Do not consider the transfer completed while it remains blocked.
`TRANSFER_DONE`	Confirm completion and use `transactionReceiptUrl` when the receipt is available.
`TRANSFER_FAILED`	Mark the operation as failed and check `failReason`, when filled in.
`TRANSFER_CANCELLED`	Update the operation as cancelled.

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

Important payload fields

Field	Purpose
`id`	Unique identifier of the event. Use it for idempotence.
`event`	Identifies the event received.
`transfer.id`	Transfer identifier.
`transfer.status`	Current status of the transfer.
`transfer.type`	Transfer type.
`transfer.operationType`	Method used for the transfer.
`transfer.value`	Amount transferred.
`transfer.effectiveDate`	Effective date of the transfer.
`transfer.failReason`	Reason for the failure, when there is one.
`transfer.transactionReceiptUrl`	Receipt URL, when available.

event identifies the change notified by the Webhook. transfer.status represents the current state of the transfer in the payload.

Payload examples

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

Pix transfer without a registered 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 made via manual Pix"
    }
}

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 made via Pix with key"
    }
}

Transfers between Asaas accounts

The same events also let you track transfers between linked Asaas accounts.

To understand the operation and the data required to make this type of transfer, see Transfer to an Asaas account.

How to handle the events

When receiving a transfer event:

identify the change through the event field;
persist the event id to prevent duplicate processing;
use transfer.id to find the transfer in your system;
update the operation according to the event and the data in transfer;
respond HTTP 200 after confirming persistence;
process additional rules asynchronously.

Webhooks follow the at least once model, so the same event may be sent more than once.

See how to implement idempotence in Webhooks.

To track state changes, prefer these events instead of repeatedly querying the transfer through the API.

🚧
Attention

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

Unscheduled Pix transfers are made instantly. APP Token and SMS Token must be disabled.

🚧
Attention

As new products and features are added to Asaas, new attributes may be included in the Webhook. It is very important that your code is prepared not to throw exceptions if Asaas returns new attributes that your application does not handle, as this may interrupt the sync queue.

We will send an email and announce on our Discord when new fields are added to the Webhook. The email will be sent to the notification email address defined in the Webhook settings.

Next steps

Updated 13 days ago

Did this page help you?