Transferência

Inicie e acompanhe transferências por Pix ou TED.

A API de Transferência permite que você inicie e consulte transferências por Pix ou TED. Você pode acompanhar transferências assinando eventos de webhook.

*Há limites diário e mensal para transferências (Pix, TED e DOC) para cada CNPJ. Estes limites podem ser consultados no App BTG Empresas, em Menu > Contas a Pagar > Meus Limites.
Para aumentar seus limites, entre em contato conosco pelo chat.

Casos de Uso

  • Iniciar e consultar uma transferência a partir de um sistema de gestão empresarial..
  • Integrar com sistemas de contas a pagar.

Modalidades de transferência

TED: É uma transferência eletrônica entre uma conta BTG e contas de outro banco. A compensação é imediata.

DOC: É uma transferência manual entre uma conta BTG e contas de outro banco. A compensação ocorre em três dias úteis.

TEF: É uma transferência eletrônica entra contas BTG.

PIX: É um pagamento eletrônico instantâneo. Só pode ser feito para contas corrente e contas de pagamento.

Segurança

📘

BTG Id

O Authorization Server do BTG Empresas se chama BTG Id. Usando o BTG Id, um aplicativo parceiro consegue consentimento e autorização para executar operações nas APIs do BTG em nome do cliente. Para saber mais, acesse a documentação do BTG Id

Escopos necessários

O token para consumir a API de Transferências deve ser gerado usando o Authorization Code.

O escopo openidé obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.

É necessário escolher um dos seguintes escopos:

EscopoDescrição
empresas.btgpactual.com/transfersPermite criar e consultar transferências.
empresas.btgpactual.com/transfers.readonlyPermite consultar transferências.

Recursos Disponíveis

Os recursos da API de Pix Cobrança estão disponíveis no API Reference.

📘

API Reference

Transferência API

Transferências agendadas

Uma transferência pode ser agendada até 1 dia antes.

*O formato de data para agendar transferências é AAAA-MM-DD.

Caso não haja recursos suficientes para uma transferência, há novas tentativas de hora em hora, dependendo da modalidade.

ModalidadePrimeira tentativaPróximas tentativas
TED7hDe hora em hora (11h às 17h)
TEF7hDe hora em hora (11h às 22h)
PIX7hDe hora em hora (11h às 22h)

Status de transferências

Uma transferência pode ter diversos status antes e depois de ser aprovada.

Antes da aprovação, uma transferência pode exibir os seguintes status:

StatusDescrição
AuthorizedTransferência autorizada.
WrongCredentialsTransferência não autorizada por falta de token ou biometria.
CanceledTransferência cancelada ou expirada.
CreationErrorErro na criação da transferência.
ExecutionErrorErro na execução da transferência.

Depois de receber o status Authorized, uma transferência pode exibir os seguintes status:

StatusDescrição
SCHEDULEDTransferência agendada.
CANCELEDTransferência agendada cancelada.
PROCESSINGTransferência em processamento.
RETRYINGNova tentativa de transferência.
CONFIRMEDTransferência confirmada.
FAILEDErro na transferência.
REVERTEDTransferência estornada.

Os status CANCELED, FAILED e REVERTED não podem ser revertidos. Ao receber esses status, uma transferência cessa.

O status CONFIRMED indica que houve débito na conta de origem, mas pode ser revertido.

Eventos

A API de Transferência disponibiliza os seguintes eventos de webhook:

transfer.success

Sucesso na liquidação.

{
  "eventId": "transfers.success",
  "metadataId": "61c07740-0000-0000-0000-63499b925735",
  "tenantId": "00000000000181",
  "message": {
    "brn": "btg:empresas:banking:transfers:87197ac6-0000-0000-0000-78a1eae6ae28",
    "transferId": "87197ac6-0000-0000-0000-78a4eae5ae27",
    "amount": 1,
    "debitParty": {
      "bankCode": "000",
      "branchCode": "00",
      "number": "000000000",
      "accountType": "CC",
      "taxId": "0000000000",
      "name": "DEBIT PARTY LTDA",
      "personType": "J"
    },
    "creditParty": {
      "bankCode": "000",
      "branchCode": "0000",
      "number": "000000",
      "accountType": "CC",
      "taxId": "0000000000",
      "name": "CREDIT PARTY LTDA",
      "personType": "J"
    },
    "description": "S20068",
    "type": "TED",
    "scheduledDate": "2023-04-06",
    "reason": "S20068",
    "tags": {}
  }
}

