--- title: "Mudanças da API: Liquidação e Recebedores (legado)" url: "https://devcenter.stone.com.br/legacy-mudancas-api-liquidacao-recebedores" image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_~TXVkYW7Dp2FzIGRhIEFQSTogTGlxdWlkYcOnw6NvIGUgUmVjZWJlZG9yZXMgKGxlZ2Fkbyk,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii9sZWdhY3ktbXVkYW5jYXMtYXBpLWxpcXVpZGFjYW8tcmVjZWJlZG9yZXMi,s_TKRZstdwkbpzfAQ-.png" --- # 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](https://devcenter.stone.com.br/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.](https://devcenter.stone.com.br/legacy-mudancas-api-visao-geral) ## [Resumo das mudanças em Liquidação e Recebedores](#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](#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](#_1-get-corev5recipientsrecipient_idbalance-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`](#_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](#_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](#_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](#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. 1. Exemplo antes: `sett_cm3kx7t2n0a4b1jn12h95wzq8` 2. Exemplo depois: `0000A978-24A7-0822-902E-FFFFFFAC08DD` Siga a Stone nas redes sociais [](https://www.facebook.com/stonepagamentos/)[](https://x.com/sejastone/)[](https://www.instagram.com/stone/)[](https://br.linkedin.com/company/stone-co)[](https://www.youtube.com/channel/UCk4L4JykgoDkN8YeuxkNqIQ) © Stone Instituição de Pagamento S.A. CNPJ 16.501.555/0001-57 Av. Rebouças, 2880, 4º andar, Pinheiros, CEP 05.402-500 – São Paulo/SP Instituição de pagamento autorizada pelo Banco Central do Brasil, nas modalidades de credenciadora e emissora de moeda eletrônica.