Transferência externa via Pix

Você vai identificar quando enviar apenas uma chave Pix e quando informar dados bancários para criar uma transferência externa pela API do Asaas.

Quando usar transferência por chave Pix

Use a transferência por chave Pix quando sua aplicação precisa movimentar saldo da conta Asaas para fora da plataforma e o destinatário pode ser identificado por uma chave Pix.

Nesse cenário, não é necessário enviar os dados da conta bancária. Envie os campos pixAddressKey e pixAddressKeyType na requisição de transferência.

Exemplo: transferência por chave Pix

{
  "value": 150.75,
  "pixAddressKey": "[email protected]",
  "pixAddressKeyType": "EMAIL",
  "description": "Repasse ao fornecedor",
  "externalReference": "repasse-1001"
}

Nesse fluxo, a API cria uma transferência via Pix usando a chave informada. Se a chave estiver inválida, incompatível com o tipo informado ou não puder ser validada, trate a rejeição retornada pela API antes de reenviar a transferência.

Quando usar dados bancários manuais

Use dados bancários manuais quando você não tiver uma chave Pix do destinatário ou quando precisar identificar o destino por uma conta bancária. Nesse caso, envie o objeto bankAccount com os dados da conta de destino, em vez de pixAddressKey e pixAddressKeyType.

A modalidade da transferência depende dos dados enviados:

1. Envie pixAddressKey e pixAddressKeyType para transferir diretamente por chave Pix.
2. Envie bankAccount para transferir para uma conta bancária externa.
3. Envie operationType quando precisar definir explicitamente a modalidade como PIX ou TED.
4. Se operationType não for informado, o sistema define automaticamente o tipo da transferência: Pix quando a instituição de destino for participante, ou TED caso contrário.

Exemplo: transferência com dados bancários

{
  "value": 150.75,
  "bankAccount": {
    "bank": "001",
    "accountName": "Nome do destinatário",
    "ownerName": "Nome do titular",
    "cpfCnpj": "00000000000",
    "agency": "0001",
    "account": "12345",
    "accountDigit": "6"
  },
  "operationType": "PIX",
  "description": "Repasse ao fornecedor",
  "externalReference": "repasse-1002"
}

Use esse formato quando a transferência Pix for feita a partir dos dados da conta bancária do destinatário, e não por uma chave Pix.

Cuidados de integração

• Valide se pixAddressKeyType corresponde ao formato da chave informada em pixAddressKey antes de enviar a requisição.
• Não envie pixAddressKey junto com dados bancários manuais quando o fluxo escolhido for transferência por conta bancária.
• Use externalReference para relacionar a transferência ao identificador do seu sistema e evitar dificuldade de conciliação.
• Trate respostas de erro e rejeições antes de tentar reenviar a mesma transferência, principalmente em casos de chave inválida, dados bancários incorretos ou indisponibilidade temporária.
• Consulte o status da transferência após a criação. A referência documenta estados como PENDING, DONE e CANCELLED.

Referência relacionada

Veja os parâmetros completos, regras de comportamento e respostas no endpoint Transferir para conta de outra Instituição ou chave Pix.