Transfer to Asaas account

Transfer balance between linked Asaas accounts using the walletId of the destination account.

In most cases, the transfer is completed immediately and the balance becomes available in the receiving account.

Before you start

Have:

• available balance in the source account;
• the walletId of the destination account;
• a link between the accounts involved.

If you did not store the walletId when the account was created, retrieve it before making the transfer.

See the Retrieve WalletId endpoint.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Obtain the walletId"] --> B["Validate the available balance"]
    B --> C["Create the transfer"]
    C --> D["Store the ID"]
    D --> E["Receive Webhooks"]
    E --> F["Reconcile the result"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Create the transfer

Use:

POST /v3/transfers/

Provide the amount and the walletId of the destination Asaas account:

{
  "value": 1000.00,
  "walletId": "0021c712-d963-4d86-a59d-031e7ac51a2e"
}

The externalReference field can also be used to relate the transfer to an identifier in your system.

See the Transfer to Asaas account endpoint.

Expected result

The API returns the data of the created transfer.

Store the returned id to identify the operation in events and reconciliation.

2. Track the transfer via Webhook

Prefer Webhooks to track status changes instead of repeatedly querying the transfer through the API.

For this flow, handle mainly:

Transfers between Asaas accounts are usually immediate. If critical event validation via APP Token or SMS Token is enabled, the transfer may remain pending until authorized.

See Transfer events.

Next steps

• See the Transfers Introduction
• See the Transfer to Asaas account reference
• Retrieve the WalletId
• Configure Transfer events
• Transfer to another institution or Pix key