Changelog

Comunicação de atualizações e melhorias.

Outubro, 2026

`startDate` de pedidos e assinaturas é no horário de Brasília

O startDate do POST /v2/orders e do POST /v2/subscriptions é uma data no horário de Brasília (America/Sao_Paulo). A data de hoje cobra na hora, e uma data futura agenda a cobrança. Se o seu sistema usa UTC por padrão, converta para o horário de Brasília antes de enviar: depois das 21h, a data UTC já é o dia seguinte e o pedido fica agendado em vez de cobrado. A regra não mudou: a documentação passou a deixar isso explícito.

Pedido: para cobrar na hora, envie a data de hoje em Brasília ou não envie o campo.
Assinatura: o startDate é obrigatório e define a data da primeira cobrança.

A referência de criar pedido e os guias de pedido e assinatura foram atualizados.

Pedido com pré-captura só fica pré-autorizado depois da autorização

Pedidos criados com capture: false passam a nascer com status SENT e vão para PRE_AUTHORIZED quando a cobrança é de fato pré-autorizada. Antes, o pedido já nascia PRE_AUTHORIZED e o webhook order.pre_authorized podia chegar antes da autorização: no 3DS com desafio, a captura falhava e nenhum webhook avisava quando a pré-autorização ficava disponível.

Webhooks: o pedido passa a gerar order.sent na criação, seguido de order.pre_authorized quando a cobrança é pré-autorizada, igual ao fluxo com capture: true (order.sent seguido de order.paid).
3DS com desafio: o order.pre_authorized só é enviado depois que o comprador conclui a autenticação. Enquanto isso, o pedido fica SENT e pode ser cancelado.
Desafio concluído depois do cancelamento automático: se o pedido foi cancelado por desafio não concluído e o comprador conclui a autenticação depois, a cobrança fica pré-autorizada e o pedido volta para PRE_AUTHORIZED, com um novo order.pre_authorized. Capture ou cancele a pré-autorização normalmente.
Resposta da criação: sem desafio, o POST /v2/orders continua retornando o pedido PRE_AUTHORIZED.

A explicação da pré-captura foi atualizada.

Atualizar vendedor aceita o domínio CHARGE nos webhooks

O PATCH /v2/seller passa a aceitar CHARGE (Transação) em webhooks[].domains, para receber os eventos charge.refund.* do novo fluxo de estorno. Os domínios aceitos são ORDER, SUBSCRIPTION e CHARGE, e CHARGE exige version "2.0".

Também mudou o tratamento de erro:

Domínio inválido passa a retornar HTTP 400. Antes, na criação, o domínio era descartado sem aviso.
Webhook que não pôde ser salvo passa a aparecer como erro na resposta. Antes a resposta podia vir com sucesso trazendo os dados antigos.

A referência do endpoint foi atualizada com o campo domains.

Captura de pré-autorização devolve o resultado real em mais casos

A captura (POST /v2/charges/{uuid}/capture) continua respondendo HTTP 200 e informando o resultado em status e retryable. Dois casos passam a refletir o que de fato aconteceu:

Autorização expirada na adquirente: a cobrança passa a voltar CANCELED com retryable: false. Antes voltava PRE_AUTHORIZED com retryable: true, e novas tentativas falhavam de novo.
Cobrança já capturada: quando uma tentativa anterior já tinha capturado o valor, a resposta passa a ser PAID com retryable: false. Antes voltava PRE_AUTHORIZED.
Pagamento já cancelado: quando a pré-autorização já tinha sido cancelada no provedor, a resposta passa a ser CANCELED com retryable: false. Antes voltava PRE_AUTHORIZED com retryable: true.

Os campos e os códigos HTTP não mudam. A descrição das respostas possíveis foi atualizada.

Setembro, 2026

Busca de pedido informa o motivo da recusa e recusas 3DS ganham código próprio

A busca de pedido (GET /v2/orders/{uuid}) passou a devolver failureReason em cada cobrança com status FAILED, com o mesmo conteúdo que a busca de cobrança (GET /v2/charges/{uuid}) já devolve:

{
  "charges": [{
    "status": "FAILED",
    "failureReason": {
      "code": "BAR-7068",
      "title": "three_ds_authentication_failed",
      "description": "Não foi possível validar a autenticação do cartão",
      "action": "Refaça a autenticação com seu banco ou utilize outro cartão"
    }
  }]
}

