Transfer to another institution via Pix or TED

Transfer the available balance in your Asaas account to an external bank account or directly to a Pix key.

Use POST /v3/transfers in both flows. The destination data determines how the transfer will be made.

Before you start

Confirm that:

• the account has available balance for the transfer;
• the destination bank details or Pix key are correct;
• your integration is using the API Key for the corresponding environment.

The requested amount cannot exceed the available balance.

Choose the destination

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Check the available balance"] --> B{"What is the destination?"}

    B --> BConta(("Bank account"))
    B --> BPix(("Pix key"))

    BConta --> C["Provide bankAccount"]
    BPix --> D["Provide pixAddressKey"]

    C --> E["Create the transfer"]
    D --> E

    E --> F["Store the ID"]
    F --> G["Receive Webhooks"]
    G --> H["Reconcile the result"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaOpcao fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class B decisao
    class C,D,E,F,G validacao
    class H sucesso

    class BConta respostaSim
    class BPix respostaOpcao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#8B5CF6,stroke-width:4px

1. Transfer to a bank account

Provide bankAccount with the destination account details.

POST /v3/transfers

{
  "value": 1000.00,
  "bankAccount": {
    "bank": {
      "code": "237"
    },
    "ownerName": "Marcelo Almeida",
    "cpfCnpj": "52233424611",
    "agency": "1263",
    "account": "9999991",
    "accountDigit": "1",
    "bankAccountType": "CONTA_CORRENTE"
  }
}

If you need to explicitly define the method, use operationType with PIX or TED.

Processing varies according to the method:

See the Transfer to another institution account or Pix key endpoint.

2. Transfer to a Pix key

Provide pixAddressKey and pixAddressKeyType.

POST /v3/transfers

{
  "value": 1000.00,
  "pixAddressKey": "09493012301",
  "pixAddressKeyType": "CPF",
  "scheduleDate": null,
  "description": "Barbecue paid via Pix with key"
}

The available key types are CPF, CNPJ, EMAIL, PHONE and EVP.

When providing the key:

• phone numbers must contain 11 digits, including the area code (DDD);
• CPF and CNPJ must be sent without punctuation.

3. Define when the Pix will be executed

A Pix transfer can be:

recurring is available only for Pix transfers.

See the Recurring Pix guide.

The Recurring Pix in this flow is a periodic transfer. It does not generate a QR Code for payment.

4. Track the transfer via Webhook

After creating the transfer, store the returned ID and use Webhooks to track the processing.

For the result of the operation, handle mainly:

Other events may indicate intermediate steps, such as bank processing or blocking.

See Transfer events.

Next steps

• See the Transfers Introduction
• See the reference for external transfers
• Configure recurring Pix transfers
• Configure Transfer events
• Transfer to a linked Asaas account