transfers.reverted

Transferência revertida.

{
  "eventId": "transfers.reverted",
  "metadataId": "61c07740-0000-0000-0000-63499b925735",
  "tenantId": "00000000000181",
  "message": {
    "brn": "btg:empresas:banking:transfers:ced9e849-d228-4721-a88d-0b7f900398cc",
    "transferId": "87197ac6-b85b-401f-00a4-78a4eae5ae27",
    "amount": 10.1,
    "debitParty": {
      "bankCode": "000",
      "branchCode": "00",
      "number": "0000000003",
      "accountType": "CC",
      "taxId": "00000000000002",
      "name": "00000000002",
      "personType": "J"
    },
    "creditParty": {
      "bankCode": "000",
      "branchCode": "0000",
      "number": "0000000000000",
      "accountType": "PG",
      "taxId": "00000000000",
      "name": "JOSE DA SILVA",
      "personType": "F"
    },
    "description": "saque dinheiro na nota",
    "type": "PIX",
    "scheduledDate": "2023-04-06",
    "reason": "saque dinheiro na nota",
    "tags": {
      "externalId": "000bdc2fa300d61bf3fda1ec"
    },
    "failedDetail": {
      "code": "INVALID_RECEIVER_ACCOUNT_TYPE",
      "message": "Tipo incorreto para a conta do usuário recebedor."
    }
  }
}

transfers.scheduled

Transferência agendada

{
  "eventId": "transfers.scheduled",
  "metadataId": "61c07740-0000-0000-0000-63499b925735",
  "tenantId": "00000000000181",
  "message": {
    "brn": "btg:empresas:banking:transfers:ec7fb630-0000-0000-0000-f8c3bcdf2204",
    "transferId": "87197ac6-0000-0000-0000-78a4eae5ae27",
    "amount": 1,
    "debitParty": {
      "bankCode": "000",
      "branchCode": "00",
      "number": "000000000",
      "accountType": "CC",
      "taxId": "0000000000",
      "name": "DEBIT PARTY LTDA",
      "personType": "J"
    },
    "creditParty": {
      "bankCode": "000",
      "branchCode": "0000",
      "number": "0000000000000",
      "accountType": "PG",
      "taxId": "00000000000",
      "name": "JOSE DA SILVA",
      "personType": "F"
    },
    "description": "",
    "type": "PIX",
    "scheduledDate": "2023-04-27",
    "reason": "",
    "tags": {
      "externalId": "8725b04c-0000-0000-0000-4bbb2138e390"
    }
  }
}

transfers.processing

Transferência em processamento.


 {
  "eventId": "transfers.processing",
  "metadataId": "61c07740-0000-0000-0000-63499b925735",
  "tenantId": "00000000000181",
  "message": {
    "brn": "btg:empresas:banking:transfers:6859d44d-0000-0000-0000-b99ea75a9c9e",
    "transferId": "6859d44d-0000-0000-0000-b99ea75a9c9e",
    "amount": 1000,
    "debitParty": {
      "bankCode": "000",
      "branchCode": "00",
      "number": "000000000",
      "accountType": "CC",
      "taxId": "0000000000",
      "name": "DEBIT PARTY LTDA",
      "personType": "J"
    },
    "creditParty": {
      "bankCode": "000",
      "branchCode": "0000",
      "number": "0000000000000",
      "accountType": "PG",
      "taxId": "00000000000",
      "name": "JOSE DA SILVA",
      "personType": "F"
    },
    "description": "",
    "type": "PIX",
    "scheduledDate": "2023-04-05",
    "reason": "",
    "tags": {}
  }
}

transfers.failed

Transferência falhou.

