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.

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 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

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`

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

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`

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

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

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 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:

Reconhecer que a nova cobrança é um registro independente.
Vinculá-la ao order_id para rastreamento.
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:

Alterar o schema para aceitar VARCHAR ou TEXT (até 128 caracteres).
Se houver parsing no código (ex: parseInt() em JavaScript), remover ou desativar.
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.