Transferência via TED

stable

Este endpoint possibilita realizar a transferência de valores via TED entre contas pertencentes ao Bankly e do Bankly para contas de outras instituições financeiras.

Requisição

Requisição HTTP

HTTP

POST https://api-mtls.sandbox.bankly.com.br/fund-transfers

cURL

curl --request POST \
     --url 'https://api-mtls.sandbox.bankly.com.br/fund-transfers' \
     --header 'Idempotency-Key: GUID' \
     --header 'api-version: 1' \
     --header 'Authorization: Bearer [token]' \
     --header 'content-type: application/json' \
     --header 'accept: application/json' \
     --header 'x-correlation-id: GUID' \
     --data '
{
  "sender": {
    "document": "47742663023",
    "name": "Nísia Floresta",
    "branch": "0001",
    "account": "15164"
  },
  "recipient": {
    "accountType": "CHECKING",
    "document": "09992220074",
    "bankCode": "332",
    "branch": "0001",
    "account": "540108",
    "name": "Maria Quitéria de Jesus"
  },
  "amount": 100,
  "description": "Aluguel"
}
'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:

Scope	Descrição
ted.cashout.create	Concede acesso para iniciar uma transferência de valores via TED.

Cabeçalhos (Headers)

Nome	Descrição
api-version	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.
Authorization	Obrigatório. Token de autorização do tipo Bearer.
x-correlation-id	Obrigatório. Informe um GUID, sendo um novo cada requisição.
Idempotency-Key	Informação utilizada para evitar a duplicidade de transações (valor em formato UUID). Importante: O tempo para a expiração do Idempotency-Key é de 6 minutos.

🚧

Importante

Caso o parceiro envie o mesmo idempotencyKey em mais de uma requisição, não será retornado um erro. Porém, o authenticationCode será igual ao gerado na primeira operação, pois a transação não será duplicada.

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição
sender	object	Obrigatório. Objeto que deverá conter os dados do pagador da transação.
sender.document	string	Obrigatório. Número do documento.
sender.name	string	Obrigatório. Nome do pagador.
sender.branch	string	Obrigatório. Agência bancária.
sender.account	string	Obrigatório. Número da conta.
recipient	object	Obrigatório. Objeto que deverá conter os dados do recebedor da transação.
recipient.accountType	string	Tipo de conta, o qual pode ser "CHECKING", para conta corrente, ou "SAVINGS", para conta poupança. Caso este campo não seja enviado na requisição, será considerado o valor "CHECKING".
recipient.document	string	Obrigatório. Número do documento.
recipient.bankCode	string	Obrigatório. Código do banco.
recipient.branch	string	Obrigatório. Agência bancária.
recipient.account	string	Obrigatório. Número da conta.
recipient.name	string	Obrigatório. Nome do recebedor.
amount	string	Obrigatório. Valor da transação.
description	string	Descrição da transferência.

📘

Nota

O valor do campo bankCode pode ser obtido por meio da consulta ao endpoint Listagem de instituições financeiras.

JSON

{
  "sender": {
    "document": "47742663023",
    "name": "Nísia Floresta",
    "branch": "0001",
    "account": "15164"
  },
  "recipient": {
    "accountType": "CHECKING",
    "document": "09992220074",
    "bankCode": "332",
    "branch": "0001",
    "account": "540108",
    "name": "Maria Quitéria de Jesus"
  },
  "amount": 100,
  "description": "Aluguel"
}

Resposta (Response)

O status code 202 indicará sucesso na requisição.

🚧

Importante

O sucesso na requisição não significa que a transação já tenha acontecido. Desse modo, para conferir a situação da transferência, recomendamos realizar a consulta do status da transação.

Sendo bem-sucedido, o retorno irá trazer o seguinte campo em formato JSON:

Nome	Tipo	Descrição
authenticationCode	string	Código de autenticação da transação realizada.

JSON

{
  "authenticationCode": "string"
}

👍

Dica

Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status code	Código	Mensagem	Descrição
400	CASH_OUT_NOT_ALLOWED_OUT_OF_BUSINESS_PERIOD	Cash out not allowed out of business period	Não é permitido realizar Ted fora do horário bancário (das 7h às 17h).
400	CASHOUT_LIMIT_NOT_ENOUGH	Sender does not have sufficient cash out limit	A transação excede o limite de valor da transferência.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:

Nome do evento (name)	Descrição
TED_CASH_OUT_WAS_APPROVED	Transação aprovada pela análise de antifraude.
TED_CASH_OUT_WAS_CANCELED	Transferência cancelada por falta de saldo na conta.
TED_CASH_OUT_WAS_REPROVED	A transação foi reprovada pela equipe de análise antifraude.