IntroduçãoReferência de APICentral de AjudaObter SuporteStatus page
Atualizações

11/02/25 — Novo endpoint: Cancelar PIX Agendado!

by Karthen Júnior

Mudou de ideia? Então cancele seu o PIX Agendado com a rota PATCH /v1/transfer_requests/{id}/scheduled_cancel

Este endpoint permite cancelar, individualmente, um PIX que foi Agendado. Para isso, basta informar o ID da Transferência que é sempre disponibilizado no retorno do endpoint Transferência para Terceiros — POST /v1/transfer_requests na propriedade transfer_request_id.

Requisição exemplo

curl --request PATCH \
     --url 'https://api.iugu.com/v1/transfer_requests/AB2483B68CA624DC98A88AFC7D1565213/scheduled_cancel?api_token=seu-api_token' \
     --header 'accept: application/json'

Retorno exemplo

{
    "transfer_request_id": "E2483B68CA624DC98A88AFC7D1565213",
    "created_at": "2025-02-11T11:28:08-03:00",
    "amount_cents": 10,
    "transfer_type": "pix",
    "end_to_end_id": "E151119752025021114280e7d38e1745",
    "external_reference": null,
    "receipt_url": "https://comprovantes.iugu.test/e2483b68-ca62-4dc9-8a88-afc7d1565213-d52c04",
    "status": "cancelled"
}

Importante ⚠️

O status desta transferência deve ser scheduled. Se não, o erro abaixo será retornado:

{
  "errors": "Status da transferência deve ser igual a agendado."
}

Não tem acesso ao transfer_request_id?

Caso não tenha a este ID, utilize o endpoint Listar Comprovantes de Transferências para Terceiros — GET /v1/transfer_requests/. Busque pela transferência deseja e atente-se a propriedade id.

11/02/25 — PIX Agendado no ar!

by Karthen Júnior

Agora é possível agendar Transferências via PIX

O endpoint POST /v1/transfer_requests recebeu um novo parâmetro: scheduled_date. Este parâmetro permite agendar uma data para a realização deste PIX Out.

Requisição exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/transfer_requests?api_token=seu-api-token' \
     --header 'Request-Time: 2025-02-11T10:50:45-03:00' \
     --header 'Signature: signature=(assinatura-RSA)' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "scheduled_date": "2025-02-12",
  "transfer_type": "pix",
  "amount_cents": 500,
  "receiver": {
    "name": "Nome Sobrenome Fictício",
    "cpf_cnpj": "113.436.750-30",
    "pix": {
      "type": "email",
      "key": "iugu@iugu.com"
    }
  }
}
'

Retorno exemplo

{
  "transfer_request_id": "61756F81FD8C47629AEFDE3A8C17713C",
  "created_at": "2025-02-05T15:43:51-03:00",
  "amount_cents": 100,
  "transfer_type": "pix",
  "end_to_end_id": "E15111975202502051843d39ea29f4fb",
  "external_reference": null,
  "receipt_url": "https://comprovantes.iugu.test/61756f81-fd8c-4762-9aef-de3a8c17713c-b54c6d",
  "status": "scheduled",
  "scheduled_date": "2025-02-06"
}

Gatilho — Mudança de status de transferência para terceiros

Confira os dados que este gatilho envia quando acionado por este evento:

Sucesso

{
  "event": "transfer_request.done",
  "transfer_request_id": "7AB45C8123DE45678BC1234F6D7E8F90",
  "transfer_status": "done",
  "description": "",
  "amount_cents": "2500",
  "total_refunded_amount_cents": "",
  "transfer_type": "pix",
  "conciliation_id": "",
  "sender_account_id": "9876543210ABCDEF1234567890ABCDEF",
  "sender_name": "12345678000199 - EMPRESA XYZ (doc. approved)",
  "sender_cpf_cnpj": "12.345.***/****-99",
  "sender_bank_account_type": "checking_account",
  "sender_bank_account": "1234567",
  "sender_bank_name": "",
  "sender_bank_branch": "0001",
  "receiver_ispb": "60701190",
  "receiver_name": "João Silva",
  "receiver_cpf_cnpj": "123.***.***-45",
  "receiver_bank_name": "Banco do Brasil",
  "receiver_bank": "001",
  "receiver_bank_branch": "1234",
  "receiver_bank_branch_digit": "",
  "receiver_bank_account": "987654",
  "receiver_bank_account_digit": "",
  "receiver_bank_account_type": "checking_account",
  "receiver_pix_key": "12345678909",
  "statement": "F9876543210987654321ABCDEF123456",
  "done_at": "2025-03-10T14:30:00.000Z"
}

Falha

{
  "event": "transfer_request.status_changed",
  "transfer_request_id": "9EF12B45CD6789AB1234567890ABCDEF",
  "transfer_status": "rejected",
  "description": "",
  "amount_cents": "5000",
  "total_refunded_amount_cents": "",
  "transfer_type": "pix",
  "conciliation_id": "",
  "sender_account_id": "ABCDEF1234567890ABCDEF1234567890",
  "sender_name": "98765432000188 - EMPRESA ABC (doc. approved)",
  "sender_cpf_cnpj": "98.765.***/****-88",
  "sender_bank_account_type": "checking_account",
  "sender_bank_account": "654321",
  "sender_bank_name": "",
  "sender_bank_branch": "0001",
  "receiver_ispb": "60701190",
  "receiver_name": "Ana Souza",
  "receiver_cpf_cnpj": "321.***.***-76",
  "receiver_bank_name": "Santander",
  "receiver_bank": "033",
  "receiver_bank_branch": "4567",
  "receiver_bank_branch_digit": "",
  "receiver_bank_account": "123456",
  "receiver_bank_account_digit": "",
  "receiver_bank_account_type": "checking_account",
  "receiver_pix_key": "98765432101",
  "statement": "F9876543210987654321ABCDEF123456",
  "rejection_reason": "Insufficient Balance",
  "rejected_at": "2025-02-15T10:20:30.000Z"
}