Além disso, três motivos de recusa que antes caíam em BAR-7005 (erro genérico) passam a ter código próprio na tabela de Códigos de Erro, tanto no erro 400 da criação quanto no failureReason das buscas:

comprador não passou na autenticação 3DS → BAR-7068
autenticação 3DS indisponível para o cartão → BAR-7951 (novo)
cartão que não aceita transação internacional → BAR-7021

O campo é adicionado à response e não altera nada de quem já integra. Nenhum código existente muda de significado ou de mensagem.

Novos códigos de erro para cobranças de cartão

Adicionamos 8 códigos novos à tabela de Códigos de Erro: BAR-7068 (autenticação 3DS, já em produção e agora documentado) e BAR-7922, BAR-7930, BAR-7945, BAR-7970, BAR-7991, BAR-7992 e BAR-7993, que cobrem motivos de recusa que antes caíam em BAR-7005 (erro genérico).

Nenhum código existente muda de significado ou de mensagem — esta é uma adição pura ao catálogo público.

Assinatura de Webhook com HMAC-SHA256

Os webhooks da Barte passam a suportar assinatura digital via HMAC-SHA256. O recurso é opcional e retrocompatível — quem não configurar continua recebendo webhooks normalmente.

Para ativar, basta informar generateSecret: true (geração automática) ou um secret próprio de 32 a 64 caracteres no cadastro do webhook via POST /v2/seller. Quando configurado, cada entrega passa a incluir três novos headers: X-Webhook-Timestamp, X-Webhook-Nonce e X-Webhook-Signature, que permitem verificar a autenticidade e integridade do payload recebido.

O secret é exibido uma única vez, no momento da criação. Nas consultas subsequentes, a API retorna apenas um preview com os 5 primeiros caracteres.

Veja como implementar a verificação no seu sistema: Assinatura de Webhook (HMAC-SHA256)

Novo endpoint de estorno de cobrança

O estorno de cobrança passou a ter um endpoint próprio, que atende cartão de crédito e PIX, aceita estorno total ou parcial e processa de forma assíncrona: o 202 Accepted confirma que a Barte aceitou o pedido, não que o dinheiro já voltou ao comprador.

A resposta devolve o estorno recém-criado, com o uuid que identifica aquele estorno específico nos webhooks e no array refunds[] da cobrança — o que importa quando há vários estornos parciais na mesma cobrança.

A criação aceita o header opcional x-idempotency-key: reenviar a mesma chave para a mesma cobrança devolve o estorno já criado em vez de duplicar. Recomendado para proteger contra retentativas de rede.

Detalhes, códigos de erro e exemplos em Estornar Cobrança.

Estornos agora são identificáveis na consulta de cobrança e no webhook

Cada item de refunds na consulta de cobrança passou a informar:

uuid — identificador do estorno, o mesmo que aparece no webhook, para correlacionar os dois;
createdAt — data e hora de criação do estorno, em UTC;
idempotencyKey — a chave enviada no header x-idempotency-key ao criar o estorno, quando houver.

O objeto de estorno do webhook v2 de cobrança também passou a trazer o idempotencyKey, permitindo reconciliar o evento com o pedido que originou a operação sem depender de identificador nosso.

Os campos são adicionais e nenhum comportamento existente mudou. Uma observação sobre o campo date, que continua igual: ele informa a última atualização do estorno e muda quando ele sai de PROCESSING — para a data em que o estorno foi criado, use createdAt.

Estornos criados antes de o identificador existir não trazem uuid, e estornos criados sem chave de idempotência não trazem idempotencyKey — em ambos os casos o campo é omitido, nunca nulo.

Agosto, 2026

Consulta de cobrança agora informa o motivo da recusa

A busca de cobrança (GET /v2/charges/{uuid}) passou a devolver o campo failureReason quando a cobrança está com status FAILED, com o motivo da recusa informado pelo provedor:

{
  "status": "FAILED",
  "failureReason": {
    "code": "BAR-7006",
    "title": "insufficient_funds",
    "description": "Saldo Insuficiente",
    "action": "Verifique com seu banco emissor se há limite suficiente no cartão. Após, tente novamente"
  }
}

