Transferência via TED

stable

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

Requisição

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/fund-transfers
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:

ScopeDescrição
ted.cashout.createConcede acesso para iniciar uma transferência de valores via TED.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.
x-correlation-idObrigatório. Informe um GUID, sendo um novo cada requisição.
Idempotency-KeyInformaçã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:

NomeTipoDescrição
senderobjectObrigatório. Objeto que deverá conter os dados do pagador da transação.
sender.documentstringObrigatório. Número do documento.
sender.namestringObrigatório. Nome do pagador.
sender.branchstringObrigatório. Agência bancária.
sender.accountstringObrigatório. Número da conta.
recipientobjectObrigatório. Objeto que deverá conter os dados do recebedor da transação.
recipient.accountTypestringTipo 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.documentstringObrigatório. Número do documento.
recipient.bankCodestringObrigatório. Código do banco.
recipient.branchstringObrigatório. Agência bancária.
recipient.accountstringObrigatório. Número da conta.
recipient.namestringObrigatório. Nome do recebedor.
amountstringObrigatório. Valor da transação.
descriptionstringDescrição da transferência.

📘

Nota

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

{
  "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:

NomeTipoDescrição
authenticationCodestringCódigo de autenticação da transação realizada.
{
  "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 codeCódigoMensagemDescrição
400CASH_OUT_NOT_ALLOWED_OUT_OF_BUSINESS_PERIODCash out not allowed out of business periodNão é permitido realizar Ted fora do horário bancário (das 7h às 17h).
400CASHOUT_LIMIT_NOT_ENOUGHSender does not have sufficient cash out limitO pagador não tem limite de saque suficiente.

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_APPROVEDTransação aprovada pela análise de antifraude.
TED_CASH_OUT_WAS_CANCELEDTransferência cancelada por falta de saldo na conta.
TED_CASH_OUT_WAS_REPROVEDA transação foi reprovada pela equipe de análise antifraude.