A versão de API utilizada define quais parâmetros você pode enviar nas requisições que vêm da sua loja online para o Pagar.me e quais as propriedades que estas vão retornar. Basicamente, ela é um dos definidores de quais funcionalidades você pode vir a usufruir em sua conta com o Pagar.me. Lembrando que algumas funcionalidades só são disponibilizadas mediante acordo comercial. 

Para descobrir qual versão da API está cadastrada em sua conta, basta seguir o caminho Configurações -> Chaves de API -> Versionamento de API e verificar a versão disponibilizada na tela. 

Quais mudanças entre as versões são retrocompatíveis?

• Criação de novas rotas na API;
• Adição de parâmetros opcionais na requisição;
• Adição de propriedades na resposta da API;
• Alteração na ordem das propriedades da resposta;
• Alteração dos formatos de ids;
• Adição de novo status em um evento de postback já existente;

Quais mudanças entre as versões não são retrocompatíveis?

• Adição de parâmetro obrigatório na requisição;
• Adição de eventos de postback;
• Alteração da validação de um parâmetro na requisição;
• Alteração da rota de um recurso;
• Alteração ou criação de códigos de resposta;
• Alteração de valores padrão;
• Remoção de parâmetros na requisição;
• Remoção de propriedades na resposta ou postback.

E o que muda de uma versão para outra?

Antes de passarmos pelas diferenças entre cada versão da API, é importante ressaltar que você pode alterar a versão sempre que quiser. Entretanto, quando fizer isto pelo Pagar.me, certifique-se de que está amparado tecnicamente para que as requisições de sua plataforma de e-commerce estejam de acordo com o novo versionamento selecionado. 

Requisições que venham da plataforma e não estejam de acordo com a versão da API registrada no Pagar.me podem ocasionar problemas como falta de criação de transações, entre outros. 

Versão 1 - 2013-03-01

Versão inicial da API.

Versão 2 - 2017-07-17

• O parâmetro customer.document_number passa a ser obrigatório para a criação de transações com payment_method=boleto
• O parâmetro customer.name passa a ser obrigatório para a criação de transações com payment_method=boleto
• Um novo evento de postback passa a ser enviado quando uma transação de boleto muda do status processing para waiting_payment

Versão 3 - 2017-08-28

Os campos para criar transações por companhias com antifraude ligado passaram por vastas alterações. Foram implementados features às rotas customers e transactions para permitir análises de fraude ainda mais robustas.

O objeto customer foi dissociado em customer, billing e shipping, nos quais constam, respectivamente, os dados do cliente, os dados de cobrança e os dados de envio. billing e shipping estão associados a transaction. Adicionalmente, foi criado o objeto items, também associado a transaction, que coleta informações sobre os itens da compra.

Os parâmetros customer, billing e items passam a ser obrigatórios para transações com cartão de crédito e antifraude habilitado.

Para criação de boletos, os campos country, documents e type dentro de customer passam a ser obrigatórios.

• Parâmetros obrigatórios adicionados a customer: external_id, type, country, phone_numbers, documents. Para mais informações, clique aqui.
• Parâmetros removidos de customer: document_number, document_type, gender, sex, born_at, phone e address. Para mais informações, clique aqui.
• Parâmetro criado: billing. Inclui os campos obrigatórios name e address. Para mais informações, clique aqui.
• Parâmetro criado: items. Inclui os campos obrigatórios id, title, unit_price, quantity e tangible. Para mais informações, clique aqui.
• Parâmetro opcional criado: shipping. Inclui os campos obrigatórios name, fee e address. Para mais informações, clique aqui.
• Novos status de transações podem agora ser enviados dentro do payload de um postback.
• Eliminação do comportamento de preenchimento dos campos de endereço a partir do CEP (presente nas versões 2013-03-01 e 2017-07-17).

Versão 4 - 2019-09-01

Foi alterado o formato do arquivo exportado na rota /recipients/:id/balance/operations.(csv|xlsx), traduzindo alguns textos que antes estavam em inglês e formatando os valores monetários.

Os campos e suas alterações foram:

• Tipo da operação - tradução para o português e alteração de valores.
  • payable agora é Transação
  • refund agora é Estorno
  • transfer agora é Transferência
  • chargeback agora é Chargeback
  • chargeback_operation agora é Operação de chargeback
  • fee_collection agora é Operação de saldo
  • block_operation agora é Operação de bloqueio
  • prepaid_card_transfer agora é Transferência de cartão pré-pago
• Método de pagamento - tradução para o português
• Entrada bruta, Saída bruta, Taxa de operação, Taxa de antecipação, Taxa total da operação, Entrada líquida e Saída líquida - formatação do valor monetário com virgula.