O conteúdo é o mesmo que a criação de cobrança já devolve no erro 400, então quem trata recusa nos dois fluxos passa a ler a mesma informação em ambos.

Antes, recusas confirmadas de forma assíncrona — caso típico de cartão com autenticação 3DS, em que a recusa chega depois da resposta da criação — só informavam status: FAILED, sem motivo. Com isso dá para distinguir saldo insuficiente de suspeita de fraude, cartão inválido ou falha na autenticação, e decidir se vale retentar, pedir outro cartão ou orientar o cliente final.

O campo é adicionado à response e não altera nada de quem já integra. Ele é omitido quando a cobrança não está recusada, e também quando a tentativa recusada não tem motivo informado pelo provedor.

Julho, 2026

Campo title de pedidos agora aceita 255 caracteres

O campo title da criação de pedidos (POST /v2/orders) passou a aceitar até 255 caracteres. O limite anterior era de 60.

A mudança já está disponível em Sandbox e Produção e não exige nenhuma ação de quem já integra: títulos com até 60 caracteres continuam funcionando exatamente como antes.

Com isso, sellers que enviam nomes de produto padronizados — e-commerces e marketplaces, por exemplo — deixam de ter pedidos recusados por exceder o limite do campo. O novo tamanho também vale para o title retornado nas responses de pedidos e cobranças.

Março, 2026

Atualização importante sobre Webhooks na API de Sellers

Clientes que utilizam o campo webhook devem iniciar a migração para o novo array webhooks.

O campo webhook foi oficialmente depreciado e será mantido temporariamente apenas para não quebrar integrações existentes. A nova estrutura permite múltiplos webhooks por seller, com controle de eventos (domains), status (active) e identificador único (uuid).

As responses de POST, GET e PATCH já retornam o array webhooks em Sandbox e Produção.

Novas integrações devem utilizar exclusivamente webhooks. O campo webhook poderá ser removido em versões futuras da API. Veja mais detalhes em: Alterações nos Endpoints de Sellers – Sandbox e Produção

Janeiro, 2026

Atualização importante sobre Early Buyer

Clientes que utilizam o recebimento no fluxo de tempo (timeline) não podem mais realizar transações via Early Buyer.

O Early Buyer é um produto baseado em cálculo de juros e antecipação, o que não se aplica a operações em timeline. Manter esse cruzamento gerava inconsistências operacionais.

Tentativas de uso do Early Buyer na API de sellers em operações com timeline resultarão em erro. Não há impacto para clientes que já operam fora do fluxo de timeline.

Dezembro, 2025

Atualização – API de Extrato

A partir de 17/12/2025, o endpoint GET /v2/report/statement passará a incluir um novo campo - uuid - em cada objeto retornado no array de resposta. Esse identificador único foi adicionado para facilitar o tratamento individual dos itens do extrato. Ver mais detalhes.

Outubro, 2025

Novos campos no objeto de Cobranças (Charges)

A partir do dia 29 de outubro de 2025, dois novos campos "acquirerAuthorizationCode" e "acquirerAuthorizationNsu" serão retornados no objeto da cobrança (Charge) em ambiente de Sandbox. Veja mais informações sobre os endpoints afetados: Ver mais detalhes.

Atualização na API de Vendedores

No dia 15/10/2025, os endpoints da Sellers API v2 (POST, GET e PATCH) passaram a exigir novos campos obrigatórios. As alterações já estão em vigor nos ambientes de Sandbox e Produção. Veja mais na referência de cada um: Criar Vendedor | Buscar Vendedor | Atualizar dados bancários do Vendedor

Setembro, 2025

Transações elegíveis para estorno

Agora, o usuário poderá consultar se uma transação é elegível ou não para um estorno parcial ou total acessando seus detalhes no portal do intermediador. Para saber mais, acesse o Portal do Intermediador.

Melhoria na lógica com o SDK Web

Antes, era preciso fazer as ações separadamente, como criar sessão, comprador (buyer) e pedido (order). Com essa nova alteração, esse fluxo foi abstraído em uma única chamada, centralizando a lógica e simplificando a integração. Veja mais dentro da seção de SDK.

Last updated 1 day ago

Was this helpful?