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:
| Escopo | Descrição |
|---|---|
empresas.btgpactual.com/transfers | Permite criar e consultar transferências. |
empresas.btgpactual.com/transfers.readonly | permite consultar transferências. |
Recursos Disponíveis
Os recursos da API de Pix Cobrança estão disponíveis no API Reference.
API Reference
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.
| Modalidade | Primeira tentativa | Próximas tentativas |
|---|---|---|
| TED | 7h | De hora em hora (11h às 17h) |
| TEF | 7h | De hora em hora (11h às 22h) |
| PIX | 7h | De 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:
| Status | Descrição |
|---|---|
| Authorized | Transferência autorizada. |
| WrongCredentials | Transferência não autorizada por falta de token ou biometria. |
| Cancelled | Transferência cancelada ou expirada. |
| CreationError | Erro na criação da transferência. |
| ExecutionError | Erro na execução da transferência. |
Depois de receber o status Authorized, uma transferência pode exibir os seguintes status:
| Status | Descrição |
|---|---|
| SCHEDULED | Transferência agendada. |
| CANCELED | Transferência agendada cancelada. |
| PROCESSING | Transferência em processamento. |
| RETRYING | Nova tentativa de transferência. |
| CONFIRMED | Transferência confirmada. |
| FAILED | Erro na transferência. |
| REVERTED | Transferê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.
{
"brn": "btg:empresas:banking:transfers:87197ac6-b95b-401f-80a4-78a1eae6ae28",
"transferId": "87197ac6-b85b-401f-00a4-78a4eae5ae27",
"amount": 0000,
"debitParty": {
"bankCode": "000",
"branchCode": "00",
"number": "000000000",
"accountType": "CC",
"taxId": "0000000000",
"name": "JUBIABA PARTICIPACOES LTDA",
"personType": "J"
},
"creditParty": {
"bankCode": "000",
"branchCode": "0000",
"number": "000000",
"accountType": "CC",
"taxId": "0000000000",
"name": "JOAO MENDES LTDA",
"personType": "J"
},
"description": "S20068",
"type": "TED",
"scheduledDate": "2023-04-06",
"reason": "S20068",
"tags": {}
}
transfers.reverted
Transferência revertida.
{
"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": "642bdc2fa300d61bf3fda1ec"
},
"failedDetail": {
"code": "INVALID_RECEIVER_ACCOUNT_TYPE",
"message": "Tipo incorreto para a conta do usuário recebedor."
}
}
transfers.scheduled
Transferência agendada
{
"brn": "btg:empresas:banking:transfers:ec7fb630-04af-44cd-8b4c-f8c3bcdf2204",
"transferId": "87197ac6-b85b-401f-00a4-78a4eae5ae27",
"amount": 0000,
"debitParty": {
"bankCode": "000",
"branchCode": "00",
"number": "000000000",
"accountType": "CC",
"taxId": "0000000000",
"name": "JUBIABA PARTICIPACOES 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-1354-4ad7-91db-4bbb2138e390"
}
}
transfers.processing
Transferência em processamento.
{
"brn": "btg:empresas:banking:transfers:6859d44d-c664-4925-b56b-b99ea75a9c9e",
"transferId": "6859d44d-c664-4925-b56b-b99ea75a9c9e",
"amount": 1000,
"debitParty": {
"bankCode": "000",
"branchCode": "00",
"number": "000000000",
"accountType": "CC",
"taxId": "0000000000",
"name": "JUBIABA PARTICIPACOES 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.
{
"brn": "btg:empresas:banking:transfers:6859d44d-c664-4925-b56b-b99ea75a9c9e",
"transferId": "6859d44d-c664-4925-b56b-b99ea75a9c9e",
"amount": 1000,
"debitParty": {
"bankCode": "000",
"branchCode": "00",
"number": "000000000",
"accountType": "CC",
"taxId": "0000000000",
"name": "JUBIABA PARTICIPACOES 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": "6424bb7f3c9cba6ed56dd8a8"
},
"failedDetail": {
"code": "ACCOUNT_NOT_FOUND",
"message": "Verifique a titularidade e as informações da conta de destino."
}
}
transfers.confirmed
Transferência confirmada.
{
"brn": "btg:empresas:banking:transfers:6859d44d-c664-4925-b56b-b99ea75a9c9e",
"transferId": "6859d44d-c664-4925-b56b-b99ea75a9c9e",
"amount": 1000,
"debitParty": {
"bankCode": "000",
"branchCode": "00",
"number": "000000000",
"accountType": "CC",
"taxId": "0000000000",
"name": "JUBIABA PARTICIPACOES 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-c7fe-48e3-a211-23f69649d684",
"event": "transfers.canceled",
"data": {
"brn": "btg:empresas:banking:transfers:5d453603-df7c-4b3a-9da6-284cdd8ec4b8",
"transferId": "5d453603-df7c-4b3a-9da6-284cdd8ec4b8",
"amount": 0.01,
"debitParty": {
"bankCode": "008",
"branchCode": "00",
"number": "00000002",
"accountType": "CC",
"taxId": "0000000000005",
"name": "0000000000005",
"personType": "J"
},
"creditParty": {
"bankCode": 008",
"branchCode": "00",
"number": "00000002",
"accountType": "CC",
"taxId": "1000000000",
"name": "PEDRO ALVARES CABRAL",
"personType": "F"
},
"description": "teste de cancelamento",
"type": "PIX",
"scheduledDate": "2023-05-10",
"reason": "teste de cancelamento",
"tags": { "externalId": "dc2dd462-979f-49d5-909b-4a2e5b430b4e" }
}
}
transfers.retrying
Nova tentativa de transferência
{
"eventId": "transfers.retrying",
"metadataId": "61c07740-c1e6-4686-a2f9-63499b925735",
"tenantId": "21845712000181",
"message": {
"brn": "btg:empresas:banking:transfers:61c07740-c1e6-4686-a2f9-63499b925735",
"transferId": "61c07740-c1e6-4686-a2f9-63499b925735",
"amount": 500,
"debitParty": {
"bankCode": "008",
"branchCode": "00",
"number": "000000008",
"accountType": "CC",
"taxId": "00000000000001",
"name": "JUBIABA PARTICIPACOES",
"personType": "J"
},
"creditParty": {
"bankCode": "000",
"branchCode": 01",
"number": "00000003",
"accountType": "PG",
"taxId": "0000000008",
"name": "Pedro Alvares Cabral",
"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"
}
}
}
Updated 13 days ago