Mudanças da API: Liquidação e Recebedores

Mudanças da API v5 em Liquidação e Recebedores: saldo do recebedor, settlements e novo formato de id.

Documentação legada do Pagar.me v5

Esta página descreve um conceito da Pagar.me v5 (versão clássica). Para projetos novos, explore o API Catalog.

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

	Método	Endpoint	Mudança
1	GET	`/core/v5/recipients/{recipient_id}/balance`	Campos `transferred_amount`, `recipient.type`, `recipient.updated_at` e `recipient.description` retornarão `null`
2	—	Identificador de `settlements`	Mudança no formato do `id`
3	—	Objeto `settlements`	Campos `liquidation_arrangement_id`, `liquidation_type`, `contract_obligation_id` e `contract_key` retornarão `null` e campo `payment_profile_id` será adicionado
4	—	Identificador de `recipients`	Novo formato de `id` e novo campo de resposta para novos recebedores

Detalhes das mudanças

Como ler essa seção?

Abaixo, temos o formato de como cada ajuste será apresentado nessa seção.

Endpoint: método e rota afetados.
O que muda: descrição técnica da alteração.
Impacto: consequência prática na sua integração.
Ação necessária: o que você precisa fazer (quando aplicável).
Exemplo: request/response ilustrativo (quando aplicável).

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.

Método	Endpoint	Path Params	Query Param	Response
GET	`/core/v5/recipients/{recipient_id}/balance`	✅		✅
POST	`/core/v5/recipients/{recipient_id}/bulk_anticipations`	✅
GET	`/core/v5/recipients/{recipient_id}/bulk_anticipations`	✅
GET	`/core/v5/recipients/{recipient_id}/bulk_anticipations/limits`	✅
POST	`/core/v5/recipients/{recipient_id}/bulk_anticipations/simulate`	✅		✅
GET	`/core/v5/recipients/:recipientId/settlements`	✅
GET	`/core/v5/recipients/:recipient_id/receivable-units`	✅
GET	`/core/v5/payables`		✅	✅
GET	`/core/v5/settlements`			✅
GET	`/core/v5/settlements/{settlement_id}`			✅

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.

Mudança no identificador de `recipients` não afetará Marketplace

Essa mudança** é válida apenas para o recebedor principal** e não se aplica ao Marketplace.

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

Existe ambiente de sandbox para testar as mudanças antes do go-live?

Sim. Iremos fornecer respostas de exemplo nas principais mudanças no ambiente de sandbox já utilizado atualmente na sua integração. Você poderá acessá-lo com suas credenciais de teste normais. Detalhes estão disponíveis em "Testes de integração" na página "Visão Geral das mudanças da API".

O formato do settlement_id está mudando também. Como trato isso?

Os dois formatos podem coexistir durante a transição. Não dependa do prefixo sett_ ou de tamanho fixo no seu código.

Exemplo antes: sett_cm3kx7t2n0a4b1jn12h95wzq8
Exemplo depois: 0000A978-24A7-0822-902E-FFFFFFAC08DD