IntroduçãoReferência de APICentral de AjudaObter SuporteStatus page
Conceitos

Transferência para Terceiros

Documentação técnica da funcionalidade

Suggest Edits

📘

O que você irá aprender nesse artigo?

• Caso de Uso
• Regras para a Transferência para Terceiros
• Gatilho
• Autenticação
• Biblioteca RSA
• Exemplos de Requisição
• Possíveis Mensagens de Erro no Retorno
• Status de Transferência
• Consultando Status de Transferência

Caso de Uso

“Cliente entra no sistema e gostaria de realizar uma transferência via TED ou PIX para uma conta bancária de outra pessoa que não é o titular da conta”.

Diagrama de Sequência:

A transferência para terceiros é uma ferramenta que a iugu está lançando que permite
realizar uma transferência para outra conta bancária que não necessariamente seja do
titular da conta iugu. Esse processo está na fase beta para testes e permitirá realizar TED
e/ou PIX de acordo com algumas regras.

Regras de Transferência para Terceiros

Os bancos aceitos são os mesmos que constam na API de domicílio bancário, consulte aqui.

🚧

Atenção

Aplicam-se taxas para cada transação realizada, não esqueça de validar se sua Conta iugu possui saldo suficiente para cumprir o valor requisitado na transferência, somado ao valor da sua taxa. Consulte valores em sua página de plano.

Gatilho

Antes de realizar a requisição de transferência, crie um gatilho de
transfer_request.status_changed para receber as notificações de mudança de status da
solicitação. A notificação só será disparada após o processamento da transferência.
Nessa chamada utilize o live_token (token_api de produção).

curl --location --request POST 'https://api.iugu.com/v1/web_hooks' \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Basic {{token_api in base 64}}' \ 
--header 'Cookie: __cfruid=fc514b6aab26d4dae534fbd0f8b0722c61a054da-1648512345' \ 
--data-raw '{ 
 "event": "transfer_request.status_changed", 
 "url": "sua URL" 
}'

Leia mais sobre o Gatilho aqui.

Após configurar os gatilhos (notificação), a transferência poderá ser realizada.
Lembre-se de armazenar do seu lado o ID da transferência para consultar informações do processamento e/ou comprovante mais tarde.

Autenticação

A autenticação será utilizada no ambiente de teste a chave API test_token e no ambiente de
produção a chave API live_token. Entretanto, além da autenticação de chave de API, é necessário realizar o processo de Assinatura Digital para garantir a segurança do processo de envio de dinheiro.

🚧

RSA - Assinatura Digital e Validação de Assinatura

Para uma maior segurança das requisições de transferência, a assinatura da requisição
utilizando a tecnologia RSA é obrigatória.
Leia mais sobre o assunto aqui.

Também disponibilizamos algumas Libs (nas principais linguagens de desenvolvimento da atualidade) para facilitar o processo de Assinatura Digital, Validação de Assinatura, e Requisição de Transferência. Veja abaixo:
Biblioteca RSA

Após validar os passos de pré-requisitos, concluir a de assinatura digital (através ou não das nossas bibliotecas de RSA), a transferência poderá ser efetuada. Lembre-se de que a chamada para TED exige dados bancários e a transferência por PIX aceita o modelo de chave_pix ou dados bancários de conta corrente.

Acesse nossa Documentação API de Transferência para Terceiros.

Endpoint: https://api.iugu.com/v1/transfer_requests

Exemplos de Requisição

Modelo de TED:

curl--request POST\
--url https: //api.iugu.com/v1/transfer_requests \
	--header 'Request-Time: 2023-02-18T13:25:29-03:00'\
	--header 'Signature: signature=Dn85sW1cSIQ3wl/uek7TMIKdtBpH78fSVzbODDeDVqSsgGgWuQXUgQ9QriluXxJ9pNsMKsNkaD6sG3CI/qP+kUs29sm4m12N1JkdPSyUE/VE+2inDWczXzyuwZF3E+1w25M94osPDCT3tCPb0Cs45vpbdespx0lckhZ5zWZg00qSfK4aG2tC7CeGCNNr3ieL6nvRcDaLMmrPEvtXEejik2ZGHhq6FEqYRpEQ7CZPB+nOm+yjxwBJ0XDKf7uROLUr0ba7ziHa+yGm8NFvPFEFEA5f5lwTgdBgpO5khgk5DZJVyBO8Q4nghVEQLIn9U971hY9GYC8ewWWgpO+8ZCwr7A'\
	--header 'accept: application/json'\
	--header 'content-type: application/json'\
	--data ' {
"transfer_type": "ted",
"amount_cents": "2",
"description": "transferência ted",
"external_reference": "0001",
"api_token": "1212141412131"
"receiver": {
	"name": "Teste Teste",
	"cpf_cnpj": "12345678911"
  "bank": {
				"compe": "123", - "compe do banco com 3 digitos"
	      "branch": "1111", - Agência
	      "account": "123456",- Conta
	      "account_type": "checking_account",- Tipo de conta
          }
}
'

Modelo de PIX para Chave

curl--request POST\
--url https: //api.iugu.com/v1/transfer_requests \
	--header 'Request-Time: 2023-02-18T13:25:29-03:00'\
	--header 'Signature: signature=Dn85sW1cSIQ3wl/uek7TMIKdtBpH78fSVzbODDeDVqSsgGgWuQXUgQ9QriluXxJ9pNsMKsNkaD6sG3CI/qP+kUs29sm4m12N1JkdPSyUE/VE+2inDWczXzyuwZF3E+1w25M94osPDCT3tCPb0Cs45vpbdespx0lckhZ5zWZg00qSfK4aG2tC7CeGCNNr3ieL6nvRcDaLMmrPEvtXEejik2ZGHhq6FEqYRpEQ7CZPB+nOm+yjxwBJ0XDKf7uROLUr0ba7ziHa+yGm8NFvPFEFEA5f5lwTgdBgpO5khgk5DZJVyBO8Q4nghVEQLIn9U971hY9GYC8ewWWgpO+8ZCwr7A'\
	--header 'accept: application/json'\
	--header 'content-type: application/json'\
	--data ' {
