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 lançou que permite
realizar uma transferência para outra conta bancária que não necessariamente seja do
titular da conta iugu.

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 7 days ago