--- title: "Mudanças da API: Pagamentos (legado)" url: "https://devcenter.stone.com.br/legacy-mudancas-api-pagamentos" image: "https://devcenter.stone.com.br/_og/d/c_Ocean.takumi,title_~TXVkYW7Dp2FzIGRhIEFQSTogUGFnYW1lbnRvcyAobGVnYWRvKQ,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMzMEE2NkQifX19,p_Ii9sZWdhY3ktbXVkYW5jYXMtYXBpLXBhZ2FtZW50b3Mi,s_WS59mhzaIgEixGqN.png" --- # Mudanças da API: Pagamentos Mudanças da API v5 em Pagamentos: padrão ABECS no acquirer\_return\_code, reprocessamento, Gateway\_Id e cancelamento de boleto via TED. 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 Pagamentos](#resumo-das-mudanças-em-pagamentos) | | Método | Endpoint | Mudança | | :-- | :----- | :----------------------------- | :------------------------------------------------------------------------------- | | 1 | POST | /core/v5/orders | acquirer_return_code passa a seguir padrão ABECS | | 2 | — | Reprocessamento de cobranças | Geração de novo charge_id | | 3 | — | Response transacional | Charge.Gateway_Id e Transaction.Gateway_Id podem passar a ser alfanuméricos, necessário garantir tratamento como string | | 4 | — | Cancelamento de boleto via TED | Funcionalidade será descontinuada | ## [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\. `POST /core/v5/orders` — Padrão ABECS no `acquirer_return_code`](#_1-post-corev5orders-padrão-abecs-no-acquirer_return_code) - **O que muda:** o campo `acquirer_return_code` passa a seguir o padrão **ABECS**. - **Impacto:** integrações que interpretam ou tratam códigos de retorno do adquirente precisam ser atualizadas para o novo padrão. - **Ação necessária:** atualize o tratamento de códigos de retorno na sua integração para o padrão ABECS. Para mais detalhes acesse [aqui](https://devcenter.stone.com.br/legacy-mudancas-api-codigos-abecs) --- ### [2\. Reprocessamento de cobranças — Geração de novo `charge_id`](#_2-reprocessamento-de-cobranças-geração-de-novo-charge_id) - \*\*O que muda: \*\*quando uma cobrança reprovada pelo antifraude é elegível para reprocessamento, o sistema **passará a criar uma nova cobrança com um **`charge_id`** distinto.** Antes, a nova tentativa era adicionada à mesma cobrança, mantendo o `charge_id` original. - **Impacto:** A cobrança original permanece inalterada com seu status final (`failed`/`cancelled`) e o reprocessamento gera uma nova cobrança com seu próprio `charge_id`,\*\* \*\*ambas vinculadas ao mesmo `order_id` ou `invoice_id`. Integrações que acompanham o ciclo de vida de uma cobrança pelo `charge_id` serão afetadas nas três frentes abaixo. - Webhooks de atualização de status chegarão com o `charge_id` da nova cobrança, não com o original. - Consultas à API pelo `charge_id` original retornarão a cobrança com seu status final, sem refletir a nova tentativa; - Fluxos de conciliação que identificam tentativas de pagamento pelo `charge_id` precisarão reconhecer o novo registro como uma entrada independente. - \*\*Ação necessária: \*\*utilize o `order_id` ou `invoice_id` como chave de busca para localizar todas as cobranças de um pedido, incluindo as geradas por reprocessamento. Atualize seus fluxos de webhook, consultas de API e conciliação para tratar o `charge_id` da nova cobrança corretamente, não como atualização da cobrança original, mas como um registro independente vinculado ao mesmo pedido. --- ### [3\. Response transacional — Formato do `Gateway_Id`](#_3-response-transacional-formato-do-gateway_id) - **O que muda:** os campos `Charge.Gateway_Id` e `Transaction.Gateway_Id` no response transacional já são `string`, mas atualmente são retornados com valores numéricos e **passarão a ser alfanuméricos**. - **Impacto:** integrações que armazenam ou processam esses campos como tipo numérico (ex.: coluna `INTEGER`/`BIGINT` em banco de dados, parsing como `int`) serão impactadas. - **Ação necessária:** valide se esses campos são tratados como `string` em sua integração. Caso não seja, ajuste o schema do banco de dados, tipagem e parsing para suportar valores alfanuméricos (`string`) com até **128 caracteres**. --- ### [4\. Cancelamento de boleto via TED](#_4-cancelamento-de-boleto-via-ted) - **O que muda:** a funcionalidade de estorno de boletos via TED será descontinuada. - **Impacto:** clientes que utilizam essa funcionalidade deixarão de poder realizar estornos de boletos por esse método. - **Ação necessária:** revise os fluxos operacionais que dependem dessa funcionalidade. --- ## [Perguntas frequentes das mudanças em Pagamentos](#perguntas-frequentes-das-mudanças-em-pagamentos) **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 padrão ABECS em acquirer\_return\_code é compatível com meu sistema?** Depende de como você trata esses códigos. Se você tem mapeamentos customizados ou uma tabela de lookup, será necessário atualizar para o padrão ABECS. Consulte a documentação de [códigos de retorno ABECS para a tabela de mapeamento](https://docs.pagar.me/docs/c%C3%B3digos-de-retorno-padr%C3%A3o-abecs) para mais detalhes. **Quando uma cobrança é reprocessada após falha de antifraude, ela recebe um novo charge\_id. Isso afeta meus webhooks?** Sim. Os webhooks de atualização de status chegarão com o `charge_id` da nova cobrança, não com o do original. Sua integração de webhooks precisa: 1. Reconhecer que a nova cobrança é um registro independente. 2. Vinculá-la ao order\_id para rastreamento. 3. Não sobrescrever o status da cobrança original — ambas devem ser consultáveis. **Por que o gateway\_id está mudando de numérico para alfanumérico no response transacional? Isso quebra minha integração?** Sim, se sua coluna de banco de dados for `INTEGER` ou `BIGINT`. Você precisa: 1. Alterar o schema para aceitar `VARCHAR` ou `TEXT` (até 128 caracteres). 2. Se houver parsing no código (ex: `parseInt()` em JavaScript), remover ou desativar. 3. Se houver validação regex, atualizar para aceitar alfanuméricos. Recomendamos fazer essas alterações antes do fim da janela, para permitir armazenar ambos os formatos durante a transição. 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.