"transfer_type": "pix",
"amount_cents": "2",
"description": "transferência pix para conta",
"external_reference": "00021",
"api_token": "1212141412131" 
"receiver": {
          "pix": {
               "type": "phone",
               "key": "+5511999999999"
          }
}
'

Modelo de PIX para Conta Bancária:

curl--request POST\
--url https: //api.iugu.com/v1/transfer_requests \
	--header 'Request-Time: 2023-02-18T13:25:29-03:00'\
	--header 'Signature: signature=Dn85sW1cSIQ3wl/uek7TMIKdtBpH78fSVzbODDeDVqSsgGgWuQXUgQ9QriluXxJ9pNsMKsNkaD6sG3CI/qP+kUs29sm4m12N1JkdPSyUE/VE+2inDWczXzyuwZF3E+1w25M94osPDCT3tCPb0Cs45vpbdespx0lckhZ5zWZg00qSfK4aG2tC7CeGCNNr3ieL6nvRcDaLMmrPEvtXEejik2ZGHhq6FEqYRpEQ7CZPB+nOm+yjxwBJ0XDKf7uROLUr0ba7ziHa+yGm8NFvPFEFEA5f5lwTgdBgpO5khgk5DZJVyBO8Q4nghVEQLIn9U971hY9GYC8ewWWgpO+8ZCwr7A'\
	--header 'accept: application/json'\
	--header 'content-type: application/json'\
	--data ' {
"transfer_type": "pix",
"amount_cents": "2",
"description": "transferência pix para conta",
"external_reference": "00021",
"api_token": "1212141412131"
},
"receiver": {
	"name": "Teste Teste",
	"cpf_cnpj": "12345678911",
  "bank": {
	"ispb": "ispb com 8 digitos",
	"branch": "1111", - Agência
	"account": "123456", Conta
	"account_type": "checking_account", - tipo de conta
  },
}
'

Possíveis Mensagens de Erro no Retorno

Status HTTPErro
400 Caso o transfer_type não seja informado ou seja em formato inválido. Exemplo: "transfer_type":"ted".
400Caso o compe e o ispb não sejam informados. (Pelo menos um deles deve ser informado na
requisição).
400Caso branch não seja informada. (Com exceção do tipo de conta de pagamento)
400Caso o amount_cents não seja informado ou não seja um número inteiro. (O mesmo erro é
retornado caso seja transferência por PIX).
400Caso o cpf_cnpj não seja enviado.
400Caso os dados do array receiver, os dados do array pix ou pix_key não sejam informados.
400Caso pix.type não seja informado.
400Caso o receiver.bank informado seja diferente da conta Pix, enviar dados bancários e chave Pix e
iremos validar se os dados coincidem.
400Caso amount.cents enviado seja maior que o saldo disponível na conta.
400Caso amount.cents enviado seja menor que o valor de R$0,02.
400Caso o account_type seja inválido.
404Caso pix.key informado não estiver cadastrado/vinculado a nenhuma conta bancária.

📘

Atenção

A requisição retornará 200 se todos os campos informados estiverem corretos. No entanto,
isso não significa que a transferência será processada com sucesso. Por exemplo, caso no
campo transfer_type for informado o conteúdo “tedi”, a requisição retornará erro pois o
formato do transfer_type está incorreto. Se o campo for informado como “ted” e todos os
demais campos estiverem corretos, a requisição retornará status HTTP 200, mas a
transferência pode ser recusada pelo banco de destino.

Status

Abaixo segue a lista de todos os status possíveis para a transferência para terceiros:

Pending = Transferência pendente. Status retornado no momento da criação;
Processing = Processando. Transferência foi enviada para processamento;
Rejected = O banco destino rejeitou, dados inválidos;
Done = Concluído. Esse status pode mudar para rejected (dentro de 24hs, após isso é
status final).

Status exclusivos para PIX

Refunded = Transferência reembolsada. Status retornado caso a transferência seja devolvida;
Partially Refunded = Transferência parcialmente reembolsada. Status retornado caso a transferência seja parcialmente devolvida;

*O status done pode ser status final, quando a transferência foi executada com sucesso, ou
pode se tornar rejected quando a comunicação foi realizada com sucesso, mas o banco de
destino recusou a transferência. Done pode ser considerado status final se passar 24hs
nesse status. No caso de pix, done é sempre status final.

Próximo Status Possível

Dado o status inicial, veja quais status as transferências podem assumir:

Pending => Pode se tornar rejected_ou _done;
Processing=> Pode se tornar rejected ou done;
Done=> Pode ser status final ou se tornar rejected;
Rejected => Status final;

Done é status final se continuar nesse status após 24hs. Dentro desse período ele pode se
tornar Rejected.

Consultando uma Transferência para Terceiros

Para essa chamada será necessário ter o id da transferência para a consulta.
Utilize a nossa Documentação API de Consulta de Transferência para Terceiros

Modelo de Request: 

curl --location --request GET
'https://api.iugu.com/v1/transfer_requests/A480797C10D84053A480D7C37C6FFFFF' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Request-Time: 2022-06-08T15:35:06-03:00' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid={{cookie}}'

Lembrem-se de consultar nosso time de Suporte e Atendimento caso possuam alguma dúvida!

Updated about 1 year ago