Liquidação e Recebedores

Para um consolidado completo de todas mudanças da API, detalhes de prazo para conclusão dos ajustes e contatos de suporte, acesse a página Visão Geral das mudanças da API.

Resumo das mudanças em Liquidação e Recebedores

Detalhes das mudanças

1. GET /core/v5/recipients/{recipient_id}/balance — Mudança nos campos

• O que muda: 4 campos deixarão de ser preenchidos no response e passarão a retornar null após o fim da janela de deprecação, sendo eles: transferred_amount, recipient.type, recipient.updated_at e recipient.description. Além disso, será adicionado no response o retorno do campo payment_profile_id, consulte o item 4 dessa página para mais detalhes.

• Impacto: integrações que dependem desses campos deixarão de recebê-los no response.

• Ação necessária: remova as dependências desses campos da sua integração. Esses campos descontinuados não terão substitutos.

---

2. Identificador de settlements — Mudança no formato do id

• O que muda: mudança no formato do id de settlement , conforme exemplos abaixo.

  • Antes: sett_cm3kx7t2n0a4b1jn12h95wzq8
  • Depois: 0000A978-24A7-0822-902E-FFFFFFAC08DD

• Impacto: sistemas que dependem do padrão atual (ex.: regex, tamanho fixo, prefixo "sett_")
  precisarão ser atualizados.

• Ação necessária: ajuste sua integração para não depender do padrão atual, lembrando que os dois formatos podem coexistir.

---

3. Objeto settlements — Mudança nos campos

• O que muda: 4 campos deixarão de ser preenchidos no response e passarão a retornar null após o fim da janela de deprecação, sendo eles: liquidation_arrangement_id, liquidation_type, contract_obligation_id e contract_key. Além disso, será adicionado no response o retorno do campo payment_profile_id, consulte o item 4 dessa página para mais detalhes.

• Impacto: integrações que dependem desses campos que serão descontinuados receberão como null no response dos endpoints GET /core/v5/settlements, GET /core/v5/recipients/:recipientId/settlements e GET /core/v5/settlements/{settlement_id}.

• Ação necessária: remova as dependências desses campos da sua integração. Esses campos descontinuados não terão substitutos.

---

4. Identificador de recipients — Novo formato de id e novo campo de resposta para novos recebedores

• O que muda: recebedores já existentes continuam com o id no formato atual (exemplo: re_cm73p9wq1tzbx4n5f2h6jkxa8) e seguem sendo retornados no campo recipient_id nos responses, nenhuma alteração para quem já usa esse padrão. Novos recebedores após essa janelas podem ter id no formato pp_ (exemplo: pp_4h8dxst2c9nyv615jbewql3fp), retornado em um novo campo, payment_profile_id.
  
  Os dois formatos coexistirão, portanto pode ocorrer cenários de um retornar null quando o outro estiver preenchido. Os endpoints que aceitam re_ também aceitarão pp_ , segue uma tabela detalhando quais desses endpoints terão suporte ao payment_profile_id e qual impacto a nível de requisição e response.

• Impacto: sistemas que hoje leem exclusivamente o campo recipient_id não encontrarão o identificador de recebedores no novo formato, pois ele estará em payment_profile_id. Também podem falhar validações que dependam de regex, tamanho fixo ou prefixo re_.

• Ação necessária: ajuste sua integração para ler tanto recipient_id quanto payment_profile_id ao processar respostas que envolvam recebedores e aceitar ambos os formatos (re_ e pp_) como válidos, evitando validações presas a um prefixo ou tamanho único. Assim como ajuste do filtro, caso seja necessário.

---

Perguntas frequentes das mudanças em Liquidação e Recebedores