External Transfer via Pix

You will identify when to send only a Pix key and when to provide bank account details to create an external transfer through the Asaas API.

When to use Pix key transfer

Use Pix key transfer when your application needs to move balance from the Asaas account outside the platform and the recipient can be identified by a Pix key.

In this scenario, you do not need to send bank account details. Send the pixAddressKey and pixAddressKeyType fields in the transfer request.

Example: Pix key transfer

{
  "value": 150.75,
  "pixAddressKey": "[email protected]",
  "pixAddressKeyType": "EMAIL",
  "description": "Supplier payment",
  "externalReference": "transfer-1001"
}

In this flow, the API creates a transfer via Pix using the provided key. If the key is invalid, incompatible with the specified type, or cannot be validated, handle the rejection returned by the API before resending the transfer.

When to use manual bank account details

Use manual bank account details when you do not have the recipient's Pix key or when you need to identify the destination by a bank account. In this case, send the bankAccount object with the destination account details instead of pixAddressKey and pixAddressKeyType.

The transfer method depends on the data sent:

1. Send pixAddressKey and pixAddressKeyType to transfer directly via Pix key.
2. Send bankAccount to transfer to an external bank account.
3. Send operationType when you need to explicitly define the method as PIX or TED.
4. If operationType is not provided, the system automatically determines the transfer type: Pix when the destination institution is a participant, or TED otherwise.

Example: transfer with bank account details

{
  "value": 150.75,
  "bankAccount": {
    "bank": "001",
    "accountName": "Recipient name",
    "ownerName": "Account holder name",
    "cpfCnpj": "00000000000",
    "agency": "0001",
    "account": "12345",
    "accountDigit": "6"
  },
  "operationType": "PIX",
  "description": "Supplier payment",
  "externalReference": "transfer-1002"
}

Use this format when the Pix transfer is made using the recipient's bank account details rather than a Pix key.

Integration considerations

• Validate that pixAddressKeyType matches the format of the key provided in pixAddressKey before sending the request.
• Do not send pixAddressKey together with manual bank account details when the chosen flow is a bank account transfer.
• Use externalReference to link the transfer to your system's identifier and avoid reconciliation issues.
• Handle error responses and rejections before attempting to resend the same transfer, especially in cases of invalid keys, incorrect bank details, or temporary unavailability.
• Check the transfer status after creation. The reference documents states such as PENDING, DONE, and CANCELLED.

Related reference

See the full parameters, behavior rules, and responses in the Transfer to Another Institution Account or Pix Key endpoint.