{
  "eventId": "transfers.failed",
  "metadataId": "61c07740-0000-0000-0000-63499b925735",
  "tenantId": "00000000000181",
  "message": {
    "brn": "btg:empresas:banking:transfers:6859d44d-0000-0000-0000-b99ea75a9c9e",
    "transferId": "6859d44d-0000-0000-0000-b99ea75a9c9e",
    "amount": 10.30,
    "debitParty": {
      "bankCode": "000",
      "branchCode": "00",
      "number": "000000000",
      "accountType": "CC",
      "taxId": "0000000000",
      "name": "DEBIT PARTY LTDA",
      "personType": "J"
    },
    "creditParty": {
      "bankCode": "000",
      "branchCode": "0000",
      "number": "0000000000000",
      "accountType": "PG",
      "taxId": "00000000000",
      "name": "JOSE DA SILVA",
      "personType": "F"
   },
    "description": "saque dinheiro na nota",
    "type": "PIX",
    "scheduledDate": "2023-04-03",
    "reason": "saque dinheiro na nota",
    "tags": {
      "externalId": "00000b7f3c9cba6ed56dd8a8"
    },
    "failedDetail": {
      "code": "ACCOUNT_NOT_FOUND",
      "message": "Verifique a titularidade e as informações da conta de destino."
    }
  }
}

transfers.confirmed

Transferência confirmada.

{
  "eventId": "transfers.confirmed",
  "metadataId": "61c07740-0000-0000-0000-63499b925735",
  "tenantId": "00000000000181",
  "message": {
    "brn": "btg:empresas:banking:transfers:6859d44d-0000-0000-0000-b99ea75a9c9e",
    "transferId": "6859d44d-0000-0000-0000-b99ea75a9c9e",
    "amount": 1000,
    "debitParty": {
      "bankCode": "000",
      "branchCode": "00",
      "number": "000000000",
      "accountType": "CC",
      "taxId": "0000000000",
      "name": "DEBIT PARTY LTDA",
      "personType": "J"
    },
    "creditParty": {
      "bankCode": "000",
      "branchCode": "0000",
      "number": "0000000000000",
      "accountType": "PG",
      "taxId": "00000000000",
      "name": "JOSE DA SILVA",
      "personType": "F"
    },
    "description": "",
    "type": "PIX",
    "scheduledDate": "2023-04-05",
    "reason": "",
    "tags": {}
  }
}

transfers.canceled

Transferência cancelada.

{
  "webhookId": "84ae6b58-0000-0000-0000-23f69649d684",
  "event": "transfers.canceled",
  "data": {
    "brn": "btg:empresas:banking:transfers:5d453603-0000-0000-0000-284cdd8ec4b8",
    "transferId": "5d453603-0000-0000-0000-284cdd8ec4b8",
    "amount": 0.01,
    "debitParty": {
      "bankCode": "008",
      "branchCode": "00",
      "number": "00000002",
      "accountType": "CC",
      "taxId": "0000000000005",
      "name": "DEBIT PARTY LTDA",
      "personType": "J"
    },
    "creditParty": {
      "bankCode": 008",
      "branchCode": "00",
      "number": "00000002",
      "accountType": "CC",
      "taxId": "1000000000",
      "name": "CREDIT PARTY",
      "personType": "F"
    },
    "description": "teste de cancelamento",
    "type": "PIX",
    "scheduledDate": "2023-05-10",
    "reason": "teste de cancelamento",
    "tags": { "externalId": "dc2dd462-0000-0000-0000-4a2e5b430b4e" }
  }
}

transfers.retrying

Nova tentativa de transferência

{
  "eventId": "transfers.retrying",
  "metadataId": "61c07740-0000-0000-0000-63499b925735",
  "tenantId": "00000000000181",
  "message": {
    "brn": "btg:empresas:banking:transfers:61c07740-0000-0000-0000-63499b925735",
    "transferId": "61c07740-0000-0000-0000-63499b925735",
    "amount": 500.2,
    "debitParty": {
      "bankCode": "008",
      "branchCode": "00",
      "number": "000000008",
      "accountType": "CC",
      "taxId": "00000000000001",
      "name": "DEBIT PARTY",
      "personType": "J"
    },
    "creditParty": {
      "bankCode": "000",
      "branchCode": "01",
      "number": "00000003",
      "accountType": "PG",
      "taxId": "0000000008",
      "name": "CREDIT PARTY",
      "personType": "F"
    },
    "description": "PIX1",
    "type": "PIX",
    "scheduledDate": "2023-04-22",
    "reason": "PIX",
    "tags": {},
    "failedDetail": {
      "code": "INSUFFICIENT_FUNDS",
      "message": "Saldo insuficiente no momento da operação"
    }
  }
}