31/01/25 — Status approved adicionado à Documentação dos Gatilhos de KYC

by Karthen Júnior

Atualização dos status dos Documentos de KYC

Identificamos a falta do status approved na documentação do gatilho Verificação de documentos de afiliados/subconta iugu — referrals.document_status_change.

Além disso, enxergamos a necessidade de explicação para cada status de cada um dos gatilhos:

Significados dos status

referrals.verification

  • accepted: Conta aceita e Verificada. Apta a transacionar.
  • rejected: Conta recusada e Não verificada. Não autorizada à transacionar.

referrals.bank_verification

  • accepted: Alteração de Domicílio Bancário aceita.
  • rejected: Alteração de Domicílio Bancário recusada.

referrals.document_status_change

  • pending_manual_analisys: Documento com análise pendente pelo Time de Prevenção.
  • requested: Documento recusado e reenvio solicitado. Utilize o endpoint para Reenviar Documentos para Verificar Conta iugu.
  • approved: Documento aprovado.

24/01/25 — Correção da descrição do parâmetro items

by Karthen Júnior

Ajustamos a descrição sobre limitação de items no endpoint Criar Fatura

A antiga descrição informava sobre o limite de 30 itens, porém, não deixava claro que esta limitação está presente apenas em ambiente de testes.

Deste modo, a descrição atual é: "Itens da fatura. O parâmetro price_cents tem o valor mínimo de 100. Limite de 30 itens em test_mode. Já live_mode não há limites."

23/01/25 — Otimização da Lista de Bancos para Verificação e Domicílio Bancário

by Karthen Júnior

Percebemos uma oportunidade de otimizar a organização e a clareza das tabelas que informam os padrões para preenchimento do nome e código do banco, além dos números de agência e conta. Com essa atualização, buscamos facilitar a consulta e a integração dos dados bancários.

As alterações foram aplicadas nas seguintes referências:

10/12/24 — +2 novos endpoints

by Karthen Júnior

Agora é possível buscar Faturas através do external_reference, order_id ou end_to_end!

Anteriormente, para consultar uma fatura na iugu, o dado principal utilizado era o invoice_id. No entanto, em diversas situações, esse identificador não era armazenado pelos nossos clientes, dificultando a consulta direta. Agora, com os novos endpoints, é possível realizar buscas utilizando outros parâmetros, como:

  • external_reference: Referência externa configurada no momento da criação da fatura.
  • order_id: Identificador do pedido atribuído durante a criação da fatura.
  • end_to_end: Código específico para transações realizadas ou reembolsadas via PIX.

Essa funcionalidade visa proporcionar maior flexibilidade e assertividade na localização de faturas.

Referências de Endpoints

DescriçãoEndpoint
Buscar Fatura por IDs externosGET /v1/resource_search
Buscar Fatura por ID Externos de SubcontasGET /v1/marketplace_resource_search

Importante ⚠️

Para utilizar esses endpoints, é necessário especificar o tipo de parâmetro no campo query_field e informar o valor correspondente em value.
Veja abaixo as opções disponíveis:

ParâmetroDescrição
external_idPara buscar faturas que possuem um valor específico configurado no campo external_reference durante a criação.
order_idPara localizar faturas utilizando o valor atribuído no parâmetro order_id no momento de sua criação.
end_to_endPara identificar faturas pagas ou reembolsadas via PIX, utilizando o código único de transação end_to_end fornecido pelo Banco Central.

Exemplo de Requisição - external_reference

curl --request GET \
     --url 'https://api.iugu.com/v1/resource_search?query_field=external_id&value=meu-external-id&api_token=seu-api_token' \
     --header 'accept: application/json'
  • query_field: Deve conter o valor external_id.
  • value: Insira o identificador externo configurado na fatura.

Exemplo de Requisição - order_id

curl --request GET \
     --url 'https://api.iugu.com/v1/resource_search?query_field=order_id&value=meu-order_id&api_token=seu-api_token' \
     --header 'accept: application/json'
  • query_field: Deve conter o valor order_id.
  • value: Insira o identificador de pedido configurado na fatura.

Exemplo de Requisição - end_to_end

curl --request GET \
     --url 'https://api.iugu.com/v1/resource_search?query_field=end_to_end&value=id-do-end_to_end&api_token=seu-api_token' \
     --header 'accept: application/json'
  • query_field: Deve conter o valor end_to_end.
  • value: Insira o código único da transação PIX.

Benefícios

  • Assertividade: Localize faturas com maior precisão utilizando identificadores alternativos.
  • Flexibilidade: Facilita o rastreamento mesmo quando o invoice_id não é salvo ou está indisponível.
  • Suporte PIX: Inclui a busca por transações realizadas via PIX, refletindo as demandas atuais do mercado.

Essa melhoria torna o gerenciamento de faturas mais eficiente e alinhado às necessidades de diferentes cenários operacionais.