# Developer Platform
Welcome to your team’s developer platform
## **Documentação Barte**
Seja bem-vindo(a) à nossa documentação! Aqui você encontrará guias práticos, detalhes sobre nossos portais e uma referência de api detalhada que te ajudará no processo de integração.
Referência API
***
### :grip-dots-vertical:Navegue pelos nossos produtos
Cover image
Referência API
Utilize a nossa referência de api para realizar as chamadas e conseguir integrar de forma fácil e tranquila.
# Bem-vindo à Barte!
A Barte oferece uma infraestrutura completa para pagamentos, adquirência e tesouraria.\
Nosso objetivo é simplificar integrações e dar flexibilidade para que você crie soluções financeiras personalizadas.
Com a API da Barte, você pode:
* Processar vendas omnichannel, criar links de pagamento e integrar com e-commerces.
* Gerenciar recebíveis, estornos, disputas e chargebacks.
* Configurar split de pagamentos e administrar parceiros no seu ecossistema.
* Automatizar tesouraria: contas, cartões, pagamentos em lote e investimentos.
A partir daqui, você encontrará **guias de entidades, regras de negócio e fluxos de integração** para colocar a Barte na sua aplicação de forma rápida e segura.
# Métodos de Pagamento
Na Barte, o campo `method` dentro do objeto `payment` define **como a cobrança será processada**. Isso tem impacto direto na **experiência do cliente**, no **repasse para o vendedor** e na **precificação da transação**.
### Visão Geral dos Métodos
Método
Código (payment.method)
Tipo de cobrança
Juros
Quem paga os juros
Exemplo prático
PIX
PIX
Pagamento à vista via QR Code
Não
N/A
Cliente escaneia e paga via QR Code em segundos
Boleto
BANK_SLIP
Pagamento à vista por boleto
Não
N/A
Cliente recebe boleto com vencimento em 3 dias
Crédito à vista/recorrente
CREDIT_CARD
Cartão de crédito (1x ou assinatura)
Não
N/A
Cliente paga R$ 200/mês por uma assinatura
Crédito parcelado com juros para o cliente
CREDIT_CARD_EARLY_BUYER
Cartão de crédito parcelado
Sim (embutido)
Cliente
Compra em 6x de R$ 200, total R$ 1.200
Crédito parcelado sem juros para o cliente
CREDIT_CARD_EARLY_SELLER
Cartão de crédito parcelado
Sim (embutido)
Seller
Cliente vê 6x de R$ 166,66 (sem juros)
***
## Detalhamento e Exemplos
* **CREDIT\_CARD**
* **Uso**: Pagamento **à vista** ou **assinaturas recorrentes**.
* **Fluxo**:
* Cliente insere cartão.
* Barte processa 1x ou cobra automaticamente todo mês (assinatura).
* **Exemplo**:
* Uma escola cobra mensalidade de R$ 500/mês:\
→ `payment.method = "CREDIT_CARD"`\
→ Repetido mensalmente (modelo de assinatura com Gatilhos/Cron scheduler)
***
* **CREDIT\_CARD\_EARLY\_BUYER**
* **Uso**: Parcelamento **com repasse de juros ao comprador**.
* **Fluxo**:
* Cliente escolhe, por exemplo, 6x.
* Valor total da compra **aumenta** por conta dos juros (ex: de R$ 1.000 para R$ 1.200).
* **Exemplo**:
* Loja de eletrônicos vende um monitor:\
→ "6x de R$ 200 com juros"\
→ `payment.method = "CREDIT_CARD_EARLY_BUYER"`
***
* **CREDIT\_CARD\_EARLY\_SELLER**
* **Uso**: Parcelamento **sem juros para o comprador**.
* **Fluxo**:
* Cliente vê "6x sem juros".
* Seller assume o custo dos juros embutidos no parcelamento.
* **Exemplo**:
* Loja de roupas faz promoção de 3x sem juros:\
→ Cliente paga 3x de R$ 100\
→ Barte antecipa o valor e desconta juros do seller\
→ `payment.method = "CREDIT_CARD_EARLY_SELLER"`
***
* PIX
* **Uso**: Pagamento instantâneo.
* **Fluxo**:
* Barte gera um QR Code ou código copia-e-cola.
* Cliente paga via app do banco.
* **Exemplo**:
* Loja online oferece desconto no PIX:\
→ `payment.method = "PIX"`
***
* BANK\_SLIP
* **Uso**: Pagamento à vista via boleto.
* **Fluxo**:
* Geração de um boleto com vencimento customizável.
* Pode demorar até 2 dias úteis para compensação.
* **Exemplo**:
* Escritório de contabilidade manda boleto mensal para clientes:\
→ `payment.method = "BANK_SLIP"`
***
#### :arrows-up-down-left-right: Considerações Técnicas
* A escolha do `payment.method` **impacta o fluxo de liquidação** e **cálculo das taxas**.
* O **tipo de antecipação (early buyer vs early seller)** define **quem absorve o custo do parcelamento**.
# Collections
Para facilitar seus testes e integrações, disponibilizamos coleções pré-configuradas da API da Barte.\
Você pode importar essas coleções nos principais clientes de API:
* **Postman** ⚡
* **Insomnia** 🌙
Essas coleções já incluem:
* Endpoints organizados por recurso
* Exemplos de requisição e resposta
* Headers obrigatórios (incluindo `X-Token-Api`)
* Estrutura pronta para que você apenas configure seu token e comece a testar
### :bolt: Usando no Postman
Você pode **fazer o fork da collection** diretamente no Postman clicando no link abaixo:
:right: [Fork da Collection no Postman](https://www.postman.com/washington-rodrigues/barte-collection/collection/hf15utp/barte-api?action=share\&creator=45328072)
O fork cria uma cópia sincronizada com nossa collection oficial, permitindo que você receba atualizações sempre que houver alterações.
***
### :floppy-disk: Importando via arquivo JSON
Se preferir, você pode **baixar o arquivo `.json`** e importar manualmente:
Baixar Collection
#### :thumbtack: Como importar:
* **No Postman** → `Import > File` e selecione o `.json`.
* **No Insomnia** → `Application → Preferences → Data → Import Data → From File` e selecione o mesmo `.json`.
> :check: O mesmo arquivo funciona para os dois clientes.
***
### :screwdriver-wrench: Dicas
* Todas as requisições exigem o header **X-Token-Api** (veja a seção Como obter o Token de API).
* As collections já vêm com exemplos de `body`, `headers` e parâmetros prontos. Basta substituir pelos dados da sua conta.
* Se optar pelo fork no Postman, mantenha sua collection sincronizada para receber atualizações automaticamente.
# Cartões para testes
Como testar cobranças de cartão em sandbox
Os cartões a serem utilizados no teste, devem ter números válidos e podem ser gerados a partir de qualquer[ site gerador de cartões](https://www.4devs.com.br/gerador_de_numero_cartao_credito), devendo o comportamento seguir as seguinte regra para diferentes validação de diferentes cenários:
| Cartão | Autorizado? | Status | Exemplo |
| --------------- | ----------------- | ------------------ | ------------------- |
| Final 0, 1 ou 4 | SIM | Aprovado | 5186 8825 4989 5601 |
| Final 2 | NÃO | Não autorizado | 5465415736976082 |
| Final 3 | NÃO | Cartão expirado | 5112 9708 0010 5403 |
| Final 5 | NÃO | Cartão bloqueado | 5528430335513025 |
| Final 6 | NÃO | Timeout | 5186882549895601 |
| Final 7 | NÃO | Cartão cancelado | 5325827236673227 |
| Final 8 | Aleatório SIM/NÃO | Aprovado / Timeout | 5397549970735078 |
Em sandbox, para testar os cenários acima, o CVV sempre deve ser um número de 3 dígitos terminado em zero (Ex. 220). Um número de CVV diferente de zero, irá resultar em falha na geração da transaçãoAbaixo está um exemplo do cartão completo válido, para testar a aprovação de uma cobrança:
```
{
"holderName": "JOSE DAS NEVES TEST",
"number": "5383638854440891",
"cvv": 220,
"expiration": "12/2024"
}
```
# Códigos de Erro
O código de retorno é a resposta obtida de uma requisição de transação no Cartão de Crédito nos casos em que a transação não foi aprovada.
Para auxiliar nesse momento, listamos abaixo os códigos de retornos e qual ação tomar quando isso acontecer.
| **Cód de Erro Barte** | **Mensagem de Erro** | **CTA (Call to Action)** |
| --------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| BAR-0436 | Pagamento bloqueado pelo fluxo de segurança | Verifique as informações e tente novamente |
| BAR-7001 | Este cartão não é aceito | Utilize um cartão de crédito ou outro cartão aceito |
| BAR-7002 | Este cartão está expirado | Verifique a data de validade ou utilize outro cartão |
| BAR-7003 | Este cartão foi recusado por fraude confirmada | Entre em contato com seu banco para resolver a fraude |
| BAR-7004 | Este cartão foi recusado por suspeita de fraude | Entre em contato com seu banco para resolver a suspeita |
| BAR-7005 | Erro no Pagamento | Verifique os detalhes da transação e/ou contate a central do seu cartão |
| BAR-7006 | Saldo Insuficiente | Verifique com seu banco emissor se há limite suficiente no cartão. Após, tente novamente |
| BAR-7007 | Valor Inválido | Verifique se o valor da transação está correto, pois está abaixo do mínimo, ou acima do máximo permitido pelo cartão |
| BAR-7008 | CVV Inválido | Verifique seu CVV, e tente novamente |
| BAR-7009 | Dados do Cartão Inválidos | Verifique os dados do seu cartão e tente novamente |
| BAR-7010 | Parcelamento Inválido | Verifique se as parcelas que quer disponibilizar está no seu plano contratado com a Barte |
| BAR-7011 | Erro Pagamento | Verifique os detalhes da transação e/ou contate a central do seu cartão |
| BAR-7012 | Dados do Cartão Inválidos | Verifique os dados do seu cartão e tente novamente |
| BAR-7013 | Dados do Cartão Inválidos | Verifique os dados do seu cartão e tente novamente |
| BAR-7014 | Dados do Cartão Inválidos | Verifique os dados do seu cartão e tente novamente |
| BAR-7015 | Cartão Perdido | O banco acusou que este cartão foi perdido, contate a central do seu cartão. Não tente novamente |
| BAR-7016 | Transação não permitida para o cartão | Verifique com seu banco emissor e tente novamente |
| BAR-7017 | Transação não permitida para o cartão | Verifique com seu banco emissor e tente novamente |
| BAR-7018 | Dados do Cartão Inválidos | Verifique com seu banco emissor e tente novamente |
| BAR-7019 | Cartão Bloqueado | Entre em contato com seu banco, desbloqueie o cartão e tente novamente |
| BAR-7020 | Dados do Cartão Inválidos | Verifique os dados do seu cartão e tente novamente |
| BAR-7021 | Serviço não permitido | Transação não permitida para o cartão. Verifique com seu banco emissor e tente novamente |
| BAR-7022 | Cartão Perdido | O banco acusou que este cartão foi perdido, contate a central do seu cartão. Não tente novamente |
| BAR-7023 | Erro Pagamento | Verifique os detalhes da transação e/ou contate a central do seu cartão |
| BAR-7024 | Tente Novamente | Aconteceu um erro inesperado com o cartão. Tente pagar novamente |
| BAR-7025 | Este cartão está bloqueado | Utilize outro cartão |
| BAR-7026 | Tipo de chave PIX inválido | Corrija a chave PIX e tente novamente |
| BAR-7027 | Cartão Cancelado / E-mail inválido | Realize tentativa com outro cartão ou corrija o e-mail |
| BAR-7028 | Pagamento não confirmado / Documento inválido | Verifique fatura/vendedor ou informe um CPF/CNPJ válido |
| BAR-7029 | O número de telefone deve ser válido | Informe um número de telefone válido |
| BAR-7030 | A chave PIX fornecida já existe | Verifique a chave PIX e tente novamente |
| BAR-7031 | Código de verificação da chave PIX inválido | Forneça um código válido |
| BAR-7032 | Limite de chaves PIX excedido (20) | Remova uma chave existente e tente novamente |
| BAR-7033 | Formato de data inválido | Corrija a data e tente novamente |
| BAR-7034 | O valor não pode ser inferior a R$ 0,00 | Informe um valor válido |
| BAR-7035 | O tipo de pagador deve ser válido | Informe um tipo de pagador válido |
| BAR-7036 | O documento do pagador deve ser CPF ou CNPJ | Informe um CPF ou CNPJ válido |
| BAR-7037 | Nome do pagador inválido | Informe um nome válido |
| BAR-7038 | E-mail do pagador inválido | Informe um e-mail válido |
| BAR-7039 | Número de telefone do pagador inválido | Informe um número de telefone válido |
| BAR-7040 | Chave PIX não encontrada | Verifique a chave PIX e tente novamente |
| BAR-7041 | Não permitido enviar PIX para conta salário | Verifique os dados e tente novamente |
| BAR-7042 | Data inválida | Corrija a data e tente novamente |
| BAR-7043 | Chave já registrada | Aguarde o processo ser finalizado |
| BAR-7044 | Não é possível excluir chaves em processo | Aguarde a finalização do processo |
| BAR-7045 | Status da chave não permite iniciar processo | Verifique o status da chave e tente novamente |
| BAR-7046 | Status da chave não permite cancelar processo | Verifique o status e tente novamente |
| BAR-7047 | Status da chave não permite confirmar processo | Verifique o status e tente novamente |
| BAR-7048 | Já existe um processo de reivindicação em curso | Aguarde a finalização do processo |
| BAR-7049 | Pix devolvido | Verifique os dados e tente novamente |
| BAR-7050 | Falha no envio da transferência | Verifique os dados bancários e tente novamente |
| BAR-7051 | Dados do QRCode duplicados | Verifique os dados e tente novamente |
| BAR-7052 | QRCode finalizado, não pode ser alterado | Crie um novo QRCode e tente novamente |
| BAR-7053 | Formato do documento inválido | Corrija o formato e tente novamente |
| BAR-7054 | Não é permitido criar divisões de valor fixo | Verifique o parâmetro e tente novamente |
| BAR-7055 | Valor das divisões excede o valor do QRCode | Ajuste o valor das divisões e tente novamente |
| BAR-7056 | Valor do QRCode inválido | Informe um valor válido e tente novamente |
| BAR-7057 | Conflito entre campos de retirada e alteração | Verifique os campos e tente novamente |
| BAR-7058 | Descrição com caracteres inválidos | Corrija os caracteres e tente novamente |
| BAR-7059 | Status da chave não permite remoção | Verifique o status e tente novamente |
| BAR-7060 | ID end2end expirado | Utilize um ID válido e tente novamente |
| BAR-7061 | ID end2end duplicado | Verifique o ID e tente novamente |
| BAR-7062 | Pix bloqueado para reembolso | Aguarde a finalização do MED e tente novamente |
| BAR-7063 | Formato de chave PIX inválido | Corrija o formato da chave e tente novamente |
| BAR-7064 | Limite de chaves PIX atingido | Remova uma chave existente e tente novamente |
| BAR-7065 | Tipo de chave PIX não permitido para esta conta | Verifique o tipo de chave e tente novamente |
| BAR-7066 | Chave PIX divergente do CPF/CNPJ | Verifique os dados e tente novamente |
| BAR-7067 | Limite de consultas no DICT excedido | Aguarde e tente novamente |
A seguir, um exemplo de um erro retornado na API:
{
"errors": [{
"status": "400",
"code": "BAR-7005",
"title": "generic",
"description": "Erro no pagamentoo",
"action": "Verifique os detalhes da transação e/ou contate a central do seu cartão",
"additionalInfo": {
"chargeUUID": "8ef3900d-e7d2-45e0-8530-830f5657c9e4",
"provider": "Barte"
}
}],
"metadata": {
"totalRecords": 1,
"totalPages": 1,
"requestDatetime": "2024-08-09T16:28:53.265693613-03:00[America/Sao_Paulo]"
}
}
# 1º - Preparação
# Obtendo o Token de API
Todos os endpoints da Barte exigem autenticação via **`X-Token-Api`**.\
Esse token é a credencial necessária para que sua aplicação consiga se comunicar com a API de forma segura.
### Passo a passo
1. Acesse o **Painel do Vendedor**.
2. Vá até **Configurações > Integração**.
3. Clique em **Gerar nova chave**.
4. Copie o valor gerado e utilize-o no header `X-Token-Api` das suas requisições.
⚠️ **Atenção:** o token é sensível e deve ser armazenado de forma segura. Evite expô-lo em clientes públicos (como apps front-end).
### Veja como obter o token:
{% embed url="" %}
Lembrando que:\
Caso o passo a passo apresente erro ou não consiga efetuar a ação, entre em contato com o time de Suporte Barte.
{% endembed %}
# Configurando Webhooks
Acessando o Dashboard do AppBarte, no menu lateral esquerdo, clique em "Configurações" e o submenu em "Integração"
#### O que são Webhooks?
Webhooks são **notificações automáticas** enviadas pela Barte para o seu sistema sempre que ocorre **uma alteração de status em uma transação ou evento importante**.
Em vez de consultar a API repetidamente para saber se algo mudou, a Barte envia uma requisição HTTP para a URL configurada, informando o evento ocorrido e seus dados.
***
#### Quando a Barte dispara webhooks?
Atualmente, a Barte dispara webhooks para os seguintes tipos de eventos:
* **Pedidos (Orders) e Assinaturas (Subscriptions)**\
Ex: pagamento confirmado, pendente, cancelado ou expirado.
* **Pedidos Físicos (Maquininhas)**\
Ex: atualização do status da transação realizada na maquininha.
* **Disputas e Chargebacks**\
Ex: abertura, atualização ou encerramento de uma disputa.
Os webhooks são enviados **sempre que uma transação sofre alteração de status**, permitindo que seu sistema reaja automaticamente a cada mudança.
***
#### Por que usar webhooks?
* Atualizar pedidos automaticamente no seu sistema
* Confirmar pagamentos de PIX e boleto
* Liberar produtos ou serviços após pagamento
* Tratar cancelamentos, estornos, disputas e chargebacks
#### Fluxo Visual
#### Como cadastrar um Webhook
* Na tela apresentada, clique no botão "Novo Webhook" no canto superior direito. O modal de criação exibirá os campos necessários:
* **URL:** endereço de destino para receber as notificações.
* **Versão:** selecione **v1** (legado) ou **v2** (novo padrão).
* Após preencher os campos, clique em "Salvar".
* Para editar um webhook existente, clique no ícone de edição — a versão salva será exibida e poderá ser alterada.
* Abaixo do cadastro do webhook estarão disponíveis as opções de ativar ou desativar o webhook ou excluí-lo pelo ícone de lixo.
{% embed url="" %}
Lembrando que:\
Caso o passo a passo apresente erro ou não consiga efetuar a ação, entre em contato com o time de Suporte Barte.
{% endembed %}
# 2º - Criando Pedidos | Links de Pagamento | Assinaturas
Nesta etapa você aprende a **criar cobranças na Barte**, escolhendo o modelo mais adequado para o seu negócio.
A Barte oferece três formas principais de cobrança:
* **Pedidos** → cobranças criadas via API, ideais para integrações diretas e fluxos customizados
* **Links de Pagamento** → cobranças compartilháveis, sem necessidade de checkout próprio
* **Assinaturas** → cobranças recorrentes baseadas em planos
Cada uma atende a um cenário diferente de venda, mas todas seguem os mesmos princípios:
* possuem identificadores únicos (`uuid`)
* geram cobranças (`charges`)
* têm seus status atualizados ao longo do tempo
* disparam **webhooks** sempre que há mudança de estado
***
### O que você vai encontrar nesta seção
#### :diamond: Pedidos
Criação de cobranças via API para pagamentos pontuais, com suporte a PIX, boleto, cartão de crédito, pré-captura, tokenização e 3DS.
Acessar [Pedidos](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos)
***
#### :diamond: Links de Pagamento
Geração de links prontos para pagamento, ideais para cobranças manuais, envio por WhatsApp, e-mail ou redes sociais.
Acessar [Links de Pagamento](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/links-de-pagamento)
***
#### :diamond: Assinaturas
Configuração de planos e criação de cobranças recorrentes automáticas, com controle de ciclo, valores e status.
Acessar [Assinaturas](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/assinaturas)
# Pedidos
Pedidos representam a **criação de cobranças** na Barte.\
É a partir de um pedido que os pagamentos são iniciados, processados e acompanhados — independentemente do método utilizado.
Cada pedido possui um **fluxo específico**, de acordo com o tipo de pagamento, nível de segurança e estratégia de cobrança do vendedor.
Escolha abaixo o cenário mais adequado para o seu caso de uso.
***
### Tipos de pedidos disponíveis
#### :diamond: Pedido simples (PIX, Boleto e Cartão de Crédito)
Criação direta de pedidos para pagamentos pontuais, com retorno síncrono ou assíncrono dependendo do método.
**Ver guia:** [Pedido simples (PIX, Boleto e Cartão de Crédito)](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-simples-pix-boleto-e-cartao-de-credito)
***
#### :diamond: Pedido com Pré-captura
Autoriza o pagamento no cartão, mas permite capturá-lo apenas no momento desejado.
**Ver guia:** [Pedido com Pré-captura](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-com-pre-captura)
***
#### :diamond: Pedido com Cartão Tokenizado
Utiliza cartões previamente tokenizados, aumentando a segurança e reduzindo o escopo de compliance.
**Ver guia:** [Pedido com Cartão Tokenizado](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-com-cartao-tokenizado)
***
#### :diamond: Pedido com 3DS (3D Secure)
Fluxo com autenticação adicional do portador do cartão, indicado para cenários de maior risco.
**Ver guia:** [Pedido com 3DS (3D Secure)](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-com-3ds-3d-secure)
# Pedido simples (PIX, Boleto e Cartão de Crédito)
Este guia descreve o passo a passo para um vendedor criar um pedido (order) utilizando a API da Barte.
***
### Criar um pedido (Order)
#### Endpoint
```
POST /v2/orders
https://api.barte.com/v2/orders
```
#### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
#### Body
Você pode ver mais detalhes sobre os métodos de pagamento aqui → [Métodos de Pagamento](/guias/inicio/metodos-de-pagamento)
{% tabs %}
{% tab title="Cartão de Crédito" %}
```json
{
"startDate": "2026-01-30",
"value": 100,
"installments": 1,
"title": "Compra de produto",
"description": "Descrição da compra",
"payment": {
"method": "CREDIT_CARD_EARLY_SELLER",
"capture": true,
"softDescriptor": "Testando Criação de Order",
"card": {
"holderName": "JOSE DAS NEVES TEST",
"number": "5560738292679681",
"expiration": "10/2026",
"cvv": "290"
},
"fraudData": {
"document": "48637879012",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111",
"billingAddress": {
"country": "BR",
"state": "Minas Gerais",
"city": "Uberlândia",
"district": "Jardim Europa",
"street": "Rua Orleans",
"zipCode": "38414552",
"number": "100",
"complement": "Bloco A"
}
}
},
"uuidBuyer": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c",
"metadata": [
{
"key": "código",
"value": "YMC"
}
]
}
```
{% endtab %}
{% tab title="PIX" %}
```json
{
"startDate": "2026-01-30",
"value": 100,
"installments": 1,
"title": "Compra de produto",
"description": "Descrição da compra",
"payment": {
"method": "PIX"
},
"uuidBuyer": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c",
"metadata": [
{
"key": "código",
"value": "YMC"
}
]
}
```
{% endtab %}
{% tab title="Boleto" %}
```json
{
"startDate": "2026-01-30",
"value": 100,
"installments": 1,
"title": "Compra de produto",
"description": "Descrição da compra",
"payment": {
"method": "BANK_SLIP",
},
"uuidBuyer": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c",
"metadata": [
{
"key": "código",
"value": "YMC"
}
]
}
```
{% endtab %}
{% endtabs %}
#### Response
{% tabs %}
{% tab title="Cartão de Crédito" %}
```json
{
"uuid": "ec12eec2-1a08-486f-bd43-971541f1cf2a",
"status": "PAID",
"title": "Compra de produto",
"description": "Descrição da compra",
"value": 100.00,
"installments": 1,
"startDate": "2026-01-30",
"payment": "CREDIT_CARD_EARLY_SELLER",
"customer": {
"document": "48637879012",
"type": "CPF",
"documentCountry": "BR",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111"
},
"idempotencyKey": "f2a57017-3aa4-42aa-a118-a594c69dbd77",
"subSellerPaymentResponse": [
{
"subSellerPaymentResponse": [],
"amountForSubSellers": 0
}
],
"charges": [
{
"uuid": "aa97d29b-a20f-41dd-8575-fd66a08666ec",
"title": "Compra de produto",
"expirationDate": "2026-01-30",
"value": 100.00,
"paymentMethod": "CREDIT_CARD_EARLY_SELLER",
"status": "PAID",
"customer": {
"document": "48637879012",
"type": "CPF",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111"
},
"authorizationCode": "558520",
"authorizationNsu": "169556",
"acquirerAuthorizationCode": "null",
"acquirerAuthorizationNsu": "169556"
}
]
}
```
{% endtab %}
{% tab title="PIX" %}
```json
{
"uuid": "ec12eec2-1a08-486f-bd43-971541f1cf2a",
"status": "SENT",
"title": "Compra de produto",
"description": "Descrição da compra",
"value": 100.00,
"installments": 1,
"startDate": "2026-01-30",
"payment": "PIX",
"customer": {
"document": "48637879012",
"type": "CPF",
"documentCountry": "BR",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111"
},
"idempotencyKey": "f2a57017-3aa4-42aa-a118-a594c69dbd77",
"subSellerPaymentResponse": [
{
"subSellerPaymentResponse": [],
"amountForSubSellers": 0
}
],
"charges": [
{
"uuid": "aa97d29b-a20f-41dd-8575-fd66a08666ec",
"title": "Compra de produto",
"expirationDate": "2026-01-30",
"value": 100.00,
"paymentMethod": "PIX",
"status": "SCHEDULED",
"customer": {
"document": "48637879012",
"type": "CPF",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111"
},
"pixCode": "00020101021126650014BR.GOV.BCB.PIX01000239BENEFICIARIO FINAL: Nome do Vendedor 52040000530398654041.005802BR5911Buyer Name 600062360532244639c3f18747ac96fa0757abb9a1ef6304B607",
"pixQRCodeImage": "https://s3.amazonaws.com/sandbox-charge-docs.barte.corp/pix/4d56b466-3c09-45ec-8282-a5a949cbf854.png",
"authorizationCode": "558520",
"authorizationNsu": "169556",
"acquirerAuthorizationCode": "null",
"acquirerAuthorizationNsu": "169556"
}
]
}
```
{% endtab %}
{% tab title="Boleto" %}
```json
{
"uuid": "ec12eec2-1a08-486f-bd43-971541f1cf2a",
"status": "SENT",
"title": "Compra de produto",
"description": "Descrição da compra",
"value": 100.00,
"installments": 1,
"startDate": "2026-01-30",
"payment": "BANK_SLIP",
"customer": {
"document": "48637879012",
"type": "CPF",
"documentCountry": "BR",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111"
},
"idempotencyKey": "f2a57017-3aa4-42aa-a118-a594c69dbd77",
"subSellerPaymentResponse": [
{
"subSellerPaymentResponse": [],
"amountForSubSellers": 0
}
],
"charges": [
{
"uuid": "aa97d29b-a20f-41dd-8575-fd66a08666ec",
"title": "Compra de produto",
"expirationDate": "2026-01-30",
"value": 100.00,
"paymentMethod": "BANK_SLIP",
"status": "SCHEDULED",
"customer": {
"document": "48637879012",
"type": "CPF",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111"
},
"bankSlipBarcode": "1111 2222 3333 4444",
"bankSlip": "https://s3.amazonaws.com/sandbox-charge-docs.barte.corp/bank-slip/1fe5fbe4-efc0-4dc3-86f3-d29b45545e53",
"authorizationCode": "558520",
"authorizationNsu": "169556",
"acquirerAuthorizationCode": "null",
"acquirerAuthorizationNsu": "169556"
}
]
}
```
{% endtab %}
{% endtabs %}
> 📌 O **uuid da charge** será necessário para ações como estorno.
Veja a referencia API do endpoint de criação de orders clicando no link abaixo para entender sobre todos os campos, métodos de pagamento, retornos de sucesso e erro e demais informações:
#### Campos mais importantes da resposta
* `uuid` - Identificador único do pedido (Order). Este campo deve ser salvo para:
* Consultas futuras do pedido
* Validação de notificações recebidas via webhook
* Conciliação financeira
* Rastreabilidade da transação no seu sistema
* `status` - Status atual do pedido, exemplo:
* `PAID` → pagamento confirmado
* `SENT` → cobrança criada e aguardando pagamento
* `CANCELED` → pedido cancelado
* `FAILED` → falha no pagamento
⚠️ **Nunca utilize apenas este campo como confirmação final sem validar via webhook.**
* `charges[].uuid` - Identificador único da cobrança gerada dentro do pedido. Este campo é obrigatório para:
* Solicitação de estorno
* Consultas específicas da cobrança
* Auditoria e conciliação
📌 **O uuid da charge é diferente do uuid do pedido. Ambos devem ser armazenados.**
Você pode ver mais detalhes na referência completa da API clicando no link abaixo:
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/DqJnW4qScozbkkcrkZGm" %}
[Criar Pedido](/api-reference/pedidos-e-cobrancas/criar-pedido)
{% endcontent-ref %}
***
### :bell: Confirmação do pagamento
Após a criação de um pedido:
#### Cartão de crédito
* A API pode retornar o pedido como `PAID` de forma síncrona
* **Mesmo assim**, um webhook será disparado confirmando o evento
* Utilize o webhook como **fonte de verdade**
#### PIX e Boleto
* O pedido será criado com status `SENT`
* A cobrança ficará como `SCHEDULED`
* Após o pagamento:
* O status do pedido é atualizado
* Um webhook é disparado para o seu sistema
👉 **Sempre confirme o pagamento exclusivamente via webhook.**
***
### :rotate: Fluxo resumido
1. Você cria o pedido via API
2. A Barte processa a cobrança
3. O cliente realiza o pagamento
4. O status da transação é atualizado
5. Um webhook é enviado ao seu sistema
6. Seu sistema valida o evento e confirma o pagamento
***
### :lightbulb: Boas práticas
* Sempre armazene:
* `uuid` do pedido
* `uuid` da charge
* Utilize o webhook como fonte única de confirmação de pagamento
* Trate o webhook de forma idempotente
* Valide o status antes de liberar produtos ou serviços
* Utilize `expirationDate` para PIX e boleto
* Use `metadata` para rastrear pedidos internos (ex: IDs do seu sistema)
***
### :hexagon-xmark: O que não fazer
* Confirmar pagamento apenas pela resposta síncrona da API
* Ignorar webhooks de atualização de status
* Reutilizar pedidos para novas cobranças
* Expor sua chave de API no frontend
# Pedido com Pré-captura
Este guia descreve o passo a passo para um vendedor criar um pedido (order) com pré-captura utilizando a API da Barte, desde a autenticação até possíveis ações após o pagamento.
***
### 1. Criar um pedido (Order)
No payload da requisição, dentro do objeto payment, temos a propriedade "`capture`", que é um boolean (true or false).
capture = true → captura direta: [Pedido simples (PIX, Boleto e Cartão de Crédito)](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-simples-pix-boleto-e-cartao-de-credito)
capture = false → pré-captura
Além disso, a pré-captura possui algumas regras que podem ser validadas em [Como funciona a Pré-Captura](/guias/pedidos-e-cobrancas/como-funciona-a-pre-captura)
#### Endpoint
```
POST /v2/orders
https://api.barte.com/v2/orders
```
#### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
#### Body
```json
{
"startDate": "2026-01-30",
"value": 100,
"installments": 1,
"title": "Compra de produto",
"description": "Descrição da compra",
"payment": {
"method": "CREDIT_CARD_EARLY_SELLER",
"capture": false, ← Aqui está o parâmetro que fine se é uma pré-captura ou não
"softDescriptor": "Testando Criação de Order",
"card": {
"holderName": "JOSE DAS NEVES TEST",
"number": "5560738292679681",
"expiration": "10/2026",
"cvv": "290"
},
"fraudData": {
"document": "48637879012",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111",
"billingAddress": {
"country": "BR",
"state": "Minas Gerais",
"city": "Uberlândia",
"district": "Jardim Europa",
"street": "Rua Orleans",
"zipCode": "38414552",
"number": "100",
"complement": "Bloco A"
}
}
},
"uuidBuyer": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c",
"metadata": [
{
"key": "código",
"value": "YMC"
}
]
}
```
#### Response
```json
{
"uuid": "ec12eec2-1a08-486f-bd43-971541f1cf2a",
"status": "PRE_AUTHORIZED",
"title": "Compra de produto",
"description": "Descrição da compra",
"value": 100.00,
"installments": 1,
"startDate": "2026-01-30",
"payment": "CREDIT_CARD_EARLY_SELLER",
"customer": {
"document": "48637879012",
"type": "CPF",
"documentCountry": "BR",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111"
},
"idempotencyKey": "f2a57017-3aa4-42aa-a118-a594c69dbd77",
"subSellerPaymentResponse": [
{
"subSellerPaymentResponse": [],
"amountForSubSellers": 0
}
],
"charges": [
{
"uuid": "aa97d29b-a20f-41dd-8575-fd66a08666ec",
"title": "Compra de produto",
"expirationDate": "2026-01-30",
"value": 100.00,
"paymentMethod": "CREDIT_CARD_EARLY_SELLER",
"status": "PRE_AUTHORIZED",
"customer": {
"document": "48637879012",
"type": "CPF",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111"
},
"authorizationCode": "558520",
"authorizationNsu": "169556",
"acquirerAuthorizationCode": "null",
"acquirerAuthorizationNsu": "169556"
}
]
}
```
> 📌 O **uuid da charge** será necessário para ações como estorno.
Veja a referencia API do endpoint de criação de orders clicando no link abaixo para entender sobre todos os campos, métodos de pagamento, retornos de sucesso e erro e demais informações:
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/DqJnW4qScozbkkcrkZGm" %}
[Criar Pedido](/api-reference/pedidos-e-cobrancas/criar-pedido)
{% endcontent-ref %}
***
### 2. Capturar cobrança (Charge)
Quando um pedido (order) é criado, a API retorna um **array de charges**.\
A **captura do pagamento é feita utilizando o `uuid` da charge**, e **não** o `uuid` da order.
> ⚠️ **Importante:**\
> Se a cobrança não for capturada em até 6 dias, ela será cancelada automaticamente. Veja mais detalhes em [Como funciona a Pré-Captura](/guias/pedidos-e-cobrancas/como-funciona-a-pre-captura)
#### Endpoint
```
POST /v2/charges/{uuid}/capture
https://api.barte.com/v2/charges/{uuid}/capture
```
> `{uuid}` deve ser substituído pelo **uuid da charge** retornada na criação da order.
***
#### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
***
#### Body
Este endpoint **não requer body**.
***
#### Response
```json
{
"uuid": "3e40ddbe-6ef7-4cdb-ab22-6a54bc405abd",
"title": "Fatura mensal do cliente",
"expirationDate": "2025-09-18",
"paidDate": "2025-09-18",
"value": 1000,
"paymentMethod": "CREDIT_CARD_EARLY_SELLER",
"status": "PAID",
"customer": {
"uuid": "",
"document": "39600937000133",
"type": "CNPJ",
"name": "Daniel e Manoel Pães e Doces Ltda",
"email": "treinamento@danielemanoelpaesedocesltda.com.br",
"phone": "15982705981"
},
"authorizationCode": null,
"authorizationNsu": "296",
"retryable": false
}
```
Veja a referência api completa de como capturar uma cobrança clicando no link abaixo:
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/Gn6D3jr3kkg2sf7iFDkI" %}
[Capturar Cobrança](/api-reference/pedidos-e-cobrancas/cobrancas/capturar-cobranca)
{% endcontent-ref %}
***
#### Observações importantes
* A captura **sempre acontece no nível da charge**
* Uma order pode possuir **uma ou mais charges**
* Após a captura bem-sucedida, o status da charge passa para `PAID`
* O `uuid` retornado permanece o mesmo da charge capturada
***
### 3. Cancelar pré-captura
O cancelamento de pré-captura deve ser utilizado **somente quando a cobrança ainda não foi capturada**, ou seja, quando a charge está com status **`PRE_AUTHORIZED`**.
> ⚠️ **Importante:**\
> Se a cobrança **já tiver sido capturada**, este endpoint **não deve ser utilizado**.\
> Nesse caso, o fluxo correto é realizar um **estorno (refund)**.
***
#### Quando usar
* A charge foi criada com `capture: false`
* O pagamento foi **apenas pré-autorizado**
* O status da charge é `PRE_AUTHORIZED`
* O vendedor decidiu **não capturar** o valor
***
#### Endpoint
```
PATCH /v2/charges/{uuid}/cancel/pre-authorization
https://api.barte.com/v2/charges/{uuid}/cancel/pre-authorization
```
> `{uuid}` deve ser o **uuid da charge** retornada na criação da order.
***
#### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
***
#### Body
Este endpoint **não requer body**.
***
#### Response
A resposta retorna um status 204 No content, indicando sucesso na operação.
***
Veja a referência completa de como cancelar uma pré-captura clicando no link abaixo:
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/XYvDAkCCkzitudDqxWNa" %}
[Cancelar Pré-Captura](/api-reference/pedidos-e-cobrancas/cobrancas/cancelar-pre-captura)
{% endcontent-ref %}
#### Observações importantes
* O cancelamento **só é permitido** se o status da charge for `PRE_AUTHORIZED`
* Após o cancelamento, o valor **não será capturado**
* Se a charge estiver com status `PAID`, o fluxo correto é **estorno total ou parcial**
* O cancelamento de pré-captura **não gera estorno**, pois o valor ainda não foi efetivamente debitado
# Pedido com Cartão Tokenizado
Este guia descreve o passo a passo para um vendedor criar um pedido (order) com cartão tokenizado utilizando a API da Barte, desde a autenticação até possíveis ações após o pagamento.
***
### 1. Criar Card Token (Tokenização de Cartão)
A tokenização permite armazenar um cartão de forma segura e reutilizá-lo em cobranças futuras, sem a necessidade de reenviar os dados sensíveis do cartão.
Após a geração do token, o cartão pode ser utilizado na criação de pedidos (orders).
***
#### Endpoint
```
POST /payment/v1/cards
https://api.barte.com/payment/v1/cards
```
***
#### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
***
#### Body
```json
{
"holderName": "JOSE DAS NEVES TEST",
"number": "5383638854440891",
"cvv": "220",
"expiration": "12/2025",
"checkZeroDollar": false,
"buyerUuid": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c"
}
```
**Campos importantes**
* **buyerUuid**: UUID do comprador previamente criado
* **checkZeroDollar**:
* `true`: realiza uma validação do cartão sem cobrança
* `false`: não realiza a validação zero-dólar
***
#### Response
```json
{
"uuid": "80efb136-e65e-4fa3-b76a-6ee5a1953c4c",
"status": "ACTIVE",
"createdAt": "2025-08-21",
"brand": "mastercard",
"cardHolderName": "JOSE DAS NEVES TEST",
"cvvChecked": true,
"fingerprint": "d1Epx4VTTGp1KdCtVvcGK0oPA//ZR6jMlEcrdVjbt28=",
"first6digits": "518688",
"last4digits": "5601",
"buyerId": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c",
"expirationMonth": "10",
"expirationYear": "2025",
"cardId": "83d353d2-716f-45cf-837f-50c18f10efa0"
}
```
***
#### ⚠️ Atenção — Qual campo usar na criação da transação
Na criação do pedido (order), o **cardToken** que deve ser enviado é:
👉 **`uuid` retornado neste endpoint**
❌ **Não utilizar** o campo `cardId` para criação de transações.
Exemplo conceitual:
```
cardToken = response.uuid
```
***
#### Observações importantes
* O token retornado representa o cartão de forma segura
* O status `ACTIVE` indica que o cartão está pronto para uso
* O token pode ser reutilizado em múltiplas cobranças
* Os dados sensíveis do cartão **não devem** ser armazenados pelo vendedor
* Caso o `checkZeroDollar` não seja realizado, a tokenização será criada com status **`PENDING`** e será automaticamente atualizada para **`ACTIVE`** após a primeira transação bem-sucedida.
***
### 2. Criar um pedido (Order)
Com o comprador e token de cartão criados, a próxima etapa é a criação do pedido.
No payload da requisição, dentro do objeto payment, a propriedade `card` terá apenas `cardToken` e `cvv`.
> ⚠️ **Importante:**\
> Também é possível criar a transação com cardToken em formato de pré-captura. Para isso, basta seguir todo o processo acima até a tokenização do cartão e, após isso, seguir o processo de pré-captura em [Pedido com Pré-captura](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-com-pre-captura). A única diferença é que o objeto card terá cardToken e cvv, apenas.
#### Endpoint
```
POST /v2/orders
https://api.barte.com/v2/orders
```
#### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
#### Body
```json
{
"startDate": "2026-01-30",
"value": 100,
"installments": 1,
"title": "Compra de produto",
"description": "Descrição da compra",
"payment": {
"method": "CREDIT_CARD_EARLY_SELLER",
"capture": true,
"softDescriptor": "Soft Descriptor 123456",
"card": {
"cardToken": "80efb136-e65e-4fa3-b76a-6ee5a1953c4c",
"cvv": "220"
},
"fraudData": {
"document": "48637879012",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111",
"billingAddress": {
"country": "BR",
"state": "Minas Gerais",
"city": "Uberlândia",
"district": "Jardim Europa",
"street": "Rua Orleans",
"zipCode": "38414552",
"number": "100",
"complement": "Bloco A"
}
}
},
"uuidBuyer": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c",
"metadata": [
{
"key": "código",
"value": "YMC"
}
]
}
```
#### Response
```json
{
"uuid": "ec12eec2-1a08-486f-bd43-971541f1cf2a",
"status": "PAID",
"title": "Compra de produto",
"description": "Descrição da compra",
"value": 100.00,
"installments": 1,
"startDate": "2026-01-30",
"payment": "CREDIT_CARD_EARLY_SELLER",
"customer": {
"document": "48637879012",
"type": "CPF",
"documentCountry": "BR",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111"
},
"idempotencyKey": "f2a57017-3aa4-42aa-a118-a594c69dbd77",
"subSellerPaymentResponse": [
{
"subSellerPaymentResponse": [],
"amountForSubSellers": 0
}
],
"charges": [
{
"uuid": "aa97d29b-a20f-41dd-8575-fd66a08666ec",
"title": "Compra de produto",
"expirationDate": "2026-01-30",
"value": 100.00,
"paymentMethod": "CREDIT_CARD_EARLY_SELLER",
"status": "PAID",
"customer": {
"document": "48637879012",
"type": "CPF",
"name": "John Doe",
"email": "johndoe@barte.com",
"phone": "34999991111"
},
"authorizationCode": "558520",
"authorizationNsu": "169556",
"acquirerAuthorizationCode": "null",
"acquirerAuthorizationNsu": "169556"
}
]
}
```
> 📌 O **uuid da charge** será necessário para ações como estorno.
#### Campos mais importantes da resposta
* `uuid` - Identificador único do pedido (Order). Este campo deve ser salvo para:
* Consultas futuras do pedido
* Validação de notificações recebidas via webhook
* Conciliação financeira
* Rastreabilidade da transação no seu sistema
* `status` - Status atual do pedido, exemplo:
* `PAID` → pagamento confirmado
* `SENT` → cobrança criada e aguardando pagamento
* `CANCELED` → pedido cancelado
* `FAILED` → falha no pagamento
⚠️ **Nunca utilize apenas este campo como confirmação final sem validar via webhook.**
* `charges[].uuid` - Identificador único da cobrança gerada dentro do pedido. Este campo é obrigatório para:
* Solicitação de estorno
* Consultas específicas da cobrança
* Auditoria e conciliação
📌 **O uuid da charge é diferente do uuid do pedido. Ambos devem ser armazenados.**
Você pode ver mais detalhes na referência completa da API clicando no link abaixo:
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/w2fKS55UNUncwDE15dqV" %}
[Criar Pedido com Token do Cartão](/api-reference/tokenizacao-de-cartao-one-buy-click/criar-pedido-com-token-do-cartao)
{% endcontent-ref %}
***
### :bell: Confirmação do pagamento
Após a criação de um pedido:
* A API pode retornar o pedido como `PAID` de forma síncrona
* **Mesmo assim**, um webhook será disparado confirmando o evento
* Utilize o webhook como **fonte de verdade**
***
### :rotate: Fluxo resumido
1. Você cria o pedido via API
2. A Barte processa a cobrança
3. O cliente realiza o pagamento
4. O status da transação é atualizado
5. Um webhook é enviado ao seu sistema
6. Seu sistema valida o evento e confirma o pagamento
***
### :lightbulb: Boas práticas
* Sempre armazene:
* `uuid` do pedido
* `uuid` da charge
* Utilize o webhook como fonte de confirmação de pagamento
* Trate o webhook de forma idempotente
* Valide o status antes de liberar produtos ou serviços
* Use `metadata` para rastrear pedidos internos (ex: IDs do seu sistema)
***
### :hexagon-xmark: O que não fazer
* Confirmar pagamento apenas pela resposta síncrona da API
* Ignorar webhooks de atualização de status
* Reutilizar pedidos para novas cobranças
* Expor sua chave de API no frontend
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/DqJnW4qScozbkkcrkZGm" %}
[Criar Pedido](/api-reference/pedidos-e-cobrancas/criar-pedido)
{% endcontent-ref %}
# Pedido com 3DS (3D Secure)
Este guia descreve o fluxo completo para criação de pedidos utilizando 3D Secure (3DS), incluindo a criação da sessão, coleta de dados do navegador e, quando necessário, o desafio de autenticação (Ste
***
### 1. Criar Card Token (Tokenização de Cartão)
A tokenização permite armazenar o cartão de forma segura para uso posterior.
#### Endpoint
```
POST /payment/v1/cards
https://api.barte.com/payment/v1/cards
```
#### Body
```json
{
"holderName": "JOSE DAS NEVES TEST",
"number": "5383638854440891",
"cvv": "220",
"expiration": "12/2025",
"checkZeroDollar": true,
"buyerUuid": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c"
}
```
#### Response
```json
{
"uuid": "80efb136-e65e-4fa3-b76a-6ee5a1953c4c",
"status": "ACTIVE",
"cardId": "83d353d2-716f-45cf-837f-50c18f10efa0"
}
```
⚠️ **Importante**
* O **cardToken** utilizado na transação é o campo **uuid**
* O campo **cardId** será utilizado **apenas na criação da sessão 3DS**
* Caso `checkZeroDollar` seja `false`, o token pode iniciar com status `PENDING` e será atualizado para `ACTIVE` após a primeira transação bem-sucedida
***
### 2. Criar sessão 3DS
A sessão 3DS é necessária para iniciar o processo de autenticação.
#### Endpoint
```
POST /v1/3ds/session
https://api.barte.com/v1/3ds/session
```
#### Body
```json
{
"sourceType": "card",
"cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```
#### Response
```json
{
"id": "701d8f14-9b5f-40b0-8013-422e0020c522",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"collectUrl": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",
"providerType": "CYBERSOURCE"
}
```
📌 Guarde:
* **id** → será enviado como `setupId` na criação do pedido
* **token** e **collectUrl** → usados na coleta de dados do navegador
***
### 3. Coletar dados do navegador (Browser Data Collection)
Antes de criar o pedido, é obrigatório coletar os dados do navegador do cliente.
#### Objetivo
Enviar informações de background do navegador para o provedor 3DS.
#### Script de coleta
```html
```
⚠️ Observações importantes:
* O iframe apresenta o desafio do banco emissor
* Ao finalizar, o cliente é redirecionado para o `redirectURL`
* O **status final da transação** será enviado via **webhook**
***
### Resumo de decisão
* `challenged = false` → pagamento segue normalmente (PAID / FAILED)
* `challenged = true` → exige Step Up Challenge
* Resultado final sempre confirmado via webhook
### 🔔 Confirmação do pagamento
Após o cliente realizar o pagamento:
1. O status da transação é atualizado na Barte
2. Um webhook é disparado para o seu sistema
3. Seu sistema deve validar o evento recebido
4. A confirmação do pagamento deve ser feita **exclusivamente via webhook**
📌 Isso se aplica a **cartão, PIX e boleto**, inclusive quando o cartão retorna `PAID` de forma síncrona.
***
### :rotate: Fluxo resumido
```
Criar pedido
↓
Cliente realiza pagamento
↓
Status atualizado na Barte
↓
Webhook enviado
↓
Seu sistema confirma o pagamento
```
***
#### Campos importantes no 3DS
**`threeDSecure.setupId`**
ID da sessão 3DS criada previamente.
**`threeDSResponse.challenged`**
* `true` → exige desafio (Step Up)
* `false` → fluxo segue normalmente
**`threeDSResponse.auth.action`**
* `REDIRECT` → redirecionamento para autenticação
📌 **O resultado final do 3DS nunca deve ser inferido no frontend.**
***
### :thumbtack-angle: Importante sobre 3DS
* O cliente pode ser autenticado com sucesso **e ainda assim** o pagamento falhar
* O redirecionamento não confirma o pagamento
* **Somente o webhook indica o estado final da transação**
***
### :lightbulb: Boas práticas
* Sempre utilize webhooks para confirmar pagamento
* Armazene:
* `uuid` do pedido
* `uuid` da charge
* Trate webhooks de forma idempotente
* Use `metadata` para rastreabilidade interna
* Aguarde a finalização da coleta de navegador no 3DS
***
### :hexagon-xmark: O que não fazer
* Confirmar pagamento sem webhook
* Reutilizar pedidos para novas cobranças
* Assumir sucesso após retorno síncrono do cartão
* Criar pedido 3DS antes da coleta de navegador
* Expor sua chave de API no frontend
# Links de Pagamento
Links de pagamento permitem criar **cobranças prontas para uso**, sem a necessidade de um checkout próprio ou integração complexa.
Ao gerar um link, a Barte se encarrega da experiência de pagamento, enquanto você acompanha o status da cobrança via API e webhooks.
Eles são ideais para:
* vendas manuais
* cobranças via WhatsApp, e-mail ou redes sociais
* operações sem frontend próprio
* testes rápidos de cobrança
***
### Tipos de links de pagamento
#### :diamond: Link de Pagamento Pontual
Indicado para **cobranças únicas**, com valor e vencimento definidos.
Acessar [Link de Pagamento Pontual](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/links-de-pagamento/link-de-pagamento-pontual)
***
#### :diamond: Link de Pagamento Recorrente
Utilizado para **cobranças recorrentes**, geralmente associado a um plano de assinatura.
Acessar [Link de Pagamento Recorrente](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/links-de-pagamento/link-de-pagamento-recorrente)
# Link de Pagamento Pontual
O **Link de Pagamento Pontual** permite criar uma **cobrança única** através de um checkout hospedado pela Barte.\
Ao acessar o link, o cliente pode realizar o pagamento utilizando os métodos configurados, sem a necessidade de integração direta com checkout.
Esse tipo de link é indicado para **vendas avulsas**, cobranças manuais e pagamentos enviados por canais externos.
***
### :thumbtack-angle: Quando usar Link de Pagamento Pontual?
Utilize esse recurso quando:
* A cobrança for **pontual (não recorrente)**
* Você não possui checkout próprio
* Precisa enviar cobranças por WhatsApp, e-mail ou redes sociais
* Quer aceitar **PIX, cartão e boleto** no mesmo link
* Deseja um checkout pronto, seguro e hospedado pela Barte
***
### :rotate: Fluxo de pagamento
```
Link de pagamento pontual é criado
↓
Link é enviado ao cliente
↓
Cliente acessa o checkout Barte
↓
Pagamento é realizado
↓
Status da transação é atualizado
↓
Webhook é enviado para seu sistema
```
> 💡 A confirmação do pagamento deve ser feita via **webhook**, independentemente do método de pagamento.
***
### :download: Criando um Link de Pagamento Pontual
#### Endpoint
```
POST /v2/payment-links
```
***
#### Headers obrigatórios
| Header | Valor |
| ------------ | ---------------- |
| X-Token-Api | Sua chave de API |
| Content-Type | application/json |
***
#### Body
```json
{
"type": "ORDER",
"scheduledDate": "2026-01-30",
"paymentOrder": {
"title": "Link de Pagamento pontual",
"description": "Cobrança referente ao pedido X",
"value": 100,
"installments": 1,
"timer": true,
"expirationDate": "2026-02-10T18:00:00",
"customInstallmentsValues": [
{
"paymentMethod": "PIX",
"installments": 1
},
{
"paymentMethod": "CREDIT_CARD_EARLY_BUYER",
"installments": 10
},
{
"paymentMethod": "BANK_SLIP",
"installments": 1
}
]
},
"paymentMethods": [
"PIX",
"CREDIT_CARD_EARLY_BUYER",
"BANK_SLIP"
]
}
```
***
#### Response
Após a criação, a API retorna os dados do link de pagamento.
```json
{
"id": 9448,
"uuid": "a1b33060-6fc3-4057-bcd2-19a253c7b90e",
"type": "ORDER",
"url": "https://sandbox-checkout.barte.com/payment-link/a1b33060-6fc3-4057-bcd2-19a253c7b90e",
"scheduledDate": "2026-01-30",
"paymentOrder": {
"title": "Link de Pagamento Pontual",
"description": "Cobrança referente ao pedido X",
"value": 100,
"installments": 1,
"customInstallmentsValues": [
{
"paymentMethod": "PIX",
"installments": 1
},
{
"paymentMethod": "CREDIT_CARD_EARLY_BUYER",
"installments": 10
},
{
"paymentMethod": "BANK_SLIP",
"installments": 1
}
],
"expirationDate": "2026-02-10T18:00:00",
"timer": true
},
"processed": 0,
"enableAnchoring": false,
"allowedPaymentMethods": {
"pixMethod": {},
"bankSlipMethod": {},
"creditCardMethod": {
"type": "EARLY_BUYER"
}
},
"paymentMethods": [
"PIX",
"BANK_SLIP",
"CREDIT_CARD_EARLY_BUYER"
],
"enableBankSlip": true,
"enableCreditCard": true,
"enablePixPayment": true,
"subSellerResponse": [],
"idSeller": 2890
}
```
#### Campo mais importante da resposta
* `url` → **link de pagamento pontual** que deve ser enviado ao cliente
***
### :bell: Confirmação do pagamento
Após o cliente realizar o pagamento:
* O status da transação é atualizado na Barte
* Um **webhook é disparado** para o seu sistema
Utilize o webhook como **fonte de verdade** para confirmar o pagamento.
***
### :lightbulb: Boas práticas
* Utilize sempre `expirationDate`
* Confirme pagamentos apenas via webhook
* Armazene o `uuid` do link para rastreabilidade
* Use links pontuais para cobranças únicas
***
### :hexagon-xmark: O que não fazer
* Confirmar pagamento sem webhook
* Reutilizar links expirados
* Expor sua chave de API no frontend
# Link de Pagamento Recorrente
O **Link de Pagamento Recorrente** permite criar uma **assinatura** através de um checkout hospedado pela Barte.\
Ao acessar o link, o cliente realiza a contratação e os pagamentos passam a ocorrer de forma **recorrente**, conforme o plano configurado.
Esse tipo de link é indicado para **planos, mensalidades, serviços contínuos e cobranças recorrentes**, sem a necessidade de checkout próprio.
> ⚠️ Para criar um link de pagamento recorrente, antes é preciso criar um plano de assinatura. Veja mais em: [Criando Plano de Assinatura](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/assinaturas/criando-plano-de-assinatura)
***
### :thumbtack-angle: Quando usar Link de Pagamento Recorrente?
Utilize esse recurso quando:
* A cobrança for **recorrente**
* Você trabalha com planos ou mensalidades
* Deseja simplificar a contratação de assinaturas
* Precisa enviar links por WhatsApp, e-mail ou redes sociais
* Quer um checkout pronto e hospedado pela Barte
***
### :rotate: Fluxo de pagamento
```
Link de pagamento recorrente é criado
↓
Link é enviado ao cliente
↓
Cliente acessa o checkout Barte
↓
Assinatura é contratada
↓
Cobranças recorrentes são processadas
↓
Webhooks são enviados a cada alteração de status
```
> 💡 A confirmação e atualização da assinatura deve ser feita via **webhook**.
***
### :download: Criando um Link de Pagamento Recorrente
#### Endpoint
```
POST /v2/payment-links
```
***
#### Headers obrigatórios
| Header | Valor |
| ------------ | ---------------- |
| X-Token-Api | Sua chave de API |
| Content-Type | application/json |
***
#### Body da requisição (exemplo)
```json
{
"type": "SUBSCRIPTION",
"scheduledDate": "2026-01-30",
"uuidSellerClient": "123e4567-e89b-12d3-a456-426614174000",
"paymentSubscription": {
"idPlan": "123e4567-e89b-12d3-a456-426614174000",
"type": "MONTHLY",
"valuePerMonth": 100
},
"paymentMethods": [
"PIX",
"CREDIT_CARD_EARLY_BUYER",
"BANK_SLIP"
]
}
```
***
### :download: Resposta da API
Após a criação, a API retorna os dados do link de pagamento recorrente.
#### Exemplo de resposta
```json
{
"id": 9450,
"uuid": "a1b33060-6fc3-4057-bcd2-19a253c7b90e",
"type": "SUBSCRIPTION",
"url": "https://sandbox-checkout.barte.com/payment-link/a1b33060-6fc3-4057-bcd2-19a253c7b90e",
"scheduledDate": "2026-01-30",
"paymentSubscription": {
"idPlan": "123e4567-e89b-12d3-a456-426614174000",
"type": "MONTHLY",
"value": 100,
"valuePerMonth": 100
},
"processed": 0,
"enableAnchoring": false,
"allowedPaymentMethods": {
"pixMethod": {},
"bankSlipMethod": {},
"creditCardMethod": {
"type": "EARLY_BUYER"
}
},
"paymentMethods": [
"PIX",
"BANK_SLIP",
"CREDIT_CARD_EARLY_BUYER"
],
"enableBankSlip": true,
"enableCreditCard": true,
"enablePixPayment": true,
"subSellerResponse": [],
"idSeller": 2890
}
```
#### Campo mais importante da resposta
* `url` → **link de pagamento recorrente** que deve ser enviado ao cliente
***
### :bell: Atualizações da assinatura via webhook
Durante o ciclo de vida da assinatura, webhooks são enviados sempre que houver:
* Criação da assinatura
* Pagamento confirmado
* Falha de pagamento
* Cancelamento
* Alteração de status
> 💡 Utilize os webhooks de **Subscriptions** como fonte de verdade.
***
### :brain: Boas práticas
* Garanta que o plano esteja configurado antes de criar o link
* Utilize webhooks para controlar o ciclo da assinatura
* Armazene o `uuid` do link para rastreabilidade
* Trate falhas de pagamento corretamente
***
### :hexagon-xmark: O que não fazer
* Criar link recorrente sem plano configurado
* Confirmar assinatura sem webhook
* Ignorar eventos de falha de pagamento
# Assinaturas
Assinaturas permitem criar **cobranças recorrentes automáticas**, ideais para produtos e serviços com pagamento periódico.
Na Barte, o fluxo de assinaturas é dividido em duas etapas principais:
1. **Criação do plano**, onde você define valores, periodicidade e métodos de pagamento
2. **Criação da assinatura**, onde um cliente é vinculado a esse plano e as cobranças passam a ocorrer automaticamente
Todas as mudanças de status das assinaturas e de suas cobranças são comunicadas via **webhook**.
***
### O que você pode fazer nesta seção
#### :diamond: Criando Plano de Assinatura
Defina as regras da cobrança recorrente, como periodicidade, valores, benefícios e métodos de pagamento aceitos.
Acessar [Criando Plano de Assinatura](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/assinaturas/criando-plano-de-assinatura)
***
#### :diamond: Criando Assinatura
Vincule um cliente a um plano existente e inicie o ciclo de cobranças recorrentes.
Acessar [Criando Assinatura](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/assinaturas/criando-assinatura)
# Criando Plano de Assinatura
Um **Plano de Assinatura** define as regras de cobrança recorrente que serão utilizadas na criação de **subscriptions** (assinaturas).\
O plano determina **valores**, **periodicidade**, **métodos de pagamento aceitos** e **benefícios exibidos ao cliente**.
📌 Um plano **não gera cobranças automaticamente**.\
Ele é utilizado posteriormente na criação de assinaturas.
***
### Endpoint
**POST** `/v2/plans`\
`https://api.barte.com/v2/plans`
#### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
***
### Body
```json
{
"title": "Plano Simples",
"description": "Descrição do plano",
"active": false,
"bullets": [
{
"title": "Benefício 1",
"description": "Descrição do benefício"
}
],
"values": [
{
"type": "MONTHLY",
"valuePerMonth": 99.9
}
],
"acceptPaymentMethods": [
"CREDIT_CARD",
"PIX",
"BANK_SLIP"
]
}
```
***
### Response
```json
{
"uuid": "08893f29-d904-4367-93a7-648c33543542",
"title": "Plano Simples",
"description": "Descrição do Plano",
"bullets": [
{
"title": "Plano Simples",
"description": "Descrição do benefício"
}
],
"active": false,
"values": [
{
"type": "MONTHLY",
"value": 99.9,
"valuePerMonth": 99.9
}
],
"acceptPaymentMethods": [
"BANK_SLIP",
"CREDIT_CARD",
"PIX"
]
}
```
#### Campos mais importantes da resposta
* `uuid` - Identificador único do plano. Este campo deve salvo para:
* Criação de assinaturas
* Consultas futuras
* Rastreabilidade e auditoria
* `active` - Indica se o plano está ativo e disponível para uso
* `values` - Lista de valores configurados no plano, contém:
* Contém o tipo de cobrança
* Valor total do período
* Valor mensal equivalente
* `acceptPaymentMethods` - Lista final de métodos de pagamento aceitos no plano
***
### :rotate: Fluxo de uso do plano
1. Criar o plano de assinatura
2. Ativar o plano (`active = true`)
3. Criar uma assinatura vinculada ao plano
4. Cobranças recorrentes são geradas automaticamente
5. Alterações de status são notificadas via webhook
***
### :bell: Confirmações e eventos
* A criação do plano **não gera cobrança**
* Nenhum pagamento é processado nessa etapa
* Webhooks passam a ser disparados **apenas após a criação de assinaturas**
* Alterações de status das cobranças recorrentes são sempre notificadas via webhook
***
### :lightbulb: Boas práticas
* Crie planos separados para cada regra de cobrança
* Use descrições claras e objetivas
* Utilize `bullets` para destacar benefícios importantes
* Ative o plano apenas quando estiver pronto para uso
* Armazene o `uuid` do plano
* Defina corretamente os métodos de pagamento aceitos
***
### :hexagon-xmark: O que não fazer
* Alterar planos ativos com assinaturas já vinculadas
* Reutilizar o mesmo plano para regras de cobrança diferentes
* Assumir que criar o plano gera cobrança
* Expor sua chave de API no frontend
* Criar assinaturas com planos inativos
# Criando Assinatura
A **assinatura** representa uma cobrança recorrente baseada em um **plano previamente criado**.\
Ao criar uma assinatura, a Barte passa a gerar cobranças automaticamente de acordo com a periodicidade definida no plano.
📌 A confirmação de pagamentos recorrentes **sempre ocorre via webhook**, independentemente do método de pagamento.
***
### Endpoint
**POST** `/v2/subscriptions`\
`https://api.barte.com/v2/subscriptions`
#### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
***
### Pré-requisitos
Antes de criar uma assinatura, é necessário:
* Ter um **plano ativo**
* Possuir o `uuid` do plano
* Possuir o `uuid` do comprador (buyer)
* Definir o método de pagamento aceito pelo plano
***
### Body
```json
{
"uuidPlan": "123e4567-e89b-12d3-a456-426614174000",
"basicValue": {
"type": "MONTHLY",
"valuePerMonth": 100
},
"additionalValue": {
"installments": 1,
"value": 100
},
"payment": {
"method": "CREDIT_CARD",
"card": {
"holderName": "JOAO DA SILVA",
"number": "4111111111111111",
"expiration": "12/2026",
"cvv": "123",
"buyerUuid": "123e4567-e89b-12d3-a456-426614174000"
},
"fraudData": {
"document": "12345678900",
"email": "email@exemplo.com",
"name": "João da Silva",
"phone": "11999999999"
}
},
"uuidBuyer": "123e4567-e89b-12d3-a456-426614174000",
"startDate": "2026-01-29",
"metadata": [
{
"key": "text",
"value": "text"
}
]
}
```
***
### Response
```json
{
"uuid": "f38644c8-ff93-410c-be8d-84c5c608dacf",
"status": "ACTIVE",
"customer": {
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"email": "name@gmail.com",
"document": "text"
},
"startDate": "2026-01-29",
"value": {
"type": "MONTHLY",
"valuePerMonth": 100
},
"additionalValue": {
"installments": 1,
"value": 100
},
"paymentMethod": "CREDIT_CARD",
"charges": [
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"status": "PAID",
"value": 1,
"createdAt": "2026-01-29T19:48:36.007Z",
"updatedAt": "2026-01-29T19:48:36.007Z"
}
]
}
```
***
#### Campos mais importantes da resposta
* `uuid` - Identificador único da assinatura. Deve ser salvo para:
* Consultas futuras
* Validação de webhooks
* Gestão da assinatura
* `status` - Status atual da assinatura. Exemplos:
* `PENDING` → aguardando primeiro pagamento
* `ACTIVE` → assinatura ativa
* `CANCELED` → assinatura cancelada
* `SUSPENDED` → cobrança interrompida
* `charges[].uuid` - Identificador da cobrança gerada. Necessário para:
* Estornos
* Conciliação
* Auditoria
* `charges[].status` - Status da cobrança recorrente. Exemplos:
* `PAID`
* `PENDING`
* `FAILED`
* `ABANDONED`
***
### :bell: Confirmação de pagamento
Após a criação da assinatura:
* A primeira cobrança é gerada automaticamente
* O pagamento pode ser:
* Processado imediatamente (cartão)
* Processado de forma assíncrona (PIX / boleto)
* Alterações de status **sempre geram webhooks**
📌 Utilize o webhook como **fonte única de verdade** para:
* Confirmar pagamento
* Ativar serviços
* Liberar acesso
***
### :rotate: Fluxo resumido da assinatura
```
Criar assinatura
↓
Gerar cobrança recorrente
↓
Cliente realiza pagamento
↓
Status atualizado na Barte
↓
Webhook enviado
↓
Seu sistema confirma o pagamento
```
***
### :lightbulb: Boas práticas
* Sempre armazene:
* `uuid` da assinatura
* `uuid` das cobranças
* Utilize webhooks para confirmação
* Trate webhooks de forma idempotente
* Valide se o plano está ativo antes de criar a assinatura
* Use `metadata` para controle interno
* Monitore falhas de pagamento recorrente
***
### :hexagon-xmark: O que não fazer
* Criar assinatura com plano inativo
* Confirmar pagamento sem webhook
* Reutilizar assinaturas canceladas
* Assumir sucesso apenas pela resposta da API
* Expor sua chave de API no frontend
# 3º - Pós-pagamento
Esta seção aborda tudo o que acontece **após a tentativa de pagamento** de um pedido, link de pagamento ou assinatura.
Aqui você aprende a **confirmar pagamentos**, **acompanhar o status das cobranças** e **executar estornos**, sempre utilizando os fluxos corretos da Barte.
O pós-pagamento é uma etapa crítica para garantir:
* consistência financeira
* conciliação correta
* segurança contra fraudes
* integração confiável com seu sistema
***
### O que você pode fazer nesta seção
#### :diamond: Confirmando pagamento via Webhook
Entenda como receber notificações automáticas sempre que uma transação muda de status e como utilizá-las como **fonte de verdade**.
Acessar [Confirmando pagamento via Webhook](/guias/passo-a-passo-do-vendedor/3o-pos-pagamento/confirmando-pagamento-via-webhook)
***
#### :diamond: Consultando status do Pedido
Aprenda a consultar o estado atual de um pedido ou cobrança via API, utilizando seu `uuid`.
Acessar [Consultando status do Pedido](/guias/passo-a-passo-do-vendedor/3o-pos-pagamento/consultando-status-do-pedido)
***
#### :diamond: Estorno Total de um Pedido
Veja como realizar o estorno completo de uma cobrança e entender os retornos e regras do processo.
Acessar [Broken mention](broken://pages/ViMdmEsIYlAS47pmO6m5)
# Confirmando pagamento via Webhook
Pagamentos na Barte podem ocorrer de forma **síncrona** ou **assíncrona**, dependendo do método de pagamento.\
Independentemente do método utilizado, a **confirmação oficial de qualquer pagamento deve ser feita via webhook**.
Webhooks garantem que seu sistema seja notificado sempre que uma transação sofrer **alteração de status**, permitindo manter seus pedidos sincronizados com a Barte.
***
### :thumbtack-angle: Quando usar este fluxo?
Este fluxo deve ser utilizado quando:
* O pagamento for via **PIX** ou **boleto** (pagamentos assíncronos)
* O pagamento for via **cartão de crédito**, mesmo com retorno síncrono
* Seu sistema precisar reagir automaticamente a mudanças de status
* Você quiser garantir consistência em casos de estorno, cancelamento ou disputa
***
### :rotate: Como funciona a confirmação de pagamento
```
Pedido criado
↓
Pagamento iniciado
↓
Status da transação muda na Barte
↓
Webhook é enviado para seu sistema
↓
Seu sistema valida o evento
↓
Pedido é atualizado automaticamente
```
***
### :credit-card: Pagamentos via cartão também disparam webhooks
Pagamentos via **cartão de crédito** normalmente retornam um status imediato no momento da criação da transação.\
Ainda assim, a Barte **dispara webhooks para pagamentos com cartão** sempre que houver qualquer alteração de status.
Isso inclui:
* Confirmação final do pagamento
* Atualizações pós-processamento
* Cancelamentos
* Estornos
* Disputas e chargebacks
> 💡 **Recomendação:** utilize sempre o webhook como **fonte de verdade**, inclusive para pagamentos com cartão.
***
### :download: Recebendo o webhook
Sempre que uma transação sofre alteração de status, a Barte envia uma requisição **HTTP POST** para a URL configurada no webhook.
O payload enviado contém as informações necessárias para identificar:
* O pedido
* O tipo de evento
* O status atual da transação
Você pode verificar mais detalhes sobre os payloads dos Webhooks aqui:
* [V1 (Deprecado)](/guias/webhooks/webhooks-overview/campos-dos-webhooks)
* [Pedidos (Orders) e Assinaturas (Subscriptions)](/guias/webhooks/pedidos-orders-e-assinaturas-subscriptions)
* [Pedidos Físicos (Maquininhas)](/guias/webhooks/pedidos-fisicos-maquininhas)
* [Disputas e Chargebacks](/guias/webhooks/disputas-e-chargebacks)
***
### :check: Confirmando o pagamento corretamente
Ao receber um webhook, seu sistema deve seguir as etapas abaixo:
1. **Identificar o pedido**
* Utilize o identificador do pedido (`uuid`) enviado no payload.
2. **Validar o status da transação**
* Verifique se o status recebido representa pagamento confirmado.
3. **Atualizar o pedido no seu sistema**
* Marque o pedido como pago.
* Libere o produto, serviço ou acesso.
4. **Retornar HTTP 200**
* Indica que o webhook foi processado com sucesso.
***
### :arrow-right-arrow-left: Reenvio de webhooks e idempotência
Caso seu sistema:
* Retorne erro
* Não responda
* Esteja indisponível
A Barte poderá **reenviar o webhook**.
Por isso, seu endpoint deve ser **idempotente**, ou seja, capaz de processar o mesmo evento mais de uma vez sem gerar duplicidade ou inconsistência.
***
### :lightbulb: Boas práticas
* Utilize webhooks como **fonte principal de atualização**
* Processe eventos de forma assíncrona
* Registre logs do payload recebido
* Evite lógica complexa no endpoint de webhook
* Garanta que a mesma transação não seja processada duas vezes
***
### :hexagon-xmark: O que não fazer
* Confirmar pagamento sem webhook
* Depender apenas do retorno síncrono do cartão
* Ignorar eventos de cancelamento, estorno ou disputa
***
#### :exclamation:Observação final
> Para todos os métodos de pagamento, o **webhook é o meio oficial de confirmação e atualização de status** das transações na Barte, embora transações no cartão de crédito tragam uma confirmação síncrona.
# Consultando status do Pedido
Este endpoint permite consultar **o estado atual de um pedido**, incluindo:
* Status geral do pedido
* Cobranças associadas
* Dados do pagamento
📌 Esse endpoint é **consultivo** e deve ser usado para:
* Reconciliação
* Exibição de status ao cliente
* Auditoria
* Recuperação de estado em caso de falha
⚠️ **Não substitui o uso de webhooks** para confirmação de pagamento.
***
### Endpoint
**GET** `/v2/orders/{uuid}`\
`https://api.barte.com/v2/orders/{uuid}`
#### Headers
```
X-Token-Api: YOUR_API_KEY
Accept: */*
```
***
### Path Param
#### `uuid` (obrigatório)
Identificador único do pedido.
📌 Deve ser o `uuid` retornado no momento da criação do pedido.
***
### Exemplo de resposta
```json
{
"uuid": "e82c66cc-cdf6-4253-87b2-ed339d3b9669",
"status": "PAID",
"title": "Teste",
"description": "",
"value": 100,
"installments": 5,
"startDate": "2025-10-14",
"payment": "CREDIT_CARD_EARLY_SELLER",
"customer": {
"uuid": "",
"document": "001052647",
"type": "SSN",
"documentCountry": "US",
"name": "Joshua Henry",
"email": "Heyj5wohn4445@gmail.com",
"phone": "9409822523",
"alternativeEmail": ""
},
"idempotencyKey": "b6cf42ba-3b64-4587-ba91-eec18465d091",
"charges": [
{
"uuid": "f337e5a4-62a3-41af-8449-c9898f1de66b",
"title": "Teste",
"expirationDate": "2025-10-14",
"paidDate": "2025-10-14",
"value": 100,
"paymentMethod": "CREDIT_CARD_EARLY_SELLER",
"status": "PAID",
"authorizationCode": "488713",
"authorizationNsu": "154054",
"retryable": false,
"fee": 0.49
}
]
}
```
***
### :bell: Webhooks x Consulta
| Uso | Recomendação |
| ------------------------ | ------------ |
| Confirmar pagamento | ✅ Webhook |
| Exibir status ao cliente | ✅ GET Order |
| Reconciliação | ✅ GET Order |
| Auditoria | ✅ GET Order |
| Ativar serviço | ❌ GET Order |
📌 **Webhook é a fonte oficial de verdade** para eventos financeiros.
***
### :rotate: Fluxo recomendado
```
Criar pedido
↓
Aguardar webhook
↓
Confirmar pagamento no webhook
↓
Persistir status final
↓
Usar GET /orders/{uuid} apenas para consulta
```
***
### :lightbulb: Boas práticas
* Sempre salve:
* `uuid` do pedido
* `value`
* `status`
* `charges[].uuid`
* Use esse endpoint para:
* Recuperação de estado
* Debug
* Painéis administrativos
* Confirme pagamento **somente via webhook**
* Trate divergências entre webhook e GET como exceção crítica
***
### :hexagon-xmark: O que não fazer
* Confirmar pagamento apenas com GET
* Ignorar o status das cobranças
* Confiar apenas no status do pedido sem validar charge
* Alterar estado interno baseado apenas em polling
* Expor a API Key no frontend
# Estorno de um Pedido
Este endpoint permite realizar o **estorno total ou parcial de uma cobrança (`charge`)** já processada.\
O estorno é sempre feito **no nível da cobrança**, e não diretamente no pedido (`order`).
📌 Um pedido pode possuir **uma ou mais cobranças**, portanto o estorno deve ser executado **para cada charge elegível**.
***
### Endpoint
**PATCH** `/v2/charges/partial-refund/{uuid}`\
`https://api.barte.com/v2/charges/partial-refund/{uuid}`
***
### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
***
### Path Param
#### `uuid` (obrigatório)
Identificador único da cobrança (`charge.uuid`).
📌 Esse `uuid` é obtido:
* Na criação do pedido
* Na consulta do pedido (`GET /v2/orders/{uuid}`)
* Via webhook de atualização de status
***
### Body
```json
{
"value": 100
}
```
#### `value`
Indica o valor que deverá ser estornado da cobrança.
📌 Também é possível passar o valor total da cobrança, realizando assim um estorno total.
***
### Exemplo de resposta
```json
[{
"uuid": "",
"originalValue": 100,
"value": 0,
"refundValue": 100,
"refundStatus": "processing"
}]
```
***
### Campos mais importantes da resposta
* `uuid` - Identificador único da cobrança estornada. Use para:
* Auditoria
* Suporte
* Conciliação financeira
* `value` - Valor atual da cobrança após a solicitação de estorno
* `originalValue` - Valor original da cobrança
* `refundValue` - Valor da solicitação de estorno
* `refundStatus` - Status em que se encontra a solicitação de estorno
***
### :rotate: Fluxo recomendado de estorno
```
Consultar pedido
↓
Identificar charge elegível
↓
Executar PATCH /partial-refund
↓
Validar retorno
↓
Atualizar estado final
```
***
### :lightbulb: Boas práticas
* Sempre valide:
* `value`
* `originalValue`
* Armazene:
* `uuid` da charge
* Status anterior e posterior
***
### :hexagon-xmark: O que não fazer
* Tentar estornar novamente quando `value = 0`
* Estornar pedido sem identificar a cobrança correta
* Implementar loop automático de retry sem validação
# Consultando um Estorno Parcial
Este endpoint permite **consultar o status e o histórico dos estornos parciais** de uma cobrança (charge) já processada.
> ⚠️ Este endpoint é **somente para consulta**. Ele **não cria**, **não altera** e **não cancela** estornos.
***
### Endpoint
**GET** `/v2/charges/partial-refund/{uuid}`\
`https://api.barte.com/v2/charges/partial-refund/{uuid}`
***
### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
***
### Path Param
#### `uuid` (obrigatório)
Identificador único da cobrança (`charge.uuid`).
📌 Esse `uuid` é obtido:
* Na criação do pedido
* Na consulta do pedido (`GET /v2/orders/{uuid}`)
***
### Body
Essa requisição **não possui body**.
***
### Exemplo de resposta
```json
[
{
"uuid": "9ec29500-7700-4e40-9a8a-66bf23795d06",
"value": 0,
"originalValue": 1000,
"refunds": [
{
"id": "81877",
"createdAt": "2026-01-30T15:55:10.000Z",
"amount": 1000,
"requestStatus": "processing"
}
]
}
]
```
***
### Campos mais importantes da resposta
* `uuid` - Identificador único da cobrança estornada. Use para:
* Auditoria
* Suporte
* Conciliação financeira
* `value` - Valor atual da cobrança após estornos parciais
* `originalValue` - Valor original da cobrança, antes de qualquer estorno
* `refunds` - Lista de solicitações de estorno parcial
* `refunds[].id` - Identificador interno da solicitação de estorno
* `refunds[].createdAt` - Data e hora da solicitação
* `refunds[].amount` - Valor solicitado no estorno
* `refunds[].requestStatus` - Status atual da solicitação
***
#### Status possíveis de `requestStatus`
| Status | Descrição |
| ---------- | ------------------------------------- |
| processing | Estorno solicitado e em processamento |
| success | Estorno concluído com sucesso |
| failed | Estorno não concluído |
📌 Enquanto o status estiver `processing`, o valor pode ainda não ter sido efetivamente devolvido ao comprador.
***
### :lightbulb: Boas práticas
* Sempre valide:
* `value`
* `originalValue`
* `refunds[].requestStatus`
* Utilize este endpoint para:
* Acompanhamento de estornos parciais
* Conciliação financeira
* Auditoria e suporte
* Armazene:
* `uuid` da charge
* Valor solicitado em cada estorno
* Histórico de status das solicitações
***
### :hexagon-xmark: O que não fazer
* Não tente criar novos estornos parciais enquanto existirem solicitações com status `processing`
* Não utilize este endpoint para criar ou cancelar estornos
* Não assuma que o estorno foi concluído sem validar o `requestStatus`
# 4º - Casos de uso (Fluxo completo)
Nesta seção você encontrará guias passo a passo para criar pedidos na Barte, cobrindo os principais cenários de cobrança utilizados pelos vendedores.
Nesta etapa você verá casos de uso de cada fluxo de pagamento, desde a primeira etapa onde obtemos o token de api, até a confirmação da transação e demais ações.
A Barte oferece três formas principais de cobrança:
* **Pedidos** → cobranças criadas via API, ideais para integrações diretas e fluxos customizados
* **Links de Pagamento** → cobranças compartilháveis, sem necessidade de checkout próprio
* **Assinaturas** → cobranças recorrentes baseadas em planos
Cada uma atende a um cenário diferente de venda, mas todas seguem os mesmos princípios:
* possuem identificadores únicos (`uuid`)
* geram cobranças (`charges`)
* têm seus status atualizados ao longo do tempo
* disparam **webhooks** sempre que há mudança de estado
***
### O que você vai encontrar nesta seção
#### :diamond: Pedidos
Fluxo completo de criação de cobranças via API para pagamentos pontuais, com suporte a PIX, boleto, cartão de crédito, pré-captura, tokenização e 3DS;
Acessar [Pedidos](/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos)
***
#### :diamond: Links de Pagamento
Fluxo completo de geração de links prontos para pagamento, ideais para cobranças manuais, envio por WhatsApp, e-mail ou redes sociais.
Acessar (Em breve)
***
#### :diamond: Assinaturas
Fluxo completo de configuração de planos e criação de cobranças recorrentes automáticas, com controle de ciclo, valores e status.
Acessar (Em breve)
# Pedidos
# Use Case - Pedido simples (PIX, Boleto e Cartão de Crédito)
Este caso de uso descreve como um vendedor cria um pedido único na API da Barte, vinculando obrigatoriamente um comprador (Buyer) e processando o pagamento via PIX, Boleto ou Cartão de Crédito, além d
***
### Atores
* **Vendedor (Seller)**: Sistema integrador que consome a API da Barte
* **Barte API**: Responsável por processar pedidos, pagamentos e pós-pagamento
***
### Pré-condições
* O vendedor possui um **Token de API válido**
* Link rápido → [Obtendo o Token de API](/guias/passo-a-passo-do-vendedor/1o-preparacao/obtendo-o-token-de-api)
* O comprador (**Buyer**) **deve existir** antes da criação do pedido
* Link rápido → [Criando um Comprador](/guias/pedidos-e-cobrancas/criando-um-comprador)
***
### Fluxo Principal
#### 1. Autenticação na API
O vendedor autentica todas as requisições utilizando seu Token de API.
**Header obrigatório em todas as chamadas:**
```
X-Token-Api: YOUR_API_KEY
```
📌 Referência: **Obtendo o Token de API**
***
#### 2. Criar um Comprador (Buyer) — *Obrigatório*
Todo pedido na Barte **deve estar vinculado a um Buyer**.\
O Buyer representa a pessoa física ou jurídica responsável pelo pagamento.
**Ação**
* O vendedor cria um Buyer informando dados de identificação, contato e endereço.
**Resultado esperado**
* A API retorna o campo `uuid` do Buyer.
📌 **Importante:**\
Esse `uuid` será utilizado obrigatoriamente na criação do pedido.
📌 Referência: [Criando um Comprador](/guias/pedidos-e-cobrancas/criando-um-comprador)
***
#### 3. Criar um Pedido (Order)
Com o Buyer criado, o vendedor pode criar um pedido informando:
* Valor da transação
* Datas
* Descrição do pedido
* Método de pagamento
* Dados específicos do pagamento (ex: cartão, PIX ou boleto)
* `uuidBuyer` (obrigatório)
**Métodos de pagamento suportados neste use case**
* Cartão de Crédito
* PIX
* Boleto
📌 Referência: [Métodos de Pagamento](/guias/inicio/metodos-de-pagamento)
***
**Resultado esperado**
* A API cria o pedido
* Uma ou mais **charges** são geradas
* O status inicial do pedido e da charge depende do método de pagamento:
* Cartão: geralmente `PAID` ou `AUTHORIZED`
* PIX/Boleto: geralmente `PENDING`
📌 O `uuid` da **charge** será necessário para ações de pós-pagamento.
📌 Referência: [Pedido simples (PIX, Boleto e Cartão de Crédito)](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-simples-pix-boleto-e-cartao-de-credito)
***
### Fluxos Pós-Pagamento
Após a criação do pedido, o vendedor pode executar ações adicionais dependendo do status da charge.
***
#### 4.1 Estorno Total de uma Charge
Realiza o estorno completo do valor pago.
**Quando usar**
* Cancelamento integral da venda
* Fraude confirmada
* Erro operacional
📌 Referência: [Broken mention](broken://pages/ViMdmEsIYlAS47pmO6m5)
***
#### 4.2 Estorno Parcial de uma Charge
Realiza o estorno de parte do valor pago.
**Quando usar**
* Devolução parcial de produtos
* Ajustes comerciais
📌 Referência: [Estorno de um Pedido](/guias/passo-a-passo-do-vendedor/3o-pos-pagamento/estorno-parcial-de-um-pedido)
***
### Pós-condições
Ao final deste caso de uso, o vendedor consegue:
* Autenticar-se na API da Barte
* Criar obrigatoriamente um Buyer
* Criar um pedido com pagamento via PIX, Boleto ou Cartão
* Consultar o status do pedido e da charge
* Realizar estorno total ou parcial de uma charge
***
### Observações Importantes
* Um **pedido nunca pode existir sem um Buyer**
* O controle de status definitivo do pagamento deve ser feito via **webhook**
* Para operações idempotentes, utilize corretamente a `idempotencyKey`
# Pedido com Pré-captura
Este caso de uso descreve como um vendedor cria um pedido com cartão de crédito utilizando pré-captura, ou seja, o valor é apenas autorizado no cartão do comprador e capturado posteriormente, conforme
***
### Atores
* **Vendedor (Seller)**: Sistema integrador
* **Comprador (Buyer)**: Pessoa que realizará o pagamento
* **Barte API**: Responsável pela autorização, captura e pós-pagamento
***
### Pré-condições
* O vendedor possui um **Token de API válido**
* Link rápido → [Obtendo o Token de API](/guias/passo-a-passo-do-vendedor/1o-preparacao/obtendo-o-token-de-api)
* O **Buyer é obrigatório** e deve ser criado previamente
* Link rápido → [Criando um Comprador](/guias/pedidos-e-cobrancas/criando-um-comprador)
* O pagamento será realizado via **Cartão de Crédito**
* O pedido será criado com **pré-captura (`capture = false`)**
***
### Fluxo Principal
#### 1. Autenticação na API
Todas as requisições devem conter o Token de API no header:
```
X-Token-Api: YOUR_API_KEY
```
📌 Referência: **Obtendo o Token de API**
***
#### 2. Criar um Comprador (Buyer) — Obrigatório
O Buyer representa o pagador e **é obrigatório para a criação de pedidos**.
**Objetivo**
* Identificar corretamente o comprador
* Suportar antifraude, conciliação e pós-pagamento
**Resultado esperado**
* A API retorna o `uuid` do Buyer
📌 Esse `uuid` será utilizado obrigatoriamente na criação do pedido.
📌 Referência: [Criando um Comprador](/guias/pedidos-e-cobrancas/criando-um-comprador)
***
#### 3. Criar um Pedido com Pré-captura
Com o Buyer criado, o vendedor cria o pedido configurado para **pré-captura**.
**Configuração importante**
* `capture = false` → o valor será **somente autorizado**
* Nenhum valor é debitado neste momento
**O que acontece**
* O cartão é validado
* O valor é autorizado pelo emissor
* Uma **charge** é criada com status `PRE_AUTHORIZED`
**Resultado esperado**
* Pedido criado com sucesso
* Uma ou mais charges associadas
* Status da charge: `PRE_AUTHORIZED`
📌 O `uuid` da charge será necessário para capturar ou cancelar a autorização.
📌 Referência: [Pedido com Pré-captura](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-com-pre-captura)
***
### Fluxos Alternativos
#### 4. Capturar Cobrança (Charge)
Após a pré-autorização, o vendedor decide capturar o valor.
**Quando usar**
* Produto enviado
* Serviço prestado
* Confirmação manual ou automática do vendedor
**Regras importantes**
* A captura ocorre **sempre no nível da charge**
* Uma order pode conter **mais de uma charge**
* Se a charge não for capturada em até **6 dias**, ela será cancelada automaticamente
**Resultado esperado**
* Status da charge passa para `PAID`
* O valor é efetivamente debitado do cartão
📌 Referência: [/pages/Rtvyd11YawfpvzsQskyC#id-2.-capturar-cobranca-charge](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/Rtvyd11YawfpvzsQskyC#id-2.-capturar-cobranca-charge "mention")
***
#### 5. Cancelar Pré-captura
Permite cancelar uma cobrança **antes da captura**, sem gerar estorno.
**Quando usar**
* A venda não será concluída
* O status da charge ainda é `PRE_AUTHORIZED`
**Importante**
* Este endpoint **não deve ser usado após a captura**
* Não há estorno, pois o valor ainda não foi debitado
**Resultado esperado**
* A autorização é cancelada
* O valor é liberado no cartão do comprador
📌 Referência: [/pages/Rtvyd11YawfpvzsQskyC#id-3.-cancelar-pre-captura](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/Rtvyd11YawfpvzsQskyC#id-3.-cancelar-pre-captura "mention")
***
### Fluxos Pós-Captura
Após a captura (`PAID`), entram os fluxos padrão de pós-pagamento.
***
#### 6.1 Estorno Total
Realiza o estorno completo do valor capturado.
📌 Referência: [Broken mention](broken://pages/ViMdmEsIYlAS47pmO6m5)
***
#### 6.2 Estorno Parcial
Realiza o estorno de parte do valor capturado.
📌 Referência: **Estorno Cobrança (Parcial)**
***
### Pós-condições
Ao final deste caso de uso, o vendedor consegue:
* Autenticar-se na API
* Criar obrigatoriamente um Buyer
* Criar um pedido com cartão de crédito e pré-captura
* Capturar ou cancelar a cobrança conforme decisão de negócio
* Realizar estornos após a captura, quando necessário
***
### Observações Importantes
* **Buyer é obrigatório**
* Pré-captura **não debita o valor**
* Cancelamento de pré-captura **não é estorno**
* A captura sempre ocorre no nível da **charge**
# Pedido com Cartão Tokenizado
Este caso de uso descreve como um vendedor cria um pedido com cartão de crédito utilizando tokenização, garantindo que os dados sensíveis do cartão não trafeguem novamente após a primeira captura.
#### O fluxo é indicado para:
* Ambientes que exigem **maior segurança**
* Reutilização de cartões
* Conformidade com boas práticas de PCI
* Fluxos compatíveis com autenticação forte (ex.: 3DS quando aplicável)
***
### Atores
* **Vendedor (Seller)**\
Sistema integrador que cria compradores, tokeniza cartões e gera pedidos.
* **Comprador (Buyer)**\
Pessoa responsável pelo pagamento.
* **Barte API**\
Responsável pela tokenização, autorização do cartão, captura e pós-pagamento.
***
### Pré-condições
* O vendedor possui um **Token de API válido**
* O **Buyer é obrigatório** e deve ser criado previamente
* O pagamento será realizado via **Cartão de Crédito**
* O cartão será **tokenizado antes da criação do pedido**
***
### Fluxo Principal
#### 1. Autenticação na API
Todas as requisições devem conter o Token de API no header:
```
X-Token-Api: YOUR_API_KEY
```
📌 Referência: [Obtendo o Token de API](/guias/passo-a-passo-do-vendedor/1o-preparacao/obtendo-o-token-de-api)
***
#### 2. Criar um Comprador (Buyer) — Obrigatório
O Buyer representa o pagador e é **obrigatório** para:
* Tokenização de cartão
* Criação de pedidos
* Antifraude e rastreabilidade
**Resultado esperado**
* A API retorna o `uuid` do Buyer
📌 Esse `uuid` será utilizado:
* Na tokenização do cartão
* Na criação do pedido
📌 Referência: [Criando um Comprador](/guias/pedidos-e-cobrancas/criando-um-comprador)
***
#### 3. Tokenizar o Cartão (Card Token)
A tokenização cria uma **representação segura do cartão**, permitindo reutilização sem reenvio dos dados sensíveis.
**O que acontece**
* Os dados do cartão são enviados **uma única vez**
* A Barte gera um token seguro
* O cartão pode ser reutilizado em cobranças futuras
**Configurações importantes**
* `buyerUuid` é obrigatório
* `checkZeroDollar` define se haverá validação sem cobrança
**Resultado esperado**
* Um token de cartão é criado com status:
* `ACTIVE` → pronto para uso
* `PENDING` → será ativado após a primeira transação bem-sucedida
⚠️ **Atenção — Campo correto**
* O **cardToken** a ser usado na order é:
```
response.uuid
```
* ❌ Não utilizar `cardId` para criar transações
📌 Referência: [/pages/RY6HmRwnw2zZmYTlPa2B#id-1.-criar-card-token-tokenizacao-de-cartao](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/RY6HmRwnw2zZmYTlPa2B#id-1.-criar-card-token-tokenizacao-de-cartao "mention")
***
#### 4. Criar um Pedido utilizando Card Token
Com o Buyer e o cardToken criados, o vendedor cria o pedido normalmente.
**Regra importante**
* No objeto `payment.card`, devem ser enviados **apenas**:
* `cardToken`
* `cvv`
**O que acontece**
* O cartão tokenizado é utilizado
* O valor é autorizado e capturado conforme configuração
* Uma ou mais charges são criadas
**Resultado esperado**
* Pedido criado com sucesso
* Status da charge:
* `PAID` (quando `capture = true`)
* ou `PRE_AUTHORIZED` (se usado com pré-captura)
📌 O `uuid` da charge será necessário para ações de pós-pagamento.
📌 Referência: [Pedido com Cartão Tokenizado](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-com-cartao-tokenizado)
***
### Fluxos Pós-Pagamento
Após a captura (`PAID`), entram os fluxos padrão de pós-pagamento.
#### 5.1 Estorno Total
Permite estornar integralmente o valor capturado.
📌 Referência: [Broken mention](broken://pages/ViMdmEsIYlAS47pmO6m5)
***
#### 5.2 Estorno Parcial
Permite estornar parte do valor capturado.
📌 Referência: [Estorno de um Pedido](/guias/passo-a-passo-do-vendedor/3o-pos-pagamento/estorno-parcial-de-um-pedido)
***
### Pós-condições
Ao final deste caso de uso, o vendedor consegue:
* Autenticar-se na API
* Criar obrigatoriamente um Buyer
* Tokenizar um cartão com segurança
* Criar pedidos utilizando card token
* Reutilizar o cartão em cobranças futuras
* Realizar estornos totais ou parciais
***
### Observações Importantes
* Buyer é obrigatório em todo o fluxo
* O token pode ser reutilizado em múltiplas transações
* A captura ocorre sempre no nível da **charge**
* Tokenização pode ser combinada com pré-captura
* O armazenamento de dados sensíveis de cartão é permitido apenas para vendedores compatíveis com o PCI DSS. Vendedores sem certificação PCI DSS não devem, em hipótese alguma, armazenar esses dados.
# Pedido com 3DS (3D Secure)
Este caso de uso descreve como um vendedor cria um pedido com cartão de crédito autenticado via 3DS (EMV 3DS), incluindo coleta de dados do navegador e execução do desafio (Step Up), quando exigido pe
### Atores
* **Vendedor (Seller)**\
Sistema integrador que cria compradores, tokeniza cartões e cria pedidos.
* **Comprador (Buyer)**\
Pessoa física responsável pelo pagamento.
* **Barte API**\
Responsável pela tokenização, orquestração do 3DS, autorização e cobrança.
* **Emissor do Cartão**\
Banco responsável pela autenticação 3DS e autorização financeira.
***
### Pré-condições
* O vendedor possui um **Token de API válido**
* O **Buyer é obrigatório** e deve ser criado previamente
* O pagamento será realizado via **Cartão de Crédito**
* O cartão será **tokenizado antes da criação do pedido**
* O vendedor implementou:
* Coleta de dados do navegador (Browser Data Collection)
* Tela ou iframe para o **Step Up Challenge**, quando necessário
***
### Fluxo Principal
#### 1. Autenticação na API
Todas as requisições devem conter o token no header:
```
X-Token-Api: YOUR_API_KEY
```
📌 Referência: [Obtendo o Token de API](/guias/passo-a-passo-do-vendedor/1o-preparacao/obtendo-o-token-de-api)
***
#### 2. Criar um Comprador (Buyer) — Obrigatório
O Buyer representa o pagador e é **obrigatório** para pedidos com 3DS.
**Objetivo**
* Identificar corretamente o comprador
* Atender requisitos de antifraude, autenticação e conciliação
**Resultado esperado**
* A API retorna o `uuid` do Buyer
📌 Esse `uuid` será utilizado nas próximas etapas.
📌 Referência: [Criando um Comprador](/guias/pedidos-e-cobrancas/criando-um-comprador)
***
#### 3. Tokenizar o Cartão (Card Token)
O vendedor tokeniza o cartão do comprador de forma segura.
**Pontos importantes**
* Os dados sensíveis do cartão **não devem ser armazenados** por vendedores **não compatíveis com PCI DSS**
* O token retornado substitui os dados reais do cartão
**Resultado esperado**
* Retorno de:
* `uuid` → **Card Token** (usado na transação)
* `cardId` → usado **exclusivamente** para criar a sessão 3DS
📌 Caso `checkZeroDollar = false`, o token pode iniciar como `PENDING`.
📌 Referência: [/pages/lLLeZrln6j9sahQycPri#id-1.-criar-card-token-tokenizacao-de-cartao](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/lLLeZrln6j9sahQycPri#id-1.-criar-card-token-tokenizacao-de-cartao "mention")
***
#### 4. Criar Sessão 3DS
A sessão 3DS inicia o processo de autenticação.
**Objetivo**
* Preparar a comunicação com o provedor 3DS (ex.: Cybersource)
**Resultado esperado**
* Retorno de:
* `id` → será enviado como `setupId` na criação do pedido
* `token` e `collectUrl` → usados na coleta de dados do navegador
📌 Referência: [/pages/lLLeZrln6j9sahQycPri#id-2.-criar-sessao-3ds](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/lLLeZrln6j9sahQycPri#id-2.-criar-sessao-3ds "mention")
***
#### 5. Coletar Dados do Navegador (Browser Data Collection)
Antes de criar o pedido, o vendedor **deve obrigatoriamente** coletar os dados do navegador do comprador.
**Objetivo**
* Enviar informações de background para o emissor
* Permitir decisão de *frictionless flow* ou *challenge*
**Regras**
* A coleta ocorre em background
* O vendedor deve aguardar a finalização da coleta
**Resultado esperado**
* Coleta concluída com sucesso (≈ 1 segundo)
📌 Sem essa etapa, o pedido com 3DS pode falhar.
📌 Referência: [/pages/lLLeZrln6j9sahQycPri#id-3.-coletar-dados-do-navegador-browser-data-collection](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/lLLeZrln6j9sahQycPri#id-3.-coletar-dados-do-navegador-browser-data-collection "mention")
***
#### 6. Criar Pedido com 3DS
Com a coleta concluída, o vendedor cria o pedido informando os dados de 3DS.
**Configurações importantes**
* Informar:
* `setupId` da sessão 3DS
* Dados do navegador
* Endereço de cobrança
* `redirectURL` para retorno pós-autenticação
* O `uuidBuyer` é obrigatório
**O que acontece**
* A Barte envia os dados ao provedor 3DS
* O emissor decide se haverá desafio
**Resultado esperado**
* Pedido criado
* Uma ou mais charges associadas
* Retorno do objeto `threeDSResponse`
📌 Referência: [/pages/lLLeZrln6j9sahQycPri#id-4.-criar-pedido-com-3ds](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/lLLeZrln6j9sahQycPri#id-4.-criar-pedido-com-3ds "mention")
***
### Fluxos Alternativos
#### 7. Desafio 3DS (Step Up Challenge)
O desafio é necessário quando:
```
threeDSResponse.challenged = true
```
**O que acontece**
* O vendedor deve renderizar o iframe de desafio
* O comprador autentica no banco emissor (senha, app, biometria)
**Após o desafio**
* O cliente é redirecionado para o `redirectURL`
* O resultado final **não é garantido imediatamente**
📌 O status definitivo é enviado via **webhook**.
📌 Referência: [/pages/lLLeZrln6j9sahQycPri#id-5.-desafio-3ds-step-up-challenge](https://docs.barte.com/guias/passo-a-passo-do-vendedor/4o-casos-de-uso-fluxo-completo/pedidos/pages/lLLeZrln6j9sahQycPri#id-5.-desafio-3ds-step-up-challenge "mention")
***
### Decisão de Fluxo
| Situação | Comportamento |
| --------------------- | ---------------------------------------- |
| `challenged = false` | Pagamento segue sem interação do cliente |
| `challenged = true` | Exige Step Up Challenge |
| Autenticação aprovada | Charge pode ser `PAID` |
| Autenticação recusada | Charge será `FAILED` |
***
### Pós-condições
Ao final deste caso de uso, o vendedor consegue:
* Autenticar-se na API
* Criar obrigatoriamente um Buyer
* Tokenizar cartões com segurança
* Executar autenticação 3DS completa
* Criar pedidos com ou sem desafio
* Receber o status final via webhook
***
### Observações Importantes
* Buyer é obrigatório
* A coleta de dados do navegador é obrigatória
* O Step Up Challenge depende do emissor
* O status final da transação **sempre deve ser confirmado via webhook**
* 3DS reduz fraude e pode gerar *liability shift*, conforme decisão do emissor
# Links de Pagamento
# Link de Pagamento Pontual
Este caso de uso descreve como um vendedor cria um link de pagamento único (pontual) para cobrança de um valor específico, que pode ser pago uma única vez pelo comprador.
#### Atores
* **Vendedor (Seller)**: Sistema integrador
* **Comprador (Buyer)**: Pessoa que realizará o pagamento
* **Barte API**: Responsável pela criação do link e processamento do pagamento
***
### Pré-condições
* O vendedor possui um **Token de API válido**
* O pagamento será realizado via **Link de Pagamento**
* **O Buyer é opcional neste fluxo**
***
### Fluxo Principal
#### 1. Obter o Token de API
Antes de realizar qualquer chamada, é necessário obter o Token de API.
Todas as requisições devem conter o header:
```
X-Token-Api: YOUR_API_KEY
```
📌 Referência: [Obtendo o Token de API](/guias/passo-a-passo-do-vendedor/1o-preparacao/obtendo-o-token-de-api)
***
#### 2. Criar um Comprador (Buyer) — **Opcional**
O vendedor **pode** criar previamente um Buyer para associá-lo ao link de pagamento.
**Quando usar esta etapa**
* O vendedor já possui os dados do comprador
* Deseja facilitar o checkout
* Precisa de maior controle de conciliação ou antifraude
**Quando não usar**
* O link será enviado de forma aberta (WhatsApp, e-mail, redes sociais)
* O comprador informará seus dados diretamente no checkout
📌 Importante\
Caso o Buyer **não seja criado**, os dados do comprador serão coletados diretamente no checkout do link de pagamento.
📌 Referência: [Criando um Comprador](/guias/pedidos-e-cobrancas/criando-um-comprador)
***
#### 3. Criar o Link de Pagamento
O vendedor cria um link de pagamento pontual.
**O que acontece**
* Um link único é gerado
* O link pode ser compartilhado com o comprador
* Nenhum pagamento ocorre neste momento
📌 Caso um **uuidBuyer** seja informado:
* O checkout pode vir pré-preenchido
* O pagamento será associado diretamente ao Buyer informado
📌 Caso **não** seja informado:
* O comprador deverá preencher seus dados no checkout
📌 Referência: [Link de Pagamento Pontual](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/links-de-pagamento/link-de-pagamento-pontual)
***
#### 4. Pagamento pelo Comprador
O comprador acessa o link de pagamento e realiza o pagamento.
**O que acontece**
* O comprador informa seus dados (caso não existam)
* O pagamento é processado
* Uma **order** e uma ou mais **charges** são criadas
Resultado esperado:
* Pedido criado com sucesso
* Status da charge conforme método de pagamento (PAID, PENDING, FAILED, etc.)
***
### Pós-condições
Ao final deste caso de uso, o vendedor consegue:
* Criar um link de pagamento pontual
* Opcionalmente associar um Buyer
* Permitir que o comprador pague via checkout hospedado
* Acompanhar o status do pedido e da cobrança
* Realizar ações pós-pagamento (estorno, conciliação, suporte)
***
### Observações Importantes
* O **Buyer é opcional** no link de pagamento
* Caso não informado, os dados do comprador serão coletados no checkout
* O link pode ser reutilizado ou expirado conforme configuração
* A cobrança sempre ocorre no nível da **charge**
# Link de Pagamento Recorrente
Este caso de uso descreve como um vendedor cria um **Link de Pagamento Recorrente** para contratação de uma **assinatura**, utilizando um checkout hospedado pela Barte.\
O cliente acessa o link, realiza a contratação e os pagamentos passam a ocorrer de forma recorrente, conforme o plano configurado.
***
### Atores
* **Vendedor (Seller)**: Sistema integrador
* **Comprador (Buyer)**: Cliente final que contratará a assinatura
* **Barte API**: Responsável pelo checkout, criação da assinatura, cobranças recorrentes e notificações
***
### Pré-condições
* O vendedor possui um **Token de API válido**
* 📌 Referência: [Obtendo o Token de API](/guias/passo-a-passo-do-vendedor/1o-preparacao/obtendo-o-token-de-api)
* Um **Plano de Assinatura deve estar previamente criado** (**obrigatório**)
* 📌 Referência: [Criando Plano de Assinatura](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/assinaturas/criando-plano-de-assinatura)
* O vendedor definiu os **métodos de pagamento permitidos** no checkout
* O comprador **não precisa ser criado previamente**
* O Buyer será criado automaticamente durante o checkout, se necessário
***
### Fluxo Principal
#### 1. Autenticação na API
Todas as requisições devem conter o Token de API no header:
```
X-Token-Api: YOUR_API_KEY
```
📌 Referência: [Obtendo o Token de API](/guias/passo-a-passo-do-vendedor/1o-preparacao/obtendo-o-token-de-api)
***
#### 2. Criar um Plano de Assinatura (Obrigatório)
O plano define as regras da cobrança recorrente, como:
* Periodicidade
* Valor
* Ciclo de cobrança
📌 O UUID do plano será utilizado obrigatoriamente na criação do link recorrente.
📌 Referência: [Criando Plano de Assinatura](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/assinaturas/criando-plano-de-assinatura)
***
#### 3. Criar um Link de Pagamento Recorrente
Com o plano criado, o vendedor gera um link de pagamento recorrente.
Configuração importante:
* `type = SUBSCRIPTION`
* `paymentSubscription.idPlan` deve conter o UUID do plano
* Definição dos métodos de pagamento permitidos no checkout
Resultado esperado:
* A API retorna um **link público (url)** de checkout
* O link pode ser compartilhado livremente com o cliente
📌 Referência: [Link de Pagamento Recorrente](/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/links-de-pagamento/link-de-pagamento-recorrente)
***
#### 4. Cliente acessa o Link de Pagamento
Ao acessar o link:
* O cliente preenche seus dados
* Escolhe o método de pagamento disponível
* Confirma a contratação da assinatura
O que acontece:
* Um Buyer pode ser criado automaticamente
* A assinatura é criada conforme o plano
* A primeira cobrança é processada (quando aplicável)
***
### Fluxos Pós-Contratação
Após a criação da assinatura, o ciclo passa a ser gerenciado pela Barte.
#### Atualizações via webhook
Webhooks são enviados sempre que ocorrer:
* Criação da assinatura
* Pagamento confirmado
* Falha de pagamento
* Cancelamento
* Alteração de status
💡 Os webhooks de **Subscriptions** devem ser utilizados como **fonte de verdade** para o estado da assinatura.
***
### Pós-condições
Ao final deste caso de uso, o vendedor consegue:
* Criar um plano de assinatura
* Criar um link de pagamento recorrente
* Permitir que clientes contratem assinaturas via checkout Barte
* Acompanhar o ciclo da assinatura via webhooks
* Controlar cobranças recorrentes sem checkout próprio
***
### Observações Importantes
* O **plano de assinatura é obrigatório**
* O Buyer **não é obrigatório** antes da criação do link
* O link recorrente **não cria regras de cobrança**, apenas referencia um plano
* A confirmação da assinatura **não deve ser feita pelo frontend**
* Webhooks são a fonte de verdade do ciclo da assinatura
# Assinaturas
Criar uma assinatura para um comprador, baseada em um plano previamente existente, permitindo que a Barte gere cobranças recorrentes automaticamente.
#### Atores
* **Vendedor** (Seller)
* **Barte**
* **Buyer** (obrigatório)
***
#### Pré-condições
* O plano deve estar **ativo**
* O **buyer deve existir**
* O método de pagamento deve ser compatível com o plano
* O merchant deve possuir webhook configurado
***
#### Pós-condições
* A assinatura é criada
* Uma cobrança recorrente é gerada automaticamente
* O status da assinatura passa a refletir o estado do pagamento
* Eventos de pagamento são comunicados via webhook
***
#### Fluxo Principal
1. O vendedor solicita a criação de uma assinatura informando:
* Plano
* Buyer
* Método de pagamento
* Data de início
2. A Barte valida:
* Existência e status do plano
* Existência do buyer
* Compatibilidade do método de pagamento
3. A Barte cria a assinatura
4. A Barte gera a primeira cobrança recorrente
5. O pagamento é processado conforme o método escolhido
6. A Barte atualiza o status da cobrança
7. A Barte envia webhook ao vendedor
8. O vendedor confirma o pagamento com base no webhook
***
#### Fluxos Alternativos
**3.a — Plano inativo**
* A Barte recusa a criação da assinatura
**3.b — Buyer inexistente**
* A Barte retorna erro de validação
**5.a — Pagamento assíncrono (PIX / boleto)**
* A cobrança permanece `PENDING`
* O webhook é enviado apenas após confirmação do pagamento
**5.b — Falha no pagamento**
* A cobrança recebe status `FAILED`
* A assinatura pode permanecer `PENDING` ou ser `SUSPENDED`, conforme regra do plano
***
#### Regras de Negócio
* O **buyer é obrigatório** para assinaturas
* A assinatura pode gerar **múltiplas cobranças ao longo do tempo**
* O status da assinatura depende do status das cobranças
* Pagamentos recorrentes **sempre devem ser confirmados via webhook**
* A resposta da API **não confirma pagamento**
* Cobranças possuem status independentes da assinatura
* Assinaturas canceladas não podem ser reutilizadas
***
#### Observações Importantes
* O `uuid` da assinatura deve ser armazenado
* O `uuid` de cada cobrança deve ser armazenado
* Webhooks devem ser tratados de forma idempotente
* A liberação de serviços deve ocorrer **somente após webhook**
# 1º - Preparação
# Obtendo o Token de API
Todos os endpoints da Barte exigem autenticação via **`X-Token-Api`**.\
Esse token é a credencial necessária para que sua aplicação consiga se comunicar com a API de forma segura.
### Passo a passo
1. Acesse o **Painel do Intermediador**.
2. No menu lateral esquerdo clique em **Vendedores**
3. Faça uma busca pelo seu **CNPJ** e depois clique em **Detalhes**
4. Nas abas superiores clique em **Integração**
5. Nessa tela você verá sua chave de API
⚠️ **Atenção:** o token é sensível e deve ser armazenado de forma segura. Evite expô-lo em clientes públicos (como apps front-end).
### Veja como obter o token:
{% embed url="" %}
Lembrando que:
\
Caso o passo a passo apresente erro ou não consiga efetuar a ação, entre em contato com o time de Suporte Barte.
{% endembed %}
# Intermediador de Pagamentos x Vendedor
## Intermediador de pagamentos x Vendedor
Na Barte, trabalhamos com dois papéis principais: **intermediadores** e **vendedores**. Entender essa diferença é fundamental para estruturar corretamente sua integração.
### :handshake: Intermediador de pagamentos
* Utiliza a Barte em **modo white-label**, operando no background.
* Define regras de negócio, taxas e fluxo financeiro.
* Oferece sua própria experiência de checkout e gestão, mas a operação é processada pela Barte.
* Normalmente representa **plataformas, fintechs ou marketplaces** que gerenciam múltiplos vendedores.
### :store: Vendedor
* São as **empresas que realizam vendas** usando a infraestrutura da Barte.
* Podem estar **associados a um intermediador** ou, dependendo do seu potencial, **vinculados diretamente à Barte**.
* Têm sua própria conta, checkout, recebíveis, estornos e relatórios.
* Todas as transações acontecem sempre no contexto de um vendedor.
:grid: Em resumo:
* **Intermediador**: controla e conecta um ecossistema de vendedores.
* **Vendedor**: é a empresa que efetivamente realiza as vendas, podendo estar ligada a um intermediador ou diretamente à Barte.
# Criando um Comprador
Na Barte, todo pedido (**order**) precisa estar associado a um **comprador**.\
Por isso, antes de criar uma order, é necessário registrar o comprador e obter o seu **`uuid`** ou buscar por um comprador já cadastrado para associá-lo ao pedido.
O **comprador** representa a pessoa física ou jurídica que realizará a transação.\
Ele armazena informações como:
* Nome e e-mail
* Documento (CPF/CNPJ)
* Dados de contato
* Endereço
### Criar um comprador (Buyer)
O comprador representa a pessoa que realizará o pagamento.
#### Endpoint
```
POST /v2/buyers
https://api.barte.com/v2/buyers
```
#### Headers
```
X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*
```
#### Body
```json
{
"document": {
"documentNumber": "48637879012",
"documentType": "cpf",
"documentNation": "BR"
},
"name": "John Doe",
"email": "johndoe@barte.com",
"countryCode": "+55",
"phone": "34999991111",
"alternativeEmail": "johndoealt@barte.com",
"address": {
"street": "Rua Orleans",
"number": "100",
"complement": "Bloco A",
"district": "Jardim Europa",
"city": "Uberlândia",
"state": "Minas Gerais",
"country": "BR",
"zipCode": "38414552"
}
}
```
#### Response
```json
{
"uuid": "1ee849a4-6bb3-47f0-b32a-293a8f0e811c",
"document": "48637879012",
"name": "John Doe",
"countryCode": "+55",
"phone": "34999991111",
"email": "johndoe@barte.com",
"alternativeEmail": "johndoe@barte.com"
}
```
> ✅ Guarde o campo **uuid**, ele será utilizado na criação do pedido.
Veja a referencia API do endpoint de criação de buyers clicando no link abaixo para entender sobre todos os campos, retornos de sucesso e erro e demais informações:
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/AWqGHk0JpyBAFok3KhB9" %}
[Criar Comprador](/api-reference/compradores/criar-comprador)
{% endcontent-ref %}
# Como funciona a Pré-Captura
Ao criar um pedido (`order`) é possível decidir se ele será **capturado imediatamente** ou se ficará em **pré-captura**.
* Se no body da requisição ([**criação do pedido**](/api-reference/pedidos-e-cobrancas/criar-pedido)) a propriedade `capture` for **true**, o pedido e a cobrança (`charge`) são capturados na hora.
* Se `capture` for **false**, o pedido e a cobrança ficam no status **PRE\_AUTHORIZED** (pré-autorizados).
*Para entender mais sobre a diferença entre Pedidos (Orders) e Cobranças (Charges), acesse:* [***Pedido (Order) x Cobrança (Charge)***](/guias/pedidos-e-cobrancas/qual-a-diferenca-entre-pedido-order-e-cobranca-charge)
A **pré-captura** garante o limite no cartão do cliente, mas não finaliza a cobrança. Isso dá margem para que o vendedor possa executar validações adicionais (como antifraude, análise interna etc.) antes de concluir a captura.
:triangle-exclamation: Importante:
* O vendedor tem até **6 dias** para capturar a cobrança.
* Se não for capturado dentro desse prazo, o pedido será **cancelado automaticamente** e tanto a `order` quanto a `charge` ficam como **CANCELED**.
Para capturar manualmente, utilize o endpoint:\
`POST /v2/charges/{uuid}/capture`
Veja a referencia completa aqui:
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/Gn6D3jr3kkg2sf7iFDkI" %}
[Capturar Cobrança](/api-reference/pedidos-e-cobrancas/cobrancas/capturar-cobranca)
{% endcontent-ref %}
**Respostas possíveis:**
* **Status PAID + retryable: false** → captura realizada com sucesso.
* **Status PRE\_AUTHORIZED + retryable: true** → captura não concluída, mas pode ser tentada novamente.
# Qual a diferença entre Pedido (Order) e Cobrança (Charge)
**Resumo rápido**
* **Order** = *pedido / intenção de venda*. Representa o contexto comercial: quem compra, o que está sendo comprado, valor total, parcelas, metadata e regras de negócio.
* **Charge** = *ação de cobrança / evento financeiro*. Representa a tentativa/registro de cobrança efetiva (autorização, captura, estorno, etc.). Uma order pode ter 1 ou várias charges associadas.
***
### Conceito detalhado
#### Order (pedido)
* É a entidade de **nível de negócio**.
* Contém informações como `uuid` do comprador (`uuidBuyer`), `value` total, `installments`, `title`, `description`, `metadata` e dados que descrevem a venda.
* A order **não é uma cobrança em si** — é o agrupador/contrato que descreve a transação a ser cobrada.
* A order controla o fluxo: regras de pagamento, parcelamento, soft descriptor, vínculo com split, entre outros.
#### Charge (cobrança)
* É a entidade de **nível financeiro** que representa uma tentativa ou registro de débito contra um meio de pagamento.
* Cada charge tem seu próprio `uuid`, `value` (pode ser parcial ou total), `expirationDate`, `status` e outros campos específicos.
* Operações financeiras (capturar, estornar, cancelar, antecipar, consultar status, reprocessar) são feitas **sobre charges**, não sobre a order.
***
### Quando uma order gera múltiplas charges
* **Parcelamento no tempo (ex.: 3x, 4x sem juros)**
* Quando a order é parcelada em **recorrência**, são criadas **múltiplas charges**, uma por parcela.
* Cada charge representa a cobrança daquele vencimento específico (valor da parcela, data de vencimento, status próprio).
* Isso facilita conciliação, reprocessamento de parcelas individualmente e controle de inadimplência por parcela.
* **Captura única / Antecipação**
* Quando a operação é feita via **antecipação** (ex.: `CREDIT_CARD_EARLY_SELLER ou CREDIT_CARD_EARLY_BUYER`), normalmente **apenas uma charge** é criada para a order (representando o valor total que será antecipado).
* Ou seja: em cenários de antecipação, não se fragmenta em múltiplas charges por parcela — a cobrança é consolidada.
***
### Status e ciclo de vida (visão prática)
* **Order**: tipicamente possui status como `SENT, ABANDONED, PAID, CANCELED, LATE, PARTIALLY_PAID, REFUND, CHARGEBACK e PRE_AUTHORIZED.`
* **Charge**: status financeiro como `PENDING, AUTHORIZED, CAPTURED, CANCELED, REFUNDED, PARTIALLY_REFUNDED, CHARGEBACK, EXPIRED.`
***
### Onde operar cada ação (prática para devs)
* **Criação de pedido** → `POST /v2/orders` (enviar `uuidBuyer`, `value`, `installments`, `payment`, `metadata`, etc.).
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/DqJnW4qScozbkkcrkZGm" %}
[Criar Pedido](/api-reference/pedidos-e-cobrancas/criar-pedido)
{% endcontent-ref %}
* **Consultas de status** → buscar tanto a order quanto as charges associadas; **sempre** verifique o status da charge para decisões financeiras.
* **Captura** → `POST /v2/charges/{uuid}/capture` (opera sobre a charge).
{% content-ref url="/pages/R1U46KfnwpWrFq3H2otk" %}
[Como funciona a Pré-Captura](/guias/pedidos-e-cobrancas/como-funciona-a-pre-captura)
{% endcontent-ref %}
* **Estorno / Refund** → ação sobre a charge (ou sobre transação financeira específica retornada pela charge).
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/VxalW96f6GgvDbw6QQIa" %}
[Estorno](/api-reference/estorno/estorno-cobranca-parcial)
{% endcontent-ref %}
* **Cancelamento** → pode existir endpoint de cancelamento de order e/ou de charge — o cancelamento financeiro efetivo age sobre charges.
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/XxqfoZJFcMVNjF5PhIJD" %}
[Cancelar Cobrança](/api-reference/pedidos-e-cobrancas/cobrancas/cancelar-cobranca)
{% endcontent-ref %}
***
### Boas práticas de implementação
1. **Guarde ambos os IDs**: mantenha `order.uuid` e `charge.uuid` no seu sistema para rastrear contexto de negócio e eventos financeiros separadamente.
2. **Conciliação**: faça reconciliação financeira por **charge** (cada charge é um evento financeiro com status e valores próprios).
3. **Webhooks**: escute eventos de charge e eventos de order quando existirem — atualize seu domínio por charge e, quando apropriado, sincronize o status da order.
4. **Retries**: use o campo `retryable` para decidir se vale a pena re-tentar a captura. Não tente capturar indefinidamente.
5. **Pré-captura**: se adotar pré-captura (`capture: false`), implemente um processo para: (a) rodar verificações antifraude; (b) capturar dentro do prazo (ex.: 6 dias); (c) cancelar e notificar quando não capturado.
6. **Metadados**: utilize `metadata` na order para ligar facilmente a order/charge ao seu ERP, pedido interno ou referência do cliente.
7. **Erros e idempotência**: ao criar orders/charges, use chaves de idempotência para evitar duplicidade em falhas de rede.
***
### Onde aplicar cada entidade na sua arquitetura
* **Order** → camada de aplicação / domínio (o “pedido” que seu negócio precisa rastrear).
* **Charge** → camada de pagamentos / financeira (monitoramento de autorizações, capturas, estornos e repasses).
# Campos dos Webhooks
Especificação dos campos e formatos entregues nos Webhooks da Barte.
# V1 (Deprecado)
Detalhes dos campos enviados nos Webhooks da Barte (formato v1).
{% hint style="danger" %}
**Formato v1 — descontinuação em 10/08/2026.**\
Sellers sem integração ativa devem integrar diretamente pelo [Webhook v2](/guias/webhooks/webhooks-overview/webhook-v2-visao-geral). A partir de **10/08/2026**, o v1 será descontinuado para todos os sellers. **Assinaturas (`SUBSCRIPTION`)** permanecem no formato v1 e não fazem parte desta migração.
{% endhint %}
Os webhooks são enviados sempre que ocorre uma atualização em **pedidos (ORDER)**, **assinaturas (SUBSCRIPTION)** ou **transações físicas/pos (PHYSICAL\_ORDER)**.\
Cada evento contém um conjunto de campos padronizados, que variam conforme o tipo de domínio e o status da transação.
***
### :shield-check: Headers da Requisição
Cada webhook é enviado com os seguintes headers HTTP para garantir autenticidade, unicidade e segurança:
| Header | Tipo | Descrição |
| ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| **X-Webhook-Timestamp** | `integer` | Unix epoch (segundos) no momento do envio. Permite detectar requisições antigas ou repetidas. |
| **X-Webhook-Nonce** | `string` | 32 caracteres hexadecimais (128 bits de aleatoriedade). Garante unicidade por requisição, prevenindo duplicatas. |
| **idempotency-key** | `string` | Chave de idempotência para garantir que requisições repetidas não causem efeitos duplicados. |
| **authorization** | `string` | Token de autenticação para validar a origem da requisição. |
> 💡 **Dica de Segurança:**\
> Recomendamos validar o timestamp para detectar requisições antigas (fora de uma janela de tolerância, ex: 5 minutos) e verificar a unicidade do nonce para evitar processamento duplicado de webhooks.
***
### :octagon-check: Campos Comuns
| Campo | Tipo | Descrição |
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **uuid** | `string` | Identificador único do pedido (`ORDER`), assinatura (`SUBSCRIPTION`) ou cobrança física (`PHYSICAL_ORDER`). |
| **dateTime** | `string` | Data e hora da ocorrência no formato ISO 8601 — `YYYY-MM-DDTHH:MM:SS`. |
| **status** | `string` | Status atual da cobrança ou assinatura. Veja Status possíveis. |
| **domain** | `string` |
Tipo de evento: • ORDER → Cobrança pontual • SUBSCRIPTION → Assinatura recorrente • PHYSICAL\_ORDER → Cobrança de maquininha
|
| **uuidBuyer** | `string` | Identificador único do comprador. Pode ser usado para buscar mais detalhes via API `/v2/buyers/{uuid}`. |
| **documentBuyer** | `string` | CPF ou CNPJ do comprador. |
| **emailBuyer** | `string` | E-mail do comprador. |
| **address** | `object` |
Objeto com os dados de endereço do comprador: country, state, city, district, street, zipCode, number, complement.
|
| **metadata** | `array` | Lista de pares `{ key, value }` contendo informações adicionais enviadas durante a criação da cobrança. |
| **cnpjSeller** | `string` | CNPJ do vendedor responsável pela transação. |
| **idSeller** | `integer` | Identificador interno do vendedor. |
| **authorizationCode** | `string` | Código de autorização da transação (quando aplicável). |
| **authorizationNsu** | `string` | NSU (Número Sequencial Único) da transação (quando aplicável). |
| **cards** | `array` | Lista de cartões associados à cobrança (quando disponível). |
| **refunds** | `array` | Lista de estornos associados à cobrança. |
> 💡 **Dica:**\
> O campo `uuid` pode ser utilizado nas rotas:
>
> * `GET /v2/subscriptions/{uuid}` → Para consultar detalhes e cobranças da assinatura
> * `GET /v2/orders/{uuid}` → Para consultar detalhes e cobranças de uma cobrança pontual
***
### :credit-card: Campos Exclusivos de `PHYSICAL_ORDER`
| Campo | Tipo | Descrição |
| ----------------------- | --------- | ----------------------------------------------- |
| **amount** | `number` | Valor total pago. |
| **installments** | `integer` | Quantidade de parcelas escolhidas. |
| **first4\_digits** | `string` | Primeiros 4 dígitos do cartão. |
| **last4\_digits** | `string` | Últimos 4 dígitos do cartão. |
| **holderName** | `string` | Nome do titular do cartão. |
| **brand** | `string` | Bandeira do cartão (ex: Visa, Elo, Mastercard). |
| **authorization\_code** | `string` | Código de autorização da operadora. |
| **authorization\_nsu** | `string` | NSU (Número Sequencial Único) da transação. |
| **pos\_id** | `string` | Identificador do terminal (POS). |
| **cnpj** | `string` | CNPJ da empresa portadora da maquininha. |
| **company\_name** | `string` | Nome da empresa portadora da maquininha. |
| **serial\_number** | `string` | Número de série do terminal POS. |
| **payment\_type** | `string` | Tipo de pagamento (ex: `credit`, `debit`). |
| **rate** | `number` | Taxa aplicada à transação. |
***
### :puzzle-piece: Status Possíveis
#### 🔸 Pedidos (`ORDER/PHYSICAL_ORDER`)
| Status | Descrição |
| ------------------- | -------------------------------------------------- |
| **SENT** | Pedido criado. |
| **PAID** | Pagamento confirmado. |
| **PARTIALLY\_PAID** | Pagamento parcial recebido. |
| **LATE** | Pagamento atrasado. |
| **ABANDONED** | Pedido abandonado (ex: atraso superior a 90 dias). |
| **CANCELED** | Pedido cancelado. |
| **REFUND** | Pedido estornado. |
| **CHARGEBACK** | Pedido com chargeback. |
| **PRE\_AUTHORIZED** | Pedido pré-autorizado. |
| **DISPUTE** | Pedido entrou em disputa. |
| **DISPUTE\_ALERT** | Alerta de disputa recebido. |
***
#### 🔹 Assinaturas (`SUBSCRIPTION`)
| Status | Descrição |
| ------------- | ------------------------------------------------------- |
| **PENDING** | Assinatura criada, aguardando confirmação de pagamento. |
| **ACTIVE** | Assinatura ativa. |
| **DEFAULTER** | Assinatura inadimplente. |
| **INACTIVE** | Assinatura encerrada. |
***
O campo `address` está presente em todos os domínios (`ORDER`, `SUBSCRIPTION`, `PHYSICAL_ORDER`) e segue o formato abaixo:
```json
"address": {
"country": "BR",
"state": "SP",
"city": "São Paulo",
"district": "Pinheiros",
"street": "Rua dos Pinheiros",
"zipCode": "05422-001",
"number": "850",
"complement": "Sala 12"
}
```
# V2 — Novo Padrão
Entenda o novo formato de envelope versionado do Webhook v2 da Barte.
{% hint style="info" %}
**Sellers sem integração ativa:** devem integrar diretamente pelo Webhook v2 — o v1 não é mais aceito para novas integrações.\
**A partir de 10/08/2026:** o formato v1 será descontinuado para todos os sellers. Todos deverão estar no v2.
{% endhint %}
{% hint style="warning" %}
**Prazo de entrega:** o endpoint receptor deve responder em até **20 segundos**. Requisições que ultrapassem esse tempo serão consideradas falhas e poderão ser reenviadas.
{% endhint %}
***
## O que mudou?
A versão 1 do webhook entregava um payload **plano**, com todos os campos no nível raiz do objeto. A versão 2 introduz um **envelope de evento versionado**, que organiza os dados em uma estrutura hierárquica com identificação explícita do tipo de evento.
| Característica | v1 (legado) | v2 (novo padrão) |
| --------------------------- | --------------------------- | ----------------------------------------------- |
| **Estrutura** | Payload plano | Envelope com `eventData` aninhado |
| **Identificação do evento** | Campo `status` | Campo `eventType` (ex: `order.paid`) |
| **Dados da cobrança** | Misturados no raiz | Isolados em `eventData.charge` |
| **Dados do comprador** | Campos planos | Objeto `buyer` em `eventData` |
| **Dados físicos (POS/TEF)** | Campos planos | Objeto `physicalTransactionData` em `eventData` |
| **Identificador de evento** | Não existe | Campo `eventId` único por evento |
| **Quem recebe** | Sellers existentes (legado) | Sellers sem integração ativa / migrados |
***
## Quem recebe o Webhook v2?
* **Sellers sem integração ativa:** devem integrar diretamente no v2. O v1 não é aceito para novas integrações.
* **Sellers com integração existente em v1:** devem migrar para v2 até **10/08/2026**, quando o formato v1 será descontinuado.
* **Assinaturas (`SUBSCRIPTION`):** permanecem no formato v1 e não fazem parte desta migração.
***
## Comportamento de transações físicas (POS/TEF)
Diferente de cobranças digitais, **transações físicas nunca geram o evento `order.sent`**. O primeiro evento recebido para uma transação de maquininha sempre será um status final:
| Primeiro evento possível | Descrição |
| ------------------------ | -------------------------------------------- |
| `order.paid` | Transação aprovada na maquininha. |
| `order.canceled` | Transação recusada ou cancelada no terminal. |
| `order.pre_authorized` | Transação pré-autorizada no terminal. |
{% hint style="info" %}
Isso ocorre porque a transação física é processada de forma síncrona no terminal — quando o webhook é emitido, o resultado já é definitivo.
{% endhint %}
***
## Headers da requisição
| Header | Tipo | Descrição |
| ----------------------- | --------- | -------------------------------------------------------------- |
| **X-Webhook-Timestamp** | `integer` | Unix epoch (segundos) no momento do envio. |
| **X-Webhook-Nonce** | `string` | 32 caracteres hexadecimais — garante unicidade por requisição. |
| **idempotency-key** | `string` | Chave de idempotência. |
| **authorization** | `string` | Token de autenticação. |
> 💡 **Dica de Segurança:** Valide o `X-Webhook-Timestamp` (tolerância de até 5 minutos) e verifique a unicidade do `X-Webhook-Nonce` para evitar processamento duplicado.
***
## Estrutura do envelope v2
```json
{
"version": "2.0",
"domain": "ORDER",
"eventType": "order.paid",
"eventId": "evt_abc123",
"eventDatetime": "2026-01-30T10:30:00Z",
"sellerId": 123,
"metadata": [],
"eventData": { ... }
}
```
### Campos do envelope
| Campo | Tipo | Descrição |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------ |
| **version** | `string` | Versão do formato do webhook. Valor: `"2.0"`. |
| **domain** | `string` | Tipo de evento: `ORDER` para cobranças pontuais. |
| **eventType** | `string` | Tipo do evento ocorrido. Ver [Tipos de evento](#tipos-de-evento-eventtype) abaixo. |
| **eventId** | `string` | Identificador único do **evento** (distinto do UUID do pedido). |
| **eventDatetime** | `string` | Data e hora do evento no formato ISO 8601. |
| **sellerId** | `integer` | Identificador interno do vendedor. |
| **metadata** | `array` | Lista de pares `{ key, value }` com informações adicionais. |
| **eventData** | `object` | Dados completos do pedido e da cobrança. Ver [Campos do eventData](#campos-do-eventdata) abaixo. |
{% hint style="warning" %}
O campo `version` indica o formato de entrega. Sempre valide esse campo para garantir compatibilidade com a versão integrada.
{% endhint %}
***
## Tipos de evento (`eventType`)
O campo `eventType` identifica o evento ocorrido e corresponde diretamente ao status do pedido:
| eventType | Descrição |
| ---------------------- | ---------------------------------------------- |
| `order.sent` | Pedido criado. |
| `order.paid` | Pagamento confirmado. |
| `order.partially_paid` | Pagamento parcial recebido. |
| `order.late` | Pagamento em atraso. |
| `order.abandoned` | Pedido abandonado (atraso superior a 90 dias). |
| `order.canceled` | Pedido cancelado. |
| `order.refund` | Pedido estornado. |
| `order.chargeback` | Pedido com chargeback. |
| `order.pre_authorized` | Pedido pré-autorizado. |
| `order.invalid` | Pedido inválido. |
***
## Campos do `eventData`
O objeto `eventData` concentra todos os dados do pedido e da cobrança associada.
### Campos do pedido
| Campo | Tipo | Descrição |
| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id** | `string` | Identificador único do pedido. Use com `GET /v2/orders/{uuid}`. |
| **status** | `string` | Status atual do pedido. Espelha o `eventType` em formato legado. |
| **amount** | `number` | Valor total da transação (com decimal, ex: `150.00`). |
| **paymentMethod** | `string` | Método de pagamento utilizado (ex: `CREDIT_CARD_EARLY_SELLER`, `PIX`, `BOLETO`). |
| **description** | `string` | Descrição informada na criação do pedido. |
| **charge** | `object` | Dados da cobrança associada. Ver [Campos da cobrança](#campos-da-cobrança-charge) abaixo. |
| **physicalTransactionData** | `object` | Dados do terminal físico. `null` em transações online. Ver [Campos de transação física](#campos-de-transação-física-physicaltransactiondata) abaixo. |
| **refunds** | `array` | Lista de estornos. Ver [Estrutura de refunds](#estrutura-de-refunds) abaixo. |
| **buyer** | `object` | Dados do comprador. Ver [Campos do comprador](#campos-do-comprador-buyer) abaixo. |
### Campos da cobrança (`charge`)
| Campo | Tipo | Descrição |
| ----------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id** | `string` | UUID da cobrança. |
| **originRequest** | `string` | Origem da transação: `API`, `POS`, `TEF`, entre outros. |
| **authorizationCode** | `string` | Código de autorização da transação. |
| **authorizationNsu** | `string` | NSU (Número Sequencial Único) da transação. |
| **acquirerAuthorizationCode** | `string` | Código de autorização da adquirente. |
| **acquirerAuthorizationNsu** | `string` | NSU da adquirente. |
| **paidDate** | `string` | Data de pagamento no formato `YYYY-MM-DD`. |
| **cardId** | `string` | Em transações online: ID do cartão gerado para a transação. Em transações físicas (POS/TEF): BIN do cartão utilizado. |
| **brand** | `string` | Bandeira do cartão (ex: `VISA`, `MASTERCARD`, `ELO`). |
| **fees** | `array` | Lista de taxas cobradas. `null` se o evento for `order.sent` ou sem charge associada; `[]` se não há taxas registradas. Ver [Estrutura de fees](#estrutura-de-fees) abaixo. |
| **installments** | `integer` | Número de parcelas. |
### Campos de transação física (`physicalTransactionData`)
Presentes apenas quando `originRequest` for `POS` ou `TEF`. Caso contrário, o objeto é `null`.
| Campo | Tipo | Descrição |
| ------------------------- | -------- | ----------------------------------------------- |
| **providerTransactionId** | `string` | ID gerado na transação física (correlation ID). |
| **terminalId** | `string` | Identificador do terminal POS. |
| **serialNumber** | `string` | Número de série do terminal POS. |
### Campos do comprador (`buyer`)
| Campo | Tipo | Descrição |
| ----------------- | -------- | -------------------------------------------------------------------------------- |
| **uuid** | `string` | Identificador único do comprador. Use com `GET /v2/buyers/{uuid}`. |
| **documentBuyer** | `string` | CPF ou CNPJ do comprador. |
| **email** | `string` | E-mail do comprador. |
| **address** | `object` | Endereço do comprador. Ver [Estrutura de address](#estrutura-de-address) abaixo. |
***
## Estrutura de `refunds`
```json
"refunds": [
{
"chargeCode": "CHG-001",
"amount": 150.00,
"status": "SUCCESS",
"createdAt": "2026-01-30",
"errorReason": null
}
]
```
| Campo | Tipo | Descrição |
| --------------- | -------- | -------------------------------------------------- |
| **chargeCode** | `string` | Código da cobrança estornada. |
| **amount** | `number` | Valor estornado. |
| **status** | `string` | Status do estorno (`SUCCESS`, `PENDING`, `ERROR`). |
| **createdAt** | `string` | Data de criação do estorno (`YYYY-MM-DD`). |
| **errorReason** | `string` | Motivo do erro, quando aplicável. |
***
## Estrutura de `fees`
```json
"fees": [
{
"name": "Credit card",
"amount": 3.49
}
]
```
| Campo | Tipo | Descrição |
| ---------- | -------- | ------------------------------------------- |
| **name** | `string` | Tipo da taxa. Ver valores possíveis abaixo. |
| **amount** | `number` | Valor da taxa em reais. |
**Valores possíveis para `name`:**
| Valor | Descrição |
| ---------------------- | --------------------------------------------------------------- |
| `Bankslip` | Taxa sobre transação de boleto bancário. |
| `Credit card` | Taxa sobre transação de cartão de crédito. |
| `Debit card` | Taxa sobre transação de cartão de débito. |
| `PIX` | Taxa sobre transação via PIX. |
| `Reversal` | Taxa cobrada sobre estornos. |
| `Antifraud` | Taxa de antifraude. |
| `Gateway` | Taxa de gateway (pode ser débito ou crédito). |
| `Barte` | Taxa da plataforma Barte (pode ser débito ou crédito). |
| `Reversal Barte` | Estorno de taxa da plataforma Barte. |
| `Revenue Anticipation` | Imposto incidente sobre antecipação de recebíveis. |
| `Anticipation` | Taxa de antecipação de recebíveis (pode ser débito ou crédito). |
| `Partner` | Taxa cobrada pelo parceiro integrador. |
| `POS Rental` | Taxa de aluguel de terminal POS. |
***
## Estrutura de `address`
```json
"address": {
"country": "BR",
"state": "SP",
"city": "São Paulo",
"district": "Pinheiros",
"street": "Rua dos Pinheiros",
"zipCode": "05422-001",
"number": "850",
"complement": "Sala 12"
}
```
***
## Exemplos de payload
### `order.paid` — via API
```json
{
"version": "2.0",
"domain": "ORDER",
"eventType": "order.paid",
"eventId": "evt_abc123",
"eventDatetime": "2026-01-30T10:30:00Z",
"sellerId": 123,
"metadata": [
{ "key": "pedido_interno", "value": "PED-9981" }
],
"eventData": {
"id": "5503ad3a-d9c4-4072-a7cb-12cf2dd0eaa7",
"status": "PAID",
"amount": 150.00,
"paymentMethod": "CREDIT_CARD_EARLY_SELLER",
"description": "Compra de produto X",
"charge": {
"id": "c1f2e3d4-5678-9abc-def0-1234567890ab",
"originRequest": "API",
"authorizationCode": "496847",
"authorizationNsu": "155224",
"acquirerAuthorizationCode": "",
"acquirerAuthorizationNsu": "",
"paidDate": "2026-01-30",
"cardId": "card_789",
"brand": "VISA",
"fees": [
{ "name": "Credit card", "amount": 16.21 },
{ "name": "Antifraud", "amount": 0.50 }
],
"installments": 1
},
"physicalTransactionData": null,
"refunds": [],
"buyer": {
"uuid": "33236116-743a-4c1c-afc4-79b8d5dbb5b5",
"documentBuyer": "12345678900",
"email": "cliente@example.com",
"address": {
"country": "BR",
"state": "SP",
"city": "São Paulo",
"district": "Pinheiros",
"street": "Rua dos Pinheiros",
"zipCode": "05422-001",
"number": "850",
"complement": "Sala 12"
}
}
}
}
```
***
### `order.paid` — via POS/maquininha
```json
{
"version": "2.0",
"domain": "ORDER",
"eventType": "order.paid",
"eventId": "c542447a-4918-4225-aab8-3e374ca927ef",
"eventDatetime": "2026-07-07T13:40:00.656126122Z",
"sellerId": 4924,
"metadata": null,
"eventData": {
"id": "b513157e-0f23-410c-9f98-ee0c0b11a628",
"status": "PAID",
"amount": 25.00,
"paymentMethod": "CREDIT_CARD",
"description": "Pagamento referente à transação realizada em ponto de venda físico.",
"charge": {
"id": "020207c2-247d-487a-a1b2-2a2cd618c357",
"originRequest": "POS",
"authorizationCode": "627632",
"authorizationNsu": "237645",
"acquirerAuthorizationCode": "282240",
"acquirerAuthorizationNsu": "000282240",
"paidDate": "2026-07-07",
"cardId": "554529******6673",
"brand": "mastercard",
"fees": [
{ "name": "Credit card", "amount": 1.07 }
],
"installments": 1
},
"physicalTransactionData": {
"providerTransactionId": "00902339-2439-3159-815b-6f1eda2e1dec",
"terminalId": "00000112",
"serialNumber": "PB1S248S76065"
},
"refunds": [],
"buyer": {
"uuid": "32110b1a-388d-4568-be9a-0892df055487",
"documentBuyer": "44522660000108",
"email": "teste@barte.com",
"address": {
"country": "BR",
"state": "SP",
"city": "São Paulo",
"district": "BELA VISTA",
"street": "PAULISTA",
"zipCode": "01310200",
"number": "1636",
"complement": "SALA 1504"
}
}
}
}
```
***
### `order.refund`
```json
{
"version": "2.0",
"domain": "ORDER",
"eventType": "order.refund",
"eventId": "evt_refund_001",
"eventDatetime": "2026-02-05T14:20:00Z",
"sellerId": 123,
"metadata": [],
"eventData": {
"id": "5503ad3a-d9c4-4072-a7cb-12cf2dd0eaa7",
"status": "REFUND",
"amount": 150.00,
"paymentMethod": "CREDIT_CARD_EARLY_SELLER",
"description": "Compra de produto X",
"charge": {
"id": "c1f2e3d4-5678-9abc-def0-1234567890ab",
"originRequest": "API",
"authorizationCode": "496847",
"authorizationNsu": "155224",
"acquirerAuthorizationCode": "",
"acquirerAuthorizationNsu": "",
"paidDate": "2026-01-30",
"cardId": "card_789",
"brand": "VISA",
"fees": [
{ "name": "Credit card", "amount": 16.21 },
{ "name": "Antifraud", "amount": 0.50 }
],
"installments": 1
},
"physicalTransactionData": null,
"refunds": [
{
"chargeCode": "CHG-001",
"amount": 150.00,
"status": "SUCCESS",
"createdAt": "2026-02-05",
"errorReason": null
}
],
"buyer": {
"uuid": "33236116-743a-4c1c-afc4-79b8d5dbb5b5",
"documentBuyer": "12345678900",
"email": "cliente@example.com",
"address": {
"country": "BR",
"state": "SP",
"city": "São Paulo",
"district": "Pinheiros",
"street": "Rua dos Pinheiros",
"zipCode": "05422-001",
"number": "850",
"complement": "Sala 12"
}
}
}
}
```
***
:tickets: Em caso de dúvidas, entre em contato com o nosso time através do suporte disponibilizado.
# Pedidos (Orders) e Assinaturas (Subscriptions)
Nesta página, você encontrará informações sobre os Webhooks de pedidos (orders) e assinaturas (subscriptions).
{% hint style="danger" %}
**Webhook de `ORDER` — formato v1 em descontinuação.**\
A partir de **10/08/2026**, o formato v1 será descontinuado. Todos os sellers deverão estar integrados ao [Webhook v2](/guias/webhooks/webhooks-overview/webhook-v2-visao-geral). Sellers que ainda não possuem integração ativa devem integrar diretamente pelo novo modelo.
**Webhook de `SUBSCRIPTION`** — o formato atual permanece inalterado e não será migrado para v2 neste momento.
{% endhint %}
***
Os webhooks de **Orders** (pedidos) e **Subscriptions** (assinaturas) compartilham **o mesmo formato de payload**.\
A única diferença entre eles está no valor do campo `domain` e nos **status possíveis** para cada tipo.
###
### :arrow-right-arrow-left: Diferenças principais
| Campo | ORDER | SUBSCRIPTION |
| -------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **domain** | `ORDER` | `SUBSCRIPTION` |
| **tipo de operação** | Pedido único | Cobrança recorrente |
| **status possíveis** | `SENT`, `ABANDONED`, `PAID`, `CANCELED`, `LATE`, `PARTIALLY_PAID`, `REFUND`, `CHARGEBACK`, `PRE_AUTHORIZED` | `PENDING`, `ACTIVE`, `DEFAULTER`, `INACTIVE` |
| **payload** | Mesmo formato JSON | Mesmo formato JSON |
***
### :right: Status válidos
#### **Pedidos (`ORDER`)**
* SENT
* PRE\_AUTHORIZED
* PARTIALLY\_PAID
* PAID
* CANCELED
* REFUND
* LATE
* CHARGEBACK
* ABANDONED
> 🔸 Pedidos com status `LATE` há mais de **90 dias** são automaticamente marcados como `ABANDONED`.
#### **Assinaturas (`SUBSCRIPTION`)**
* PENDING
* ACTIVE
* DEFAULTER
* INACTIVE
***
### :gear-code: Estrutura do Payload (único)
A estrutura abaixo é **idêntica** para ambos os domínios (`ORDER` e `SUBSCRIPTION`).
```json
{
"uuid": "5503ad3a-d9c4-4072-a7cb-12cf2dd0eaa7",
"dateTime": "2025-10-21T14:04:05.930643751",
"status": "SENT",
"domain": "ORDER",
"uuidBuyer": "33236116-743a-4c1c-afc4-79b8d5dbb5b5",
"documentBuyer": "518287216",
"address": {
"country": "AU",
"state": "TAS",
"city": "",
"district": "",
"street": "balers way sunset beach",
"zipCode": "7330",
"number": "17",
"complement": ""
},
"emailBuyer": "cliente@example.com",
"metadata": null,
"cnpjSeller": "56210126000145",
"idSeller": 4922,
"authorizationCode": "496847",
"authorizationNsu": "155224",
"cards": [],
"refunds": []
}
```
### :memo: Exemplo de Refunds
Quando houver estorno, o campo `refunds` será preenchido conforme o exemplo abaixo:
```json
"refunds": [
{
"date": "2025-04-04",
"amount": 121.12,
"status": "SUCCESS"
}
]
```
:tickets: Em caso de dúvidas, entre em contato com o nosso time através do suporte disponibilizado.
# Pedidos Físicos (Maquininhas)
Nesta página, você encontrará informações sobre os Webhooks de pedidos físicos/maquininhas (PHYSICAL\_ORDER).
{% hint style="danger" %}
**Formato v1 em descontinuação.**\
A partir de **10/08/2026**, o formato v1 será descontinuado. Todos os sellers deverão estar integrados ao [Webhook v2](/guias/webhooks/webhooks-overview/webhook-v2-visao-geral). Sellers que ainda não possuem integração ativa devem integrar diretamente pelo novo modelo.
{% endhint %}
***
O domínio **`PHYSICAL_ORDER`** representa **transações realizadas via maquininha (POS).**\
Ele **segue exatamente a mesma estrutura de payload de `ORDER`**, incluindo campos, formato e comportamento —\
diferindo apenas por trazer **informações adicionais do terminal físico**.
***
### :arrow-right-arrow-left: Diferenças principais
| Campo | ORDER | PHYSICAL\_ORDER |
| -------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **domain** | `ORDER` | `PHYSICAL_ORDER` |
| **origem** | Cobrança online | Venda física via maquininha |
| **status possíveis** | `SENT`, `ABANDONED`, `PAID`, `CANCELED`, `LATE`, `PARTIALLY_PAID`, `REFUND`, `CHARGEBACK`, `PRE_AUTHORIZED` | `SENT`, `ABANDONED`, `PAID`, `CANCELED`, `LATE`, `PARTIALLY_PAID`, `REFUND`, `CHARGEBACK`, `PRE_AUTHORIZED` |
| **campos extras** | — | `serial_number`, `pos_id`, `brand`, `holderName`, `first4_digits`, `last4_digits`, `rate`, `payment_type`, `installments` |
***
### :right: Status válidos
#### **Physical Orders (`PHYSICAL_ORDER`)**
* SENT
* PRE\_AUTHORIZED
* PARTIALLY\_PAID
* PAID
* CANCELED
* REFUND
* LATE
* CHARGEBACK
* ABANDONED
> 🔸 Pedidos com status `LATE` há mais de **90 dias** são automaticamente marcados como `ABANDONED`.
***
### :gear-code: Estrutura do Payload
Abaixo está um exemplo de payload enviando no Webhook de maquininhas.
```json
{
"uuid": "c21d64be-5bae-476e-b8d4-9dc373c5afaf",
"dateTime": "2025-10-21T16:40:55.000Z",
"status": "PAID",
"domain": "PHYSICAL_ORDER",
"amount": "1397.20",
"installments": "12",
"first4_digits": "6550",
"last4_digits": "2921",
"holderName": "AGUIAR/HILDA B",
"brand": "ELO CREDITO",
"authorization_code": "107734",
"authorization_nsu": "311000210",
"pos_id": "00000393",
"cnpj": "31228966000104",
"company_name": "Carla Marieli Delmiro Capeli Ltda",
"idSeller": 14161,
"serial_number": "PB1S24C176607",
"payment_type": "credit",
"rate": 9.9
}
```
***
### :credit-card: Campos específicos de POS
| Campo | Descrição |
| -------------------------------------- | ----------------------------------------------------- |
| **serial\_number** | Número de série da maquininha utilizada na transação. |
| **pos\_id** | Identificador do terminal POS. |
| **brand** | Bandeira e modalidade (ex.: `ELO CREDITO`). |
| **holderName** | Nome impresso no cartão do portador. |
| **first4\_digits** / **last4\_digits** | Dígitos iniciais e finais do cartão utilizado. |
| **installments** | Número de parcelas da compra. |
| **payment\_type** | Tipo de pagamento (`credit`, `debit`, etc.). |
| **rate** | Percentual de taxa aplicada na operação. |
:tickets: Em caso de dúvidas, entre em contato com o nosso time através do suporte disponibilizado.
# Disputas e Chargebacks
{% hint style="danger" %}
**Formato v1 em descontinuação.**\
A partir de **10/08/2026**, o formato v1 será descontinuado. Todos os sellers deverão estar integrados ao [Webhook v2](/guias/webhooks/webhooks-overview/webhook-v2-visao-geral). Sellers que ainda não possuem integração ativa devem integrar diretamente pelo novo modelo.
{% endhint %}
Os eventos de **disputa e chargeback** notificam que um comprador contestou ou solicitou estorno de uma cobrança.
* **Disputas (`DISPUTE`)**: indicam que um cliente abriu contestação em uma transação.
* **Alerta de disputa (`DISPUTE_ALERT`)**: notifica que uma disputa foi iniciada, mas ainda não há resolução final.
* **Chargebacks**: seguem o mesmo payload de **ORDER**, pois o status `CHARGEBACK` é enviado via webhook de Orders.
> 🔹 Todos os eventos trazem dados do comprador e do seller, permitindo rastrear e reagir rapidamente.
***
### :gear-code: Payload — Disputa
```json
{
"uuid": "c5a7f2b1-3a91-4a93-8e11-8b4e7f7a61d2",
"dateTime": "2025-10-10T14:32:18.00",
"status": "DISPUTE",
"domain": "ORDER",
"uuidBuyer": "a9fbc3e8-21e4-4f12-8f6b-74a9b37e8b6a",
"documentBuyer": "12345678909",
"address": {
"country": "BR",
"state": "SP",
"city": "São Paulo",
"district": "Pinheiros",
"street": "Rua dos Pinheiros",
"zipCode": "05422-001",
"number": "850",
"complement": "Sala 12"
},
"emailBuyer": "cliente.exemplo@email.com",
"cnpjSeller": "27865738000105",
"idSeller": 16199,
"metadata": [
{
"key": "",
"value": ""
}
]
}
```
🔹 O **domain** ainda é `ORDER`, pois disputas e chargebacks estão ligados à transação original.
###
### :gear-code: Payload — Dispute Alert
```json
{
"uuid": "12dfdf90-8742-479d-b36b-8016faa877a9",
"dateTime": "2025-10-22T02:29:17.437Z",
"status": "DISPUTE_ALERT",
"domain": "ORDER",
"uuidBuyer": "a8d3a8a3-db99-4558-a0e4-a0dae69be4b4",
"documentBuyer": "25307027800",
"country": "BR",
"state": "SP",
"city": "Cotia",
"district": "Parque Dom Henrique",
"street": "Avenida Benedito Isaac Pires",
"zipCode": "06716-300",
"number": "2100",
"complement": "Casa 03",
"emailBuyer": "andremaria1980@gmail.com",
"cnpjSeller": "17830029000101",
"idSeller":622
}
```
> 🔹 Alertas de disputa podem ser usados para **monitorar e acionar fluxos internos** antes da disputa ser oficialmente registrada.
***
### :arrows-rotate-reverse: Fluxo de Disputa → Chargeback
1. A transação é criada com status **PAID**.
2. O comprador abre uma disputa → status muda para **DISPUTE**.
3. Após \~1 semana, se não houver resolução, o sistema altera para **CHARGEBACK**.
4. Se a disputa for ganha, o status retorna para **PAID**.
5. Caso seja perdida, permanece **CHARGEBACK**.
> Esse fluxo segue o comportamento padrão das bandeiras e instituições financeiras.
### :puzzle-piece: Campos importantes
| Campo | Descrição |
| --------------- | ------------------------------------------- |
| `uuid` | Identificador da transação/ordem contestada |
| `dateTime` | Data e hora do evento |
| `status` | `DISPUTE` ou `DISPUTE_ALERT` |
| `domain` | Sempre `ORDER` |
| `uuidBuyer` | Identificador do comprador |
| `documentBuyer` | CPF ou CNPJ do comprador |
| `address` | Endereço completo do comprador |
| `emailBuyer` | E-mail do comprador |
| `cnpjSeller` | CNPJ do seller responsável |
| `idSeller` | ID do seller |
| `metadata` | Dados adicionais opcionais |
***
#### :light-emergency-on: Observações importantes
* Nem toda disputa se transforma em chargeback, mas **a maioria das disputas evolui automaticamente** para `CHARGEBACK` após uma semana.
* Se a disputa for ganha, o status é revertido para `PAID`.
* O webhook de `DISPUTE` é enviado assim que o status é atualizado pela adquirente.
# Autenticação
A autenticação na nossa API é realizada por meio de uma **chave de acesso (X-Token-Api)**. É com ela que conseguimos identificar sua conta e autorizar as operações realizadas em seu nome.
Se a chave informada for inválida, estiver ausente ou enviada em um header incorreto, a API retornará o status **HTTP 401 (não autorizado)**.
A proteção dessa chave é de total responsabilidade do cliente. Para aumentar a segurança, recomendamos a utilização de camadas adicionais, como a restrição de acesso por endereços IP confiáveis.
{% hint style="warning" %}
⚠️ **Importante:**
\
Depois de gerar sua chave de API na plataforma, evite compartilhá-la em e-mails, mensagens ou qualquer outro canal.\
Nunca insira a chave diretamente no código-fonte de seus sistemas nem a exponha em atendimentos, no front-end da aplicação ou em registros de log.
Você poderá resgatar essa chave novamente a qualquer momento dentro do portal.
{% endhint %}
## Cabeçalhos nas requisições
Toda requisição deve conter o seguinte cabeçalho para autenticação:
```css
"Content-Type": "application/json",
"X-Token-Api": "sua_api_key"
```
### Ambientes de Sandbox e Produção
As chaves de API dos ambientes de Sandbox e Produção são distintas, então lembre-se de atualizar a chave corretamente de acordo com o ambiente utilizado.
### Veja no link abaixo como obter seu Token de API:
{% content-ref url="/pages/Qs9PsdIK0uPEuSQMlQ3j" %}
[Obtendo o Token de API](/guias/passo-a-passo-do-vendedor/1o-preparacao/obtendo-o-token-de-api)
{% endcontent-ref %}
### URLs de Sandbox e Produção
Ambiente
URL
Produção
https://api.barte.com
Sandbox
https://sandbox-api.barte.com
###
### Protocolo de segurança TLS (Transport Layer Security)
Atualmente, nosso sistema está configurado para receber comunicações TLS 1.2+.
### Erro de autenticação
O status **401 Unauthorized** significa que a requisição não foi autenticada com sucesso. Para facilitar a identificação da causa, a API retorna no corpo da resposta uma mensagem de erro descritiva, indicando o motivo específico em cada situação.
```css
{
"errors": [
{
"code": "BAR-3005",
"title": "Token inativo ou inexistente.",
"description": "Verifique se informou o x-token-api corretamente."
}
]
}
```
# Alterações nos Endpoints de Sellers – Sandbox e Produção
As alterações nos endpoints de **Sellers** da API já estão em vigor no ambiente de **Sandbox** e **Produção**.
***
### Resumo das Alterações
As principais mudanças envolvem:
* Inclusão do objeto **`webhooks`** nas responses de `POST`, `GET` e `PATCH`
* Atualização do `PATCH /v2/seller` para permitir:
* Atualização de **account** (já existia)
* Criação e atualização de **webhooks**
* Depreciação do campo **`webhook`** (mantido temporariamente por compatibilidade)
* Novas regras de validação para o `PATCH`
A request do `POST` **não sofreu alterações**.
***
## POST `/v2/seller`
### Request (sem alterações)
A estrutura da requisição permanece a mesma.
```
POST /v2/seller HTTP/1.1
Host: api.barte.com
X-Token-Api: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
```
*(Body permanece inalterado conforme documentação anterior.)*
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/nO7uQGIG08MTcKPkqkbL" %}
[Criar Vendedor](/api-reference/intermediador-de-pagamentos/gerencie-seus-vendedores/criar-vendedor)
{% endcontent-ref %}
***
### Alteração na Response
#### Response Anterior
```
{
"document": "87654321000198",
"idSeller": 28451,
"companyName": "TECHNOLOGY SOLUTIONS BRASIL LTDA",
"email": "suporte@technologysolutions.com.br",
"webhook": "https://api.technologysolutions.com.br/webhook",
"x-token-api": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```
***
#### Nova Response
Agora a API retorna também o array `webhooks`:
```
{
"document": "87654321000198",
"idSeller": 28451,
"companyName": "TECHNOLOGY SOLUTIONS BRASIL LTDA",
"email": "suporte@technologysolutions.com.br",
"webhook": "https://api.technologysolutions.com.br/webhook",
"webhooks": [
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"title": "Webhook",
"domains": ["ORDER", "SUBSCRIPTION"],
"active": true,
"url": "https://api.technologysolutions.com.br/webhook"
}
],
"x-token-api": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```
***
### Depreciação do campo `webhook`
O campo:
```
"webhook": "https://api.technologysolutions.com.br/webhook"
```
* Continua sendo retornado temporariamente no `POST` e no `GET`
* Está oficialmente **depreciado**
* Foi mantido para **não quebrar integrações existentes**
* Pode ser removido em versões futuras da API
#### Recomendação
Novas integrações devem utilizar exclusivamente o array `webhooks`.
***
### Estrutura do novo campo `webhooks`
| Campo | Tipo | Descrição |
| ------- | ------- | -------------------------------------------- |
| uuid | string | Identificador único do webhook |
| title | string | Nome do webhook |
| domains | array | Eventos vinculados (`ORDER`, `SUBSCRIPTION`) |
| active | boolean | Indica se o webhook está ativo |
| url | string | URL configurada para recebimento |
***
## GET `/v2/seller`
### Alteração na Response
#### Response Anterior
Retornava apenas os dados do seller.
***
#### Nova Response
Agora o retorno inclui também o array `webhooks`.
```
[
{
"idSeller": 89,
"document": "12345678901",
"companyName": "Empresa Exemplo Ltda",
"fantasyName": "Empresa Exemplo",
"sellerUrl": "https://empresa-exemplo.com.br",
"email": "contato@empresa-exemplo.com",
"token": "123e4567-e89b-12d3-a456-426614174000",
"address": {
"city": "São Paulo",
"state": "SP",
"number": "123",
"street": "Rua das Flores",
"country": "BR",
"zipCode": "01234567",
"district": "Centro",
"complement": "Sala 101"
},
"contacts": {
"name": "João Silva",
"email": "contato@empresa.com",
"phone": "11966701879"
},
"accounts": {
"bank": 1,
"issuer": "1234",
"number": "98765",
"pixKey": "12345678901",
"pixKeyType": "CPF",
"accountType": "CHECKING_ACCOUNT",
"issuerDigit": 6,
"transferType": "PIX"
},
"webhooks": [
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"title": "Webhook",
"domains": [
"ORDER",
"SUBSCRIPTION"
],
"active": true,
"url": "https://api.technologysolutions.com.br/webhook"
}
]
}
]
```
#### Compatibilidade
Assim como no `POST`:
* O campo `webhook` continua sendo retornado
* Está depreciado
* Deve ser substituído pelo uso do array `webhooks`
***
## PATCH `/v2/seller`
### Alterações Importantes
Agora o endpoint permite:
* Atualizar **account**
* Atualizar webhook existente
* Criar novo webhook
* Enviar `account` e `webhooks` juntos
* Não é permitido enviar a request sem `account` e sem `webhooks`
***
### Regras de Validação
#### 1. `account` e `webhooks` são opcionais
Mas **ao menos um dos dois deve ser enviado**.
***
#### 2. Atualização de Webhook
Para atualizar um webhook existente:
* É obrigatório enviar o campo `uuid`
* É obrigatório enviar **pelo menos um** dos campos abaixo:
* `title`
* `domains`
* `active`
* `url`
Exemplo:
```
{
"idSeller": 123,
"webhooks": [
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"title": "Webhook de Pedidos",
"active": true
}
]
}
```
***
#### 3. Criação de Novo Webhook
Para criar um novo webhook:
* Não enviar `uuid`
* Enviar todos os campos obrigatórios:
```
{
"idSeller": 123,
"webhooks": [
{
"title": "Webhook de Assinaturas",
"domains": ["SUBSCRIPTION"],
"active": true,
"url": "https://barte.com/webhook"
}
]
}
```
***
### Nova Request Completa (Account + Webhooks)
```
{
"idSeller": 123,
"webhooks": [
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"title": "Webhook de Pedidos",
"domains": ["ORDER", "SUBSCRIPTION"],
"active": true,
"url": "https://barte.com/webhook"
}
],
"account": {
"bank": "1",
"issuer": "144111",
"issuerDigit": "6",
"number": "1425",
"bankDigit": "5",
"accountType": "CHECKING_ACCOUNT",
"transferType": "PIX",
"pixKey": "50307285030",
"pixKeyType": "DOCUMENT"
}
}
```
***
### Alteração na Response
#### Response Anterior
```
{
"idSeller": "1001",
"account": { ... }
}
```
***
#### Nova Response
Agora retorna também os `webhooks`:
```
{
"idSeller": "1001",
"account": {
"bank": "237",
"bankDigit": "2",
"issuer": "1234",
"issuerDigit": "5",
"number": "98765",
"accountType": "CHECKING_ACCOUNT",
"transferType": "PIX",
"pixKey": "12345678901",
"pixKeyType": "CPF"
},
"webhooks": [
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"title": "Webhook de Pedidos",
"domains": ["ORDER", "SUBSCRIPTION"],
"active": true,
"url": "https://barte.com/webhook"
}
]
}
```
***
## Recomendações
Recomendamos que todas as integrações:
* Migrem o quanto antes para o uso exclusivo de `webhooks`
* Não dependam mais do campo `webhook`
* Validem todos os fluxos em Sandbox antes de migrar para produção
# API de Extrato – Nova Propriedade uuid
### Visão Geral
A partir de **17/12/2025**, o endpoint **`GET /v2/report/statement`** passou a retornar um novo campo chamado **`uuid`** em cada objeto do array de resposta.
Esse campo representa um **identificador único do item de extrato**, permitindo que cada registro seja tratado, referenciado e rastreado individualmente.
***
### O que mudou
#### Antes
Os objetos retornados pelo endpoint não possuíam um identificador único próprio. A identificação dependia de combinações de campos, como datas, operação ou `uuid_charge`.
#### Agora
Cada item do extrato possui um campo **`uuid`**, garantindo unicidade e facilitando integrações e tratamentos posteriores.
***
### Nova Propriedade
| Campo | Tipo | Descrição |
| ------ | --------------- | ------------------------------------------------------------------------------------------- |
| `uuid` | `string (UUID)` | Identificador único do item de extrato. É estável e exclusivo para cada registro retornado. |
***
### Exemplo de Retorno
```json
[
{
"uuid":"8a3f5c2e-1b4d-4e9a-b7c1-3d6f9e2a1c5b",
"execution_date":"2025-12-15",
"charge_paid_date":"2025-12-15T17:35:23.851Z",
"uuid_charge":"123e4567-e89b-12d3-a456-426614174000",
"operacao":"ESTORNO",
"payment_method":"text",
"entrada_bruta":1,
"saida_bruta":1,
"entrada_liquida":1,
"saida_liquida":1,
"taxa_operacao":"text",
"bandeira":"text"
}
]
```
***
### Casos de Uso
A nova propriedade `uuid` pode ser utilizada para:
* Identificar unicamente um item do extrato em sistemas externos;
* Evitar duplicidade de registros em processos de ingestão ou conciliação;
* Referenciar um item específico em logs, auditorias ou suporte;
* Facilitar operações de cache e controle de estado no frontend.
***
### Compatibilidade
* ✅ Alteração **retrocompatível**
* ❌ Nenhum campo existente foi removido ou alterado
* ➕ Apenas a adição do novo atributo `uuid`
Não é necessária nenhuma ação imediata para integrações existentes, a menos que desejem utilizar o novo identificador.
***
### Observações
* O valor do `uuid` é gerado pelo sistema e não deve ser inferido ou construído a partir de outros campos.
* O mesmo `uuid` sempre representará o mesmo item de extrato.
***
Em caso de dúvidas, entre em contato com o time de integração ou consulte a documentação completa da API.
# Alterações na API de Vendedores em 15/10/2025
### **Resumo das Alterações**
Estamos atualizando os endpoints da API de Sellers v2 com novos campos obrigatórios a partir do dia 15/10/25.
#### **POST /v2/seller**
**Clique no link abaixo para ver a referência completa da requisição:**
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/nO7uQGIG08MTcKPkqkbL" %}
[Criar Vendedor](/api-reference/intermediador-de-pagamentos/gerencie-seus-vendedores/criar-vendedor)
{% endcontent-ref %}
| **Antes** | **Depois** |
| ---------------------------- | ------------------------------------------------------------------------- |
| Sem objeto `owner` | Objeto `owner` obrigatório com 3 campos (`name`, `document`, `birthdate`) |
| Sem campo `mccCpf` | Campo `mccCpf` **obrigatório** quando document for CPF |
| 7 campos no objeto `account` | 8 campos no objeto `account` (+ `transferType`) |
| Sem campo `transferType` | Campo `transferType` **obrigatório** no objeto `account` |
#### **PATCH /v2/seller**
**Clique no link abaixo para ver a referência completa da requisição:**
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/eOUVcXkNunX70f7dKyTd" %}
[Atualizar Conta e Webhooks de um Vendedor](/api-reference/intermediador-de-pagamentos/gerencie-seus-vendedores/atualizar-conta-e-webhooks-de-um-vendedor)
{% endcontent-ref %}
| **Antes** | **Depois** |
| ---------------------------- | --------------------------------------------- |
| Sem campo `transferType` | Campo `transferType` **obrigatório** |
| 7 campos no objeto `account` | 8 campos no objeto `account` (+ transferType) |
#### **GET/v2/seller**
**Clique no link abaixo para ver a referência completa da requisição:**
{% content-ref url="/spaces/hY03QzfTvLWOjOsYfPiz/pages/zIwK6okG84nsa852kbOm" %}
[Buscar Vendedores](/api-reference/intermediador-de-pagamentos/gerencie-seus-vendedores/buscar-vendedores)
{% endcontent-ref %}
| **Antes** | **Depois** |
| ---------------------------- | --------------------------------------------- |
| Sem campo `transferType` | Campo `transferType` **no response** |
| 7 campos no objeto `account` | 8 campos no objeto `account` (+ transferType) |
***
## **Detalhamento das Alterações**
### **1. POST /v2/seller - Criação de Sellers**
**Novos Campos:**
* **transferType** (obrigatório): `"PIX"` ou `"BANK_ACCOUNT"` no objeto `account`
* **mccCpf** (condicional): Obrigatório quando `document` for CPF
* objeto **owner** (obrigatório):
* **`name`** (string, obrigatório): Nome completo do proprietário (máx. 100 caracteres)
* **`document`** (string, obrigatório): CPF do proprietário (11 dígitos)
* **`birthdate`** (string, obrigatório): Data de nascimento no formato YYYY-MM-DD
#### **Exemplo de Payload (com campos adicionais):**
```json
{
"document": "65800562000165",
"companyName": "Old Order",
"fantasyName": "Old Order Tecnologia",
"webhook": "https://oldorder.com.br",
"sellerUrl": "https://oldorder.com.br",
"email": "o@teste.com",
"password": "cp202729",
"owner": { // ← NOVO OBJETO OBRIGATÓRIO
"name": "João da Silva",
"document": "51102616010",
"birthdate": "1990-01-01"
},
"address": {
"country": "BR",
"state": "MG",
"city": "Belo Horizonte",
"district": "Centro",
"street": "Avenida Afonso Pena",
"zipCode": "30130001",
"number": "1500",
"complement": "Sala 202"
},
"contact": {
"name": "João Silva",
"email": "joao@oldorder.com",
"countryCode": "55",
"phone": "31999887766"
},
"account": {
"account": {
"bank": "001",
"issuer": "144111",
"issuerDigit": "6",
"number": "1425",
"bankDigit": "5",
"accountType": "CHECKING_ACCOUNT"
},
"transferType": "PIX", // ← NOVO CAMPO OBRIGATÓRIO
"pix": {
"keyType": "CNPJ",
"key": "65800562000165"
}
}
```
#### **Exemplos de resposta:**
**Sucesso (201)**
```json
{
"document": "65800562000165",
"companyName": "Old Order",
"fantasyName": "Old Order Tecnologia",
"webhook": "https://oldorder.com.br",
"sellerUrl": "https://oldorder.com.br",
"email": "o@teste.com",
"password": "cp202729",
"owner": {
"name": "João da Silva",
"document": "51102616010",
"birthdate": "1990-01-01"
},
"address": {
"country": "BR",
"state": "MG",
"city": "Belo Horizonte",
"district": "Centro",
"street": "Avenida Afonso Pena",
"zipCode": "30130001",
"number": "1500",
"complement": "Sala 202"
},
"contact": {
"name": "João Silva",
"email": "joao@oldorder.com",
"countryCode": "55",
"phone": "31999887766"
},
"account": {
"account": {
"bank": "001",
"issuer": "144111",
"issuerDigit": "6",
"number": "1425",
"bankDigit": "5",
"accountType": "CHECKING_ACCOUNT"
},
"transferType": "PIX",
"pix": {
"keyType": "CNPJ",
"key": "65800562000165"
}
}
}
```
**Erro (400)**
{% code fullWidth="false" %}
```json
{ "error": "[400] BAR-3011 Erro de validação do payload - document é obrigatório; email deve ser um email válido; owner.document deve ser um CPF válido"}
```
{% endcode %}
**Erros comuns**
#### 400 - Bad Request
* **BAR-3011**: Erro de validação do payload
* Campos obrigatórios ausentes
* Formatos inválidos
* Valores fora dos limites permitidos
#### 401 - Unauthorized
* **BAR-3009**: Token de autenticação ausente ou inválido
***
### **2. PATCH /v2/seller - Atualização de Conta Bancária**
**Novo Campo:**
* **transferType** (obrigatório): `PIX` ou `BANK_ACCOUNT`
**Novo Payload (com transferType):**
```json
{
"idSeller": 123,
"account": {
"bank": "1",
"issuer": "144111",
"issuerDigit": "6",
"number": "1425",
"bankDigit": "5",
"accountType": "CHECKING_ACCOUNT",
"transferType": "PIX", // ← NOVO CAMPO OBRIGATÓRIO
"pixKey": "50307285030",
"pixKeyType": "DOCUMENT"
}
}
```
**Resposta (inclui novo campo transferType):**
```json
{
"idSeller": 123,
"account": {
"bank": "1",
"issuer": "144111",
"number": "1425",
"issuerDigit": "6",
"bankDigit": "5",
"accountType": "CHECKING_ACCOUNT",
"transferType": "PIX", // ← NOVO CAMPO OBRIGATÓRIO
"pixKey": "50307285030",
"pixKeyType": "DOCUMENT"
}
}
```
### **3. GET/v2/seller -** Buscar vendedor
```json
{
"idSeller":89,
"document":"12345678901",
"companyName":"Empresa Exemplo Ltda",
"fantasyName":"Empresa Exemplo",
"sellerUrl":"https://empresa-exemplo.com.br",
"email":"contato@empresa-exemplo.com",
"token": 123e4567-e89b-12d3-a456-426614174000,
"address":{
"city":"São Paulo",
"state":"SP",
"number":"123",
"street":"Rua das Flores",
"country":"BR",
"zipCode":"01234567",
"district":"Centro",
"complement":"Sala 101"
},
"contacts":{
"name":"João Silva",
"email":"joao@empresa-exemplo.com",
"phone":"11999887766"
},
"accounts":{
"bank":1,
"issuer":"1234",
"number":"98765",
"pixKey":"12345678901",
"pixKeyType":"CPF",
"accountType":"CHECKING_ACCOUNT",
"issuerDigit":6,
"transferType":"PIX"
}
}
```
***
### **Valores Aceitos**
#### **transferType:**
* `PIX`: Transferência via sistema PIX
* `BANK_ACCOUNT`: Transferência bancária tradicional (TED/DOC)
#### **accountType:**
* `CHECKING_ACCOUNT`: Conta corrente
* `SAVINGS_ACCOUNT`: Conta poupança
#### **pixKeyType:**
* `CPF`: Documento de pessoa física
* `CNPJ`: Documento de pessoa jurídica
* `EMAIL`: Endereço de email
* `PHONE`: Número de telefone
* `DOCUMENT`: CPF ou CNPJ (detecção automática)
* `ALLEATORY_KEY`: Chave aleatória
#### **mccCpf:**
* `VETERINARY_SERVICES`: Serviços veterinários
* `SPECIAL_TRADE_CONTRACTORS`: Empreiteiros especializados
* `TAXI_CABS_AND_LIMOUSINES`: Táxis e limusines
* `MISCELLANEOUS_GENERAL_MERCHANDISE`: Mercadorias gerais diversas
* `MISCELLANEOUS_FOOD_SHOPS`: Lojas de alimentos diversos
* `TAILORS_SEAMSTRESSES_MENDING`: Alfaiates e costureiras
* `MISCELLANEOUS_APPAREL_SHOPS`: Lojas de vestuário diversas
* `DOOR_TO_DOOR_SALES`: Vendas porta a porta
* `ARTIST_SUPPLY_CRAFT_SHOPS`: Lojas de materiais artísticos
* `BEAUTY_AND_BARBER_SHOPS`: Salões de beleza e barbearias
* `MISCELLANEOUS_PERSONAL_SERVICES`: Serviços pessoais diversos
* `TOWING_SERVICES`: Serviços de reboque
* `COMPUTER_MAINTENANCE_REPAIR`: Manutenção e reparo de computadores
* `BUSINESS_SERVICES`: Serviços empresariais
* `AUTOMOTIVE_SERVICE_SHOPS`: Oficinas automotivas
* `DOCTORS_AND_PHYSICIANS`: Médicos e clínicos
* `DENTISTS_AND_ORTHODONTISTS`: Dentistas e ortodontistas
* `MEDICAL_SERVICES_HEALTH_PRACTITIONERS`: Serviços médicos e profissionais de saúde
* `LEGAL_SERVICES_ATTORNEYS`: Serviços jurídicos e advogados
* `PROFESSIONAL_SERVICES`: Serviços profissionais
***
### **Exemplos de Erro**
#### **Campo transferType ausente:**
```json
{
"error": "Campo transferType é obrigatório no objeto account"
}
```
#### **Campo mccCpf ausente (quando document for CPF):**
```json
{
"error": "mccCpf é obrigatório quando document for CPF"
}
```
#### **Valor inválido para transferType:**
```json
{
"error": "transferType deve ser PIX ou BANK_ACCOUNT"
}
```
***
### **Testando em Sandbox**
No processo de teste utilize as credenciais de Sandbox compartilhados pelo time Barte. Sua chave `X-Token-Api` é diferente da utilizada em produção.
#### **Cenários de Teste Recomendados:**
1. **POST /v2/seller** com novos campos `transferType` e `mccCpf`
2. **PATCH /v2/seller** com novo campo `transferType`
#### **Exemplo de Teste POST (CPF):**
```json
POST /v2/seller
{
"document": "12345678901",
"companyName": "Empresa Teste",
"fantasyName": "Fantasia Teste",
"mccCpf": "BUSINESS_SERVICES",
"account": {
"bank": "1",
"issuer": "144111",
"issuerDigit": "6",
"number": "1425",
"bankDigit": "5",
"accountType": "CHECKING_ACCOUNT",
"transferType": "PIX",
"pixKey": "12345678901",
"pixKeyType": "DOCUMENT"
},
// ... outros campos obrigatórios
}
```
#### **Exemplo de Teste POST (CNPJ):**
```json
POST /v2/seller
{
"document": "12345678000195",
"companyName": "Empresa Teste LTDA",
"fantasyName": "Fantasia Teste",
// mccCpf não é obrigatório para CNPJ
"account": {
"transferType": "PIX",
// ... outros campos
}
}
```
***
**Agradecemos pela parceria e estamos à disposição para auxiliar em todo o processo de migração!**
# Código de Autorização e Código NSU
A partir de 29 de outubro de 2025, os endpoints relacionados a orders, **charges** e subscriptions passam a incluir dois novos campos no payload de resposta em ambiente de Sandbox. Esses mesmos campos entrarão em vigor em ambiente de produção no dia 03 de novembro de 2025:
* **`acquirerAuthorizationCode`**
* **`acquirerAuthorizationNsu`**
Esses campos estarão presentes nas **charges** retornadas pelos seguintes endpoints:
* `/orders`
* `/subscriptions`
* `/charges`
***
### :gear-code: Novos campos adicionados
| Campo | Tipo | Descrição |
| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `acquirerAuthorizationCode` | `string` | Código de autorização **emitido pela adquirente** ou instituição financeira responsável pela transação. |
| `acquirerAuthorizationNsu` | `string` | NSU (**Número Sequencial Único**) **gerado pela adquirente** ou banco, utilizado para rastrear a operação externamente. |
Esses campos permitem **rastreabilidade avançada das transações financeiras**, facilitando processos de conciliação, auditoria e integração com adquirentes e bancos.
***
### :scale-balanced: Diferença entre códigos internos e externos
A Barte já disponibiliza os campos `authorizationCode` e `authorizationNsu`, que são **códigos internos de gerenciamento**, utilizados dentro dos sistemas Barte para identificar e vincular transações.
Os novos campos `acquirerAuthorizationCode` e `acquirerAuthorizationNsu` são **códigos externos**, emitidos diretamente pelas **adquirentes** ou **instituições financeiras**, e servem para rastrear as transações em sistemas externos.
| Tipo de código | Campo | Origem | Utilização |
| -------------- | -------------------------------------------------------- | ------------------ | ------------------------------- |
| Interno | `authorizationCode` / `authorizationNsu` | Barte | Controle e rastreamento interno |
| Externo | `acquirerAuthorizationCode` / `acquirerAuthorizationNsu` | Adquirente / Banco | Consulta e conciliação externa |
***
### :code: Exemplo de payload atualizado
O payload abaixo é o objeto da charge.
```json
{
"uuid": "f337e5a4-62a3-41af-8449-c9898f1de66b",
"title": "Teste",
"expirationDate": "2025-10-14",
"value": 100,
"paymentMethod": "CREDIT_CARD_EARLY_SELLER",
"status": "PAID",
"customer": {
"document": "001052647",
"type": "SSN",
"name": "Joshua Henry",
"email": "Heyj5wohn4445@gmail.com",
"phone": "9409822523"
},
"authorizationCode": "7021748",
"authorizationNsu": "5737396",
"acquirerAuthorizationCode": "A1B2C3D4",
"acquirerAuthorizationNsu": "99887766",
"refunds": [],
"createdAt": "2025-10-14 22:35:30",
"paidDate": "2025-10-14",
"originalValue": 100,
"installments": 5,
"brand": "mastercard"
}
```
***
### :thumbtack: Observação
> A partir de 29 de outubro de 2025, todas as respostas dos endpoints que retornam um ou vários objetos da charge (orders, charges, subscriptions) passarão a conter os campos `acquirerAuthorizationCode` e `acquirerAuthorizationNsu`. Esses dois campos entrarão em vigor em ambiente de produção no dia 03 de novembro de 2025.
>
> Essa atualização não altera os campos internos `authorizationCode` e `authorizationNsu`, que continuarão sendo utilizados para rastreamento dentro dos sistemas Barte.
>
> Nada muda no contrato existente, são apenas campos adicionais (sem breaking change).
>
> Melhora a conciliação, agiliza auditoria/suporte e aumenta a rastreabilidade em interações — especialmente com bancos.
>
> Dica (para quem faz parsing estrito de payloads): se sua aplicação rejeita atributos desconhecidos, ajuste para permitir/ignorar esses dois novos campos.
# Collections
Para facilitar seus testes e integrações, disponibilizamos coleções pré-configuradas da API da Barte.\
Você pode importar essas coleções nos principais clientes de API:
* **Postman** ⚡
* **Insomnia** 🌙
Essas coleções já incluem:
* Endpoints organizados por recurso
* Exemplos de requisição e resposta
* Headers obrigatórios (incluindo `X-Token-Api`)
* Estrutura pronta para que você apenas configure seu token e comece a testar
### :bolt: Usando no Postman
Você pode **fazer o fork da collection** diretamente no Postman clicando no link abaixo:
:right: [Fork da Collection no Postman](https://www.postman.com/washington-rodrigues/barte-collection/collection/hf15utp/barte-api?action=share\&creator=45328072)
O fork cria uma cópia sincronizada com nossa collection oficial, permitindo que você receba atualizações sempre que houver alterações.
***
### :floppy-disk: Importando via arquivo JSON
Se preferir, você pode **baixar o arquivo `.json`** e importar manualmente:
Baixar Collection
#### :thumbtack: Como importar:
* **No Postman** → `Import > File` e selecione o `.json`.
* **No Insomnia** → `Application → Preferences → Data → Import Data → From File` e selecione o mesmo `.json`.
> :check: O mesmo arquivo funciona para os dois clientes.
***
### :screwdriver-wrench: Dicas
* Todas as requisições exigem o header **X-Token-Api** (veja a seção Como obter o Token de API).
* As collections já vêm com exemplos de `body`, `headers` e parâmetros prontos. Basta substituir pelos dados da sua conta.
* Se optar pelo fork no Postman, mantenha sua collection sincronizada para receber atualizações automaticamente.
# Comece por aqui
Este é o seu ponto de partida para integrar as soluções de pagamento da Barte. Compilamos informações detalhadas sobre nossos endpoints e como utilizá-los para que você comece a operar de forma rápida e eficiente.
## URLs para realizar as chamadas
| **Ambiente** | **URL** |
| ------------ | ------------------------------- |
| Produção | |
| Sandbox | |
## Chaves de API
Para realizar as chamadas em nossos endpoints, é necessário enviar um **X-Token-Api** no Header da requisição, dessa forma podemos validar e aprovar com base em suas permissões.
#### Como conseguir essa Chave de API?
* Para os **Intermediadores de Pagamentos**, é possível encontrar as Chaves de API de seus vendedores acessando o [Portal do Intermediador](https://docs.barte.com/webapp/) → Vendedores → Selecionar um Vendedor → Integração. Nessa tela, você verá as chaves pertencentes a esse vendedor.
* Para os **Vendedores**, é possível encontrar sua Chave de API acessando o [Portal do Vendedor](https://docs.barte.com/app/) → Configurações → Integração. Nessa tela, você verá as Chaves de API disponíveis para utilizar nas chamadas.
## Suporte e Ajuda
Caso apareçam dúvidas durante a integração, é possível chamar nossa equipe de especialistas para ajudá-lo através dos canais disponibilizados pela Barte no fechamento do contrato.
# Gerencie seus Vendedores
# Criar Vendedor
Para iniciar o processo de integração, siga os passos abaixo para cadastrar um novo vendedor com sucesso.
{% hint style="warning" %}
Importante
Após criar um novo vendedor, salve o **X-Token-Api** retornado na resposta: ele é a credencial que autentica e autoriza todas as transações dessa conta.
{% endhint %}
{% openapi src="/files/kNUVvXhC9hELLG8LWc06" path="/v2/seller" method="post" %}
[sellers.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-97db3620f00860e5dc2d8684bc1f4620634703d6%2Fsellers.yaml?alt=media)
{% endopenapi %}
# Buscar Vendedores
## Consultar dados do seller
> Retorna os dados do seller com query parameters opcionais
```json
{"openapi":"3.0.0","info":{"title":"API de Sellers v2 - Atualizada","version":"2.1.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de produção"},{"url":"https://sandbox-api.barte.com","description":"Servidor de sandbox"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Token-Api"}},"schemas":{"SellerGetResponse":{"type":"object","properties":{"idSeller":{"type":"integer"},"document":{"type":"string"},"companyName":{"type":"string"},"fantasyName":{"type":"string"},"sellerUrl":{"type":"string"},"email":{"type":"string","format":"email"},"token":{"type":"string","format":"uuid"},"address":{"$ref":"#/components/schemas/AddressResponse"},"contacts":{"$ref":"#/components/schemas/ContactResponse"},"accounts":{"$ref":"#/components/schemas/AccountResponse"},"webhooks":{"type":"array","description":"Array de webhooks do seller","items":{"$ref":"#/components/schemas/Webhook"}}}},"AddressResponse":{"type":"object","properties":{"city":{"type":"string"},"state":{"type":"string"},"number":{"type":"string"},"street":{"type":"string"},"country":{"type":"string"},"zipCode":{"type":"string"},"district":{"type":"string"},"complement":{"type":"string"}}},"ContactResponse":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"AccountResponse":{"type":"object","properties":{"bank":{"type":"integer"},"issuer":{"type":"string"},"number":{"type":"string"},"pixKey":{"type":"string"},"pixKeyType":{"type":"string"},"accountType":{"type":"string"},"issuerDigit":{"type":"integer"},"transferType":{"type":"string"}}},"Webhook":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Identificador único do webhook"},"title":{"type":"string","description":"Nome do webhook"},"domains":{"type":"array","description":"Eventos vinculados (ORDER, SUBSCRIPTION)","items":{"type":"string","enum":["ORDER","SUBSCRIPTION"]}},"active":{"type":"boolean","description":"Indica se o webhook está ativo"},"url":{"type":"string","format":"uri","description":"URL configurada para recebimento"}}},"SellerListResponse":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/SellerListItem"}},"page":{"type":"integer"},"size":{"type":"integer"},"totalElements":{"type":"integer"},"totalPages":{"type":"integer"}}},"SellerListItem":{"type":"object","properties":{"id":{"type":"integer"},"company_name":{"type":"string"},"notification_email":{"type":"string","format":"email"},"document":{"type":"string"},"sellerUrl":{"type":"string","nullable":true},"token":{"type":"string","format":"uuid"}}},"ValidationError":{"type":"object","properties":{"errors":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}},"AuthenticationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}},"ForbiddenError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}},"NotFoundError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}},"InternalError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}}}},"paths":{"/v2/seller":{"get":{"summary":"Consultar dados do seller","description":"Retorna os dados do seller com query parameters opcionais","tags":["Sellers"],"parameters":[{"name":"X-Token-Api","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Token de autenticação UUID v4"},{"name":"idSeller","in":"query","required":false,"schema":{"type":"string"},"description":"ID do seller para consulta"},{"name":"document","in":"query","required":false,"schema":{"type":"string"},"description":"Documento do seller para consulta (CPF ou CNPJ)"},{"name":"sellerToken","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Token do seller para consulta"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Número da página para paginação"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":10,"maximum":1000},"description":"Quantidade de registros por página (padrão 10, máximo 1000)"},{"name":"sort","in":"query","required":false,"schema":{"type":"string"},"description":"Ordenação dos resultados (ex. companyName,desc)"}],"responses":{"200":{"description":"Dados do seller retornados com sucesso","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SellerGetResponse"},{"$ref":"#/components/schemas/SellerListResponse"}]}}}},"400":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Token inativo ou inexistente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"403":{"description":"Acesso negado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"404":{"description":"Seller não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}}}}}}}
```
# Atualizar Conta e Webhooks de um Vendedor
{% openapi src="/files/iUjV9UjaXivXp7ntiH8M" path="/v2/seller" method="patch" %}
[sellers-update.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-dd9b532c88c084a89d1e48ae49a1e6160d9e5ce4%2Fsellers-update.yaml?alt=media)
{% endopenapi %}
# Atualizar taxas de um Vendedor
## Atualiza as taxas de um vendedor específico
> Atualiza as taxas de um vendedor específico
```json
{"openapi":"3.0.0","info":{"title":"API de Seller v2","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Token-Api"}},"schemas":{"SellerRatesUpdateRequest":{"type":"object","required":["idSeller","currentSellerRatesRequest","observation"],"properties":{"idSeller":{"type":"integer","description":"Id do vendedor que se deseja alterar as taxas (Exemplo 123)"},"currentSellerRatesRequest":{"$ref":"#/components/schemas/CurrentSellerRatesRequest"},"observation":{"type":"string","description":"Observações sobre a alteração das taxas (Exemplo \"Alterar taxas\")"}}},"CurrentSellerRatesRequest":{"type":"object","description":"Objeto contendo as configurações de taxas do vendedor","properties":{"pixConfigData":{"$ref":"#/components/schemas/PixConfigData"},"debitCardConfigData":{"$ref":"#/components/schemas/DebitCardConfigData"},"bankSlipConfigData":{"$ref":"#/components/schemas/BankSlipConfigData"},"sightCreditCardConfigData":{"$ref":"#/components/schemas/SightCreditCardConfigData"},"earlyCreditCardConfigData":{"$ref":"#/components/schemas/EarlyCreditCardConfigData"}}},"PixConfigData":{"type":"object","description":"Configurações de taxa para PIX","properties":{"delayForRedeem":{"type":"integer","description":"Dias para resgatar (Exemplo 2)"},"rate":{"type":"number","format":"float","description":"Taxa aplicada (Exemplo 0.2)"},"rateLimitValue":{"type":"integer","description":"Valor limite para a taxa (Exemplo 10000)"}}},"DebitCardConfigData":{"type":"object","description":"Configurações de taxa para cartão de débito","properties":{"delayForRedeem":{"type":"integer","description":"Dias para resgatar (Exemplo 1)"},"rate":{"type":"number","format":"float","description":"Taxa aplicada (Exemplo 1.99)"},"rateType":{"type":"string","enum":["value","percentage"],"description":"Tipo de taxa (value ou percentage) (Exemplo \"value\")"}}},"BankSlipConfigData":{"type":"object","description":"Configurações de taxa para boleto bancário","properties":{"delayForRedeem":{"type":"integer","description":"Dias para resgatar (Exemplo 1)"},"value":{"type":"number","format":"float","description":"Valor da taxa (Exemplo 4)"},"rate":{"type":"number","format":"float","description":"Taxa aplicada (Exemplo 4)"},"rateType":{"type":"string","enum":["value","percentage"],"description":"Tipo de taxa (value ou percentage) (Exemplo \"value\")"},"rateLimitValue":{"type":"integer","description":"Valor limite para a taxa (Exemplo 10000)"}}},"SightCreditCardConfigData":{"type":"object","description":"Configurações de taxa para cartão de crédito à vista","properties":{"delayForRedeem":{"type":"integer","description":"Dias para resgatar (Exemplo 2)"},"rate":{"type":"number","format":"float","description":"Taxa aplicada (Exemplo 3.17)"}}},"EarlyCreditCardConfigData":{"type":"object","description":"Configurações de taxa para antecipação de crédito","properties":{"delayForRedeem":{"type":"integer","description":"Dias para resgatar (Exemplo 2)"},"buyerRates":{"type":"object","description":"Taxas para o comprador","additionalProperties":{"type":"number","format":"float"}},"sellerRates":{"type":"object","description":"Taxas para o vendedor","additionalProperties":{"type":"number","format":"float"}}}},"Error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}},"Metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"path":{"type":"string"},"method":{"type":"string"}}}}},"paths":{"/v2/seller/rates":{"patch":{"summary":"Atualiza as taxas de um vendedor específico","description":"Atualiza as taxas de um vendedor específico","tags":["Seller"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRatesUpdateRequest"}}}},"responses":{"200":{"description":"Taxas atualizadas com sucesso","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro de autenticação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Acesso negado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"Método inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# Consultar taxas de um Vendedor
## Consulta as taxas de um vendedor específico
> Consulta as taxas de um vendedor específico
```json
{"openapi":"3.0.0","info":{"title":"API de Seller v2","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Token-Api"}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}},"Metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"path":{"type":"string"},"method":{"type":"string"}}}}},"paths":{"/v2/seller/rates/{sellerId}":{"get":{"summary":"Consulta as taxas de um vendedor específico","description":"Consulta as taxas de um vendedor específico","tags":["Seller"],"parameters":[{"name":"sellerId","in":"path","required":true,"description":"Identificador do vendedor (Exemplo 123)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Taxas do vendedor recuperadas com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"currentSellerRatesRequest":{"type":"object","properties":{"pixConfigData":{"type":"object","properties":{"rate":{"type":"string"},"delayForRedeem":{"type":"string"},"rateLimitValue":{"type":"string"}}},"bankSlipConfigData":{"type":"object","properties":{"value":{"type":"string"},"delayForRedeem":{"type":"string"},"rate":{"type":"string"},"rateType":{"type":"string"},"rateLimitValue":{"type":"string"}}},"debitCardConfigData":{"type":"object","properties":{"delayForRedeem":{"type":"string"},"rate":{"type":"string"},"rateType":{"type":"string"}}},"sightCreditCardConfigData":{"type":"object","properties":{"delayForRedeem":{"type":"string"},"rate":{"type":"string"}}},"earlyCreditCardConfigData":{"type":"object","properties":{"delayForRedeem":{"type":"string"},"buyerRates":{"type":"object","additionalProperties":{"type":"string"}},"sellerRates":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro de autenticação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Acesso negado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"Método inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# Solicitar Repasse
## Solicitar repasse
> Solicita o repasse do saldo disponível do seller
```json
{"openapi":"3.0.0","info":{"title":"API de Seller v2","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Token-Api"}},"schemas":{"SellerRedeemRequest":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","format":"double","minimum":10,"description":"Valor a ser resgatado"},"description":{"type":"string","description":"Descrição do resgate"}}},"Error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}},"Metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"path":{"type":"string"},"method":{"type":"string"}}}}},"paths":{"/v2/seller/{sellerId}/redeems":{"post":{"summary":"Solicitar repasse","description":"Solicita o repasse do saldo disponível do seller","tags":["Seller"],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"string"},"description":"ID do seller"},{"name":"X-Token-Api","in":"header","required":true,"schema":{"type":"string"},"description":"Token de autenticação para acesso à API"},{"name":"Content-Type","in":"header","required":false,"schema":{"type":"string","enum":["application/json"]},"description":"Tipo de conteúdo da requisição"},{"name":"x-ip-origin-request","in":"header","required":false,"schema":{"type":"string"},"description":"IP de origem da requisição"},{"name":"x-idempotency-key","in":"header","required":false,"schema":{"type":"string"},"description":"Chave de idempotência"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRedeemRequest"}}}},"responses":{"200":{"description":"Repasse solicitado com sucesso","content":{}},"202":{"description":"Solicitação aceita, processamento em andamento"},"400":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Token inativo ou inexistente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Acesso negado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro de processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Muitas requisições","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# Gerencie seus Terminais (POS)
Estes endpoints permitem que o intermediador (payfac) gerencie de forma autônoma seus **terminais POS** e o vínculo dos terminais com seus **vendedores**, sob o prefixo `/physical-payments/payfac/`.
{% hint style="warning" %}
Apenas a **conta principal (payfac)** da company pode acessar estes recursos. As requisições são autenticadas pelo header **`X-Token-Api`** e o resultado é sempre isolado pela company do token. Tokens que não sejam da conta principal recebem `403` com o código `BAR-PP-09`.
{% endhint %}
# Listar Terminais
Retorna a lista paginada dos terminais POS do intermediador autenticado, com filtros opcionais por serial number, vendedor e status transacional.
{% openapi src="/files/bQ63d5mfWk7MkCIs0OyU" path="/physical-payments/payfac/v1/terminals" method="get" %}
[physical-payments-payfac-terminals.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-32e78ae730c4fb09771b4ce2224c38500749873e%2Fphysical-payments-payfac-terminals.yaml?alt=media)
{% endopenapi %}
# Detalhar Terminal
Retorna os detalhes de um terminal a partir do seu serial number, incluindo o histórico de alocação a vendedores da company.
{% openapi src="/files/bQ63d5mfWk7MkCIs0OyU" path="/physical-payments/payfac/v1/terminals/{serial\_number}" method="get" %}
[physical-payments-payfac-terminals.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-32e78ae730c4fb09771b4ce2224c38500749873e%2Fphysical-payments-payfac-terminals.yaml?alt=media)
{% endopenapi %}
# Vincular Terminais a um Vendedor
Vincula um ou mais terminais (por serial number) a um vendedor da company do intermediador.
{% hint style="info" %}
**Operação em lote (bulk):** informe de 1 a 30 serial numbers em uma única requisição. Cada terminal é processado de forma independente e a resposta é sempre `200`, com o resultado por terminal em duas listas:
* `success` — serial numbers vinculados com sucesso.
* `errors` — serial numbers que falharam, cada um com `code` e `message`.
**Sobrescrita automática de vínculo:** um terminal já vinculado a outro vendedor da mesma company é automaticamente re-vinculado ao vendedor informado.
{% endhint %}
{% openapi src="/files/bQ63d5mfWk7MkCIs0OyU" path="/physical-payments/payfac/v1/terminals/configure" method="post" %}
[physical-payments-payfac-terminals.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-32e78ae730c4fb09771b4ce2224c38500749873e%2Fphysical-payments-payfac-terminals.yaml?alt=media)
{% endopenapi %}
# Desvincular Terminais
Desassocia terminais do vendedor atual, mantendo o vínculo com o intermediador (inverso do vínculo): um terminal `ACTIVE` volta ao status `LINKED`, sem vendedor.
{% hint style="info" %}
**Operação em lote (bulk):** informe de 1 a 30 serial numbers em uma única requisição. Cada terminal é processado de forma independente e a resposta é sempre `200`, no **mesmo padrão do vínculo**, com o resultado por terminal em duas listas:
* `success` — serial numbers desvinculados com sucesso.
* `errors` — serial numbers que falharam, cada um com `code` e `message`.
{% endhint %}
{% openapi src="/files/bQ63d5mfWk7MkCIs0OyU" path="/physical-payments/payfac/v1/terminals/unconfigure" method="post" %}
[physical-payments-payfac-terminals.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-32e78ae730c4fb09771b4ce2224c38500749873e%2Fphysical-payments-payfac-terminals.yaml?alt=media)
{% endopenapi %}
# Listar Vendedores e Terminais Vinculados
Lista os vendedores da company do intermediador, incluindo os serial numbers dos terminais POS vinculados a cada vendedor. Suporta filtros por identificador, documento e nome.
{% openapi src="/files/bQ63d5mfWk7MkCIs0OyU" path="/physical-payments/payfac/v1/sellers" method="get" %}
[physical-payments-payfac-terminals.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-32e78ae730c4fb09771b4ce2224c38500749873e%2Fphysical-payments-payfac-terminals.yaml?alt=media)
{% endopenapi %}
# Recuperação de Vendas com IA
## Solicitar recuperação de charge via IA
> Envia uma charge com falha para tentativa de recuperação via IA
```json
{"openapi":"3.0.0","info":{"title":"Barte Payment Service API - Charges","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de Produção"},{"url":"https://sandbox-api.barte.com","description":"Servidor de Sandbox"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Token-Api","description":"Token de autenticação para acesso à API"}},"schemas":{"IARecoveryRequest":{"type":"object","required":["uuid_charge"],"properties":{"uuid_charge":{"type":"string","format":"uuid","description":"Identificador único da cobrança que falhou"},"company_name":{"type":"string","description":"Nome da empresa para contexto da chamada (opcional)"}}},"IARecoveryResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Indica se a requisição foi processada com sucesso"},"message":{"type":"string","description":"Mensagem de confirmação"}}}}},"paths":{"/v2/charges/sales-recovery-ai":{"post":{"summary":"Solicitar recuperação de charge via IA","description":"Envia uma charge com falha para tentativa de recuperação via IA","tags":["Sellers"],"parameters":[{"name":"X-Token-Api","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Token de autenticação do intermediador"},{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"Tipo de conteúdo da requisição"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IARecoveryRequest"}}}},"responses":{"200":{"description":"Charge recebida para tentativa de recuperação via IA","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IARecoveryResponse"}}}},"400":{"description":"Parâmetros inválidos ou falha na requisição","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorSingle"}}}},"401":{"description":"Token inativo ou inexistente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"403":{"description":"Acesso negado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}}}}}}}
```
# Financeiro
# Consultar Transações de um Vendedor
## Lista de transações do seller
> Retorna a lista de transações de um seller específico em um período
```json
{"openapi":"3.0.3","info":{"title":"Sellers API","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-token-api","description":"Token de API obrigatório para autenticação"}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro seguindo padrão BAR-XXXX"},"title":{"type":"string","description":"Título do erro"},"description":{"type":"string","description":"Descrição detalhada do erro"}}}}},"required":["errors"]}}},"paths":{"/v2/seller/{sellerId}/transactions":{"get":{"summary":"Lista de transações do seller","description":"Retorna a lista de transações de um seller específico em um período","operationId":"getTransactions","tags":["Transactions"],"parameters":[{"name":"sellerId","in":"path","required":true,"description":"ID do Seller","schema":{"type":"string"}},{"name":"startDate","in":"query","required":true,"description":"Data inicial do período (formato YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","required":true,"description":"Data final do período (formato YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"page","in":"query","required":false,"description":"Número da página para paginação","schema":{"type":"integer"}},{"name":"size","in":"query","required":false,"description":"Quantidade de itens por página","schema":{"type":"integer","default":1000,"maximum":3000}}],"responses":{"200":{"description":"Resposta bem-sucedida","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","description":"Lista de transações","items":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"UUID da transação"},"transactionType":{"type":"string","description":"Tipo da transação"},"chargeUUID":{"type":"string","format":"uuid","description":"UUID da cobrança"},"title":{"type":"string","description":"Título da transação"},"installments":{"type":"string","description":"Número de parcelas"},"status":{"type":"string","enum":["PAID","FAILED","PENDING","CANCELLED"],"description":"Status da transação"},"paymentMethod":{"type":"string","description":"Método de pagamento"},"grossValue":{"type":"string","description":"Valor bruto (formato brasileiro)"},"netValue":{"type":"string","nullable":true,"description":"Valor líquido (formato brasileiro)"},"fee":{"type":"string","nullable":true,"description":"Taxa (formato brasileiro)"},"createdAt":{"type":"string","description":"Data de criação (formato YYYY/MM/DD HH:MM:SS)"},"updatedAt":{"type":"string","description":"Data de atualização (formato YYYY/MM/DD HH:MM:SS)"},"expirationDate":{"type":"string","description":"Data de expiração (formato YYYY/MM/DD)"},"paidDate":{"type":"string","nullable":true,"description":"Data de pagamento (formato YYYY/MM/DD)"},"receiptDate":{"type":"string","nullable":true,"description":"Data do recibo (formato YYYY/MM/DD)"},"frequencyType":{"type":"string","nullable":true,"description":"Tipo de frequência"},"customer":{"type":"object","description":"Dados do cliente","properties":{"document":{"type":"string","description":"CPF/CNPJ do cliente"},"email":{"type":"string","format":"email","description":"Email do cliente"},"name":{"type":"string","description":"Nome do cliente"},"phone":{"type":"string","description":"Telefone do cliente"}}},"address":{"type":"object","description":"Endereço do cliente","properties":{"city":{"type":"string","description":"Cidade"},"complement":{"type":"string","description":"Complemento"},"country":{"type":"string","description":"País (código ISO)"},"district":{"type":"string","description":"Bairro"},"number":{"type":"string","description":"Número"},"state":{"type":"string","description":"Estado (UF)"},"street":{"type":"string","description":"Rua"},"zipCode":{"type":"string","description":"CEP"}}},"brand":{"type":"string","description":"Bandeira do cartão"},"first6digits":{"type":"string","nullable":true,"description":"Primeiros 6 dígitos do cartão"},"last4digits":{"type":"string","nullable":true,"description":"Últimos 4 dígitos do cartão"},"cardHolerName":{"type":"string","nullable":true,"description":"Nome do titular do cartão"},"metadata":{"type":"string","nullable":true,"description":"Metadados adicionais"}}}},"totalElements":{"type":"integer","description":"Total de elementos"},"totalPages":{"type":"integer","description":"Total de páginas"},"size":{"type":"integer","description":"Quantidade de itens por página"},"page":{"type":"integer","description":"Número da página atual"}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Acesso negado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# Consultar Extrato
{% openapi src="/files/And6bAoaYEXK2CxU2soG" path="/report/statement" method="post" %}
[statements.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-c86cae53a6beb2ea711149187346dcd8f111e171%2Fstatements.yaml?alt=media)
{% endopenapi %}
# Consultar Detalhes de Repasse
## Consultar detalhamento de repasse
> Retorna o discriminativo detalhado de todas as transações, taxas e ajustes que compõem o valor total transferido ao seller em uma data específica.
```json
{"openapi":"3.0.3","info":{"title":"Consulta de Composição de Repasses","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de Produção"}],"paths":{"/v2/seller/{sellerId}/transfers/details":{"get":{"summary":"Consultar detalhamento de repasse","description":"Retorna o discriminativo detalhado de todas as transações, taxas e ajustes que compõem o valor total transferido ao seller em uma data específica.","tags":["Infraestrutura Financeira"],"parameters":[{"name":"sellerId","in":"path","description":"Identificador único do seller na plataforma.","required":true,"schema":{"type":"integer"}},{"name":"transferDate","in":"query","description":"Data de referência do repasse financeiro (YYYY-MM-DD).","required":true,"schema":{"type":"string"}},{"name":"x-token-api","in":"header","description":"Token de autenticação da aplicação.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dados do repasse recuperados com sucesso","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TransferResponse"}}}}},"400":{"description":"Erro de validação nos parâmetros","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Credenciais inválidas ou ausentes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Nenhum repasse localizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"TransferResponse":{"type":"object","properties":{"uuid":{"type":"string","description":"Identificador global único (UUID) do lote de transferência."},"total_amount":{"type":"string","description":"Valor líquido total efetivamente transferido."},"created_at":{"type":"string","description":"Carimbo de data/hora do processamento (YYYY-MM-DD HH:mm:ss)."},"transfer_details":{"type":"array","description":"Lista analítica dos lançamentos que compõem o saldo.","items":{"type":"object","properties":{"uuid_charge":{"type":"string","description":"UUID da cobrança ou transação original vinculada."},"type":{"type":"string","description":"Natureza do lançamento (ex: 'Taxa da Transação', 'Crédito de Venda')."},"amount":{"type":"string","description":"Valor monetário do item. Valores negativos representam débitos/taxas."},"description":{"type":"string","description":"Descrição identificadora do lançamento no extrato."}}}},"receipt_url":{"type":"string","description":"URL do comprovante detalhado do repasse."}}},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Código interno do erro para diagnóstico."},"title":{"type":"string","description":"Título legível do erro."},"description":{"type":"string","description":"Detalhamento técnico da causa do erro."}}}}}}}}}
```
# Consultar Saldo do Vendedor
## Consultar saldo do seller
> Retorna o saldo atual do seller. Quando futureAmount=true, também retorna o saldo futuro.
```json
{"openapi":"3.0.0","info":{"title":"API de Seller v2","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Token-Api"}},"schemas":{"SellerBalanceResponse":{"type":"object","properties":{"amount":{"type":"number","format":"double","description":"Saldo atual do seller"},"futureAmount":{"type":"number","format":"double","description":"Saldo futuro do seller; presente apenas quando o parâmetro futureAmount=true"}}},"Error":{"type":"object","properties":{"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}},"Metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"path":{"type":"string"},"method":{"type":"string"}}}}},"paths":{"/v2/seller/{sellerId}/balance":{"get":{"summary":"Consultar saldo do seller","description":"Retorna o saldo atual do seller. Quando futureAmount=true, também retorna o saldo futuro.","tags":["Seller"],"parameters":[{"name":"sellerId","in":"path","required":true,"schema":{"type":"string"},"description":"ID do seller"},{"name":"X-Token-Api","in":"header","required":true,"schema":{"type":"string"},"description":"Token de autenticação para acesso à API"},{"name":"Content-Type","in":"header","required":false,"schema":{"type":"string","enum":["application/json"]},"description":"Tipo de conteúdo da requisição"},{"name":"futureAmount","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Quando true, inclui o saldo futuro (futureAmount) no retorno"}],"responses":{"200":{"description":"Saldo do seller retornado com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerBalanceResponse"}}}},"202":{"description":"Solicitação aceita, processamento em andamento"},"400":{"description":"Erro de validação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Token inativo ou inexistente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Acesso negado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erro de processamento","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Muitas requisições","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# Consultar Recebíveis Futuros
## Consultar Recebíveis Futuros
> Retorna recebíveis futuros consolidados por data de execução, com cálculos de desconto aplicados.
```json
{"openapi":"3.0.0","info":{"title":"Barte Payment Service API - Recebíveis Futuros","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de Produção"},{"url":"https://sandbox-api.barte.com","description":"Servidor de Sandbox"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Token-Api","description":"Token de autenticação da company."}},"schemas":{"FutureReceivablesResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FutureReceivablesData"}}},"FutureReceivablesData":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/Summary"},"receivables":{"type":"array","items":{"$ref":"#/components/schemas/Receivable"},"description":"Lista de recebíveis por data."}}},"Summary":{"type":"object","properties":{"totalDays":{"type":"integer","description":"Número de dias com recebíveis."},"totalNet":{"type":"number","format":"double","description":"Valor líquido total do período."},"averageDailyAmount":{"type":"number","format":"double","description":"Média diária de recebíveis."}}},"Receivable":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Data de execução."},"daysUntilExecution":{"type":"integer","description":"Dias até a data de execução."},"amounts":{"$ref":"#/components/schemas/Amounts"}}},"Amounts":{"type":"object","properties":{"netCredit":{"type":"number","format":"double","description":"Total de créditos."},"netDebit":{"type":"number","format":"double","description":"Total de débitos."},"totalNet":{"type":"number","format":"double","description":"Valor líquido do dia."},"finalAmount":{"type":"number","format":"double","description":"Valor final após desconto."}}},"Error":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string","enum":["MISSING_FIELD","INVALID_DATE_FORMAT","DATE_RANGE_TOO_LARGE","Token inválido"]},"message":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/v2/report/receivables/future":{"get":{"summary":"Consultar Recebíveis Futuros","description":"Retorna recebíveis futuros consolidados por data de execução, com cálculos de desconto aplicados.","tags":["Recebíveis Futuros"],"parameters":[{"name":"X-Token-Api","in":"header","required":true,"schema":{"type":"string"},"description":"Token de autenticação para acesso à API (deve ser o token principal da company)."},{"name":"idSeller","in":"query","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,5}$"},"description":"ID do vendedor (apenas números de 1 a 999999)."},{"name":"executionDateInitial","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Data inicial no formato YYYY-MM-DD."},{"name":"executionDateFinal","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Data final no formato YYYY-MM-DD. Deve ser até 1095 dias maior que data inicial."}],"responses":{"200":{"description":"Recebíveis futuros retornados com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FutureReceivablesResponse"}}}},"400":{"description":"Erro de validação ou parâmetros inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Token inválido ou acesso negado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Muitas requisições (limite de 100 por minuto).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno do servidor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# Detalhar Recebíveis do Vendedor
## Detalhes de recebíveis do seller
> Retorna os detalhes dos recebíveis de um seller específico
```json
{"openapi":"3.0.3","info":{"title":"Sellers API","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-token-api","description":"Token de API obrigatório para autenticação"}},"schemas":{"Error":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Código do erro seguindo padrão BAR-XXXX"},"title":{"type":"string","description":"Título do erro"},"description":{"type":"string","description":"Descrição detalhada do erro"}}}}},"required":["errors"]}}},"paths":{"/v2/seller/{sellerId}/receivables/details":{"get":{"summary":"Detalhes de recebíveis do seller","description":"Retorna os detalhes dos recebíveis de um seller específico","operationId":"getReceivablesDetails","tags":["Receivables"],"parameters":[{"name":"sellerId","in":"path","required":true,"description":"ID do Seller","schema":{"type":"string"}},{"name":"date","in":"query","required":true,"description":"Data para consulta dos recebíveis (formato YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"page","in":"query","required":false,"description":"Número da página para paginação","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Quantidade de itens por página","schema":{"type":"integer"}}],"responses":{"200":{"description":"Resposta bem-sucedida","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","description":"Número da página atual"},"limit":{"type":"integer","description":"Quantidade de itens por página"},"total_page":{"type":"integer","description":"Total de páginas"},"total_records":{"type":"integer","description":"Total de registros"},"has_prev":{"type":"boolean","description":"Indica se existe página anterior"},"has_next":{"type":"boolean","description":"Indica se existe próxima página"},"date":{"type":"string","format":"date","description":"Data da consulta"},"expected_total_amount":{"type":"number","format":"float","description":"Valor total esperado"},"receivables":{"type":"array","description":"Lista de recebíveis","items":{"type":"object","properties":{"expected_net_amount":{"type":"number","format":"float","description":"Valor líquido esperado"},"expected_gross_amount":{"type":"number","format":"float","description":"Valor bruto esperado"},"charge_uuid":{"type":"string","format":"uuid","description":"UUID da cobrança"},"execution_date":{"type":"string","format":"date","description":"Data de execução"},"installment":{"type":"integer","description":"Número da parcela"},"statement_description":{"type":"string","description":"Descrição do extrato"},"details":{"type":"array","description":"Detalhes do recebível","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREDIT","DEBIT"],"description":"Tipo de transação"},"description":{"type":"string","description":"Descrição da transação"},"statement_uuid":{"type":"string","format":"uuid","description":"UUID do extrato"},"amount":{"type":"number","format":"float","description":"Valor da transação"}}}}}}}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# Plano de Taxas (Beta)
Esta documentação destina-se exclusivamente a intermediadores que já têm o recurso de Planos de Taxas ativado.
{% hint style="danger" %}
**Importante**: para utilizar essa funcionalidade, é necessário que o intermediador solicite ao time da Barte a ativação prévia do recurso. Sem isso, chamadas à API poderão retornar erros.
{% endhint %}
Os *Planos de Taxas* são uma funcionalidade da Barte para otimizar a experiência de aplicação de taxas por intermediadores. O fluxo se inicia com a criação de um plano, que é sempre vinculado à *company* (intermediador) que o originou. A gestão completa — criação, atualização e recuperação — pode ser feita tanto via API quanto pelo Webapp.
### Estrutura e regras do plano
* Os planos podem definir taxas para os métodos de pagamento: **pix**, **boleto**, **débito** e **cartão de crédito**.
* Para **cartão de crédito**, é obrigatório incluir os três tipos de pagamento: `online`, `pos` e `tap`. Eles podem ser enviados com valor zero, mas devem estar presentes.
* Cada tipo de pagamento para cartão pode ainda mapear taxas por bandeiras: `default`, `mastercard`, `visa`, `hipercard`, `elo`, `discover` e `american_express`. A bandeira `default` é obrigatória.
### Lógica de cálculo
* As taxas definidas no plano correspondem à taxa final aplicada aos seus vendedores.
* Para detalhes sobre o cálculo, consulte a interface do Webapp (tela de visualização/edição do plano).
### Associação com vendedores
* Um plano pode ser associado a **múltiplos vendedores**.
### Usabilidade no Webapp:
#### Criando um plano de taxas:
{% embed url="" %}
#### Atualizar taxas de um plano:
{% embed url="" %}
#### Atualizar o plano de um vendedor
{% embed url="" %}
# Criar Plano de Taxas
{% openapi src="/files/E2HZFJGhdvGoxlbfME3f" path="/v2/payfac/rate-plans" method="post" %}
[rate-plans.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-072526bac640948f74ac1627f8ce4cdd0b82ba30%2Frate-plans.yaml?alt=media)
{% endopenapi %}
# Atualizar Plano de Taxas
{% openapi src="/files/E2HZFJGhdvGoxlbfME3f" path="/v2/payfac/rate-plans/{idPlan}" method="put" %}
[rate-plans.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-072526bac640948f74ac1627f8ce4cdd0b82ba30%2Frate-plans.yaml?alt=media)
{% endopenapi %}
# Atualizar Nome do Plano de Taxas
{% openapi src="/files/E2HZFJGhdvGoxlbfME3f" path="/v2/payfac/rate-plans/{idPlan}" method="patch" %}
[rate-plans.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-072526bac640948f74ac1627f8ce4cdd0b82ba30%2Frate-plans.yaml?alt=media)
{% endopenapi %}
# Listar Planos de Taxas
{% openapi src="/files/E2HZFJGhdvGoxlbfME3f" path="/v2/payfac/rate-plans" method="get" %}
[rate-plans.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-072526bac640948f74ac1627f8ce4cdd0b82ba30%2Frate-plans.yaml?alt=media)
{% endopenapi %}
# Detalhar Plano de Taxas
{% openapi src="/files/E2HZFJGhdvGoxlbfME3f" path="/v2/payfac/rate-plans/{idPlan}" method="get" %}
[rate-plans.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-072526bac640948f74ac1627f8ce4cdd0b82ba30%2Frate-plans.yaml?alt=media)
{% endopenapi %}
# Alterar Plano de Taxas Padrão
{% openapi src="/files/E2HZFJGhdvGoxlbfME3f" path="/v2/payfac/rate-plans/{idPlan}/default" method="patch" %}
[rate-plans.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-072526bac640948f74ac1627f8ce4cdd0b82ba30%2Frate-plans.yaml?alt=media)
{% endopenapi %}
# Buscar Plano de Taxas de um Vendedor
{% openapi src="/files/E2HZFJGhdvGoxlbfME3f" path="/v2/payfac/seller/{idSeller}/rate-plans" method="get" %}
[rate-plans.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-072526bac640948f74ac1627f8ce4cdd0b82ba30%2Frate-plans.yaml?alt=media)
{% endopenapi %}
# Alterar Plano de Taxas de um Vendedor
{% openapi src="/files/E2HZFJGhdvGoxlbfME3f" path="/v2/payfac/seller/{idSeller}/rate-plans/{idPlan}" method="patch" %}
[rate-plans.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-072526bac640948f74ac1627f8ce4cdd0b82ba30%2Frate-plans.yaml?alt=media)
{% endopenapi %}
# Carta de Cancelamento de Transação
## Gerar carta de cancelamento
> Gera a carta de cancelamento de uma cobrança específica.\
> \
> O parâmetro \`download\` controla o comportamento do PDF:\
> \- Se \`download=true\`: ao clicar na URL, o PDF é baixado automaticamente\
> \- Se \`download=false\`: ao clicar na URL, o PDF abre no navegador (sem download automático)
```json
{"openapi":"3.0.0","info":{"title":"API de Cancellation Letter - Charges","version":"1.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de produção"},{"url":"https://sandbox-api.barte.com","description":"Servidor de sandbox"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Token-Api"}},"schemas":{"CancellationLetterResponse":{"type":"object","properties":{"message":{"type":"string","description":"Mensagem de sucesso da geração do comprovante"},"url":{"type":"string","format":"uri","description":"URL temporária para acesso ao PDF da carta de cancelamento"},"expiresInSeconds":{"type":"integer","description":"Tempo de expiração da URL em segundos"}}},"ValidationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}},"AuthenticationError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}},"ForbiddenError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}},"NotFoundError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}},"UnprocessableEntityError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}},"InternalError":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}}}}}}},"paths":{"/v2/charges/{chargeUuid}/cancellation-letter":{"get":{"summary":"Gerar carta de cancelamento","description":"Gera a carta de cancelamento de uma cobrança específica.\n\nO parâmetro `download` controla o comportamento do PDF:\n- Se `download=true`: ao clicar na URL, o PDF é baixado automaticamente\n- Se `download=false`: ao clicar na URL, o PDF abre no navegador (sem download automático)\n","tags":["Charges"],"parameters":[{"name":"X-Token-Api","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"Token de autenticação do vendedor"},{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"Tipo de conteúdo da requisição"},{"name":"chargeUuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Identificador único da cobrança"},{"name":"download","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Define se o PDF deve ser baixado automaticamente ou apenas visualizado no navegador.\n- `true`: baixar automaticamente\n- `false`: abrir no navegador (padrão)\n"}],"responses":{"200":{"description":"Carta de cancelamento gerada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancellationLetterResponse"}}}},"400":{"description":"Erro na requisição","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"403":{"description":"Acesso negado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"404":{"description":"Cobrança não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"422":{"description":"Status inválido da cobrança","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}}}}}}}
```
# Criar Comprador
## Cria um buyer
> Cria um buyer e retorna o seu identificador (UUID) junto aos dados fornecidos
```json
{"openapi":"3.0.3","info":{"title":"API de Buyers","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de Produção"},{"url":"https://sandbox-api.barte.com","description":"Servidor de Sandbox"}],"security":[{"X-Token-Api":[]}],"components":{"securitySchemes":{"X-Token-Api":{"type":"apiKey","name":"X-Token-Api","in":"header"}},"schemas":{"CreateBuyerV2Request":{"type":"object","required":["document","name","email","phone"],"properties":{"document":{"$ref":"#/components/schemas/DocumentRequest"},"name":{"type":"string","maxLength":255},"email":{"type":"string","maxLength":150,"format":"email"},"countryCode":{"type":"string","maxLength":4},"phone":{"type":"string","maxLength":11,"pattern":"^\\d{10,11}$"},"alternativeEmail":{"type":"string","maxLength":150,"format":"email"},"address":{"$ref":"#/components/schemas/AddressSellerClientRequest"}}},"DocumentRequest":{"type":"object","required":["documentNumber","documentType","documentNation"],"properties":{"documentNumber":{"type":"string"},"documentType":{"type":"string","enum":["cpf","cnpj"]},"documentNation":{"type":"string"}}},"AddressSellerClientRequest":{"type":"object","properties":{"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"district":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"zipCode":{"type":"string"}}},"BuyerV2Response":{"type":"object","properties":{"uuid":{"type":"string"},"document":{"type":"string"},"name":{"type":"string"},"countryCode":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"alternativeEmail":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ErrorDetail":{"type":"object","properties":{"status":{"type":"string"},"code":{"type":"string","enum":["PAYMENT-0000","PAYMENT-0500","PAYMENT-9999","BAR-7001","BAD_REQUEST","FORBIDDEN","METHOD_NOT_ALLOWED","NOT_ACCEPTABLE","UNSUPPORTED_MEDIA_TYPE"]},"title":{"type":"string","enum":["BUSINESS_SELLER","BUSINESS_CHECKOUT","BUSINESS_COMMON","BUSINESS_SECURITY","BUSINESS_SUBSCRIPTION","INVALID_REQUEST_PARAM","BUSINESS_METRIC","BUSINESS_ACCOUNTANCY","BUSINESS_NOTIFICATION","BUSINESS_BARTE","BUSINESS_COMPANY","BUSINESS_INVOICE","BUSINESS_TRANSFER","BUSINESS_CARD","BUSINESS_ORDER","card_not_supported"]},"description":{"type":"string"},"action":{"type":"string"},"additionalInfo":{"type":"object","additionalProperties":{"type":"object"}}}},"Metadata":{"type":"object","properties":{"totalRecords":{"type":"integer"},"totalPages":{"type":"integer"},"requestDatetime":{"type":"string","format":"date-time"}}}}},"paths":{"/v2/buyers":{"post":{"tags":["API v2 para criação de Buyers"],"summary":"Cria um buyer","description":"Cria um buyer e retorna o seu identificador (UUID) junto aos dados fornecidos","operationId":"createBuyer","requestBody":{"description":"Dados do buyer a ser criado","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBuyerV2Request"}}}},"responses":{"201":{"description":"buyer cadastrado com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerV2Response"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Acesso proibido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
# Atualizar Comprador
## Atualiza um buyer por seu UUUID
> Atualiza os dados de um buyer específico com base no UUID fornecido.
```json
{"openapi":"3.0.3","info":{"title":"API de Buyers","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de Produção"},{"url":"https://sandbox-api.barte.com","description":"Servidor de Sandbox"}],"security":[{"X-Token-Api":[]}],"components":{"securitySchemes":{"X-Token-Api":{"type":"apiKey","name":"X-Token-Api","in":"header"}},"schemas":{"UpdateBuyerV2Request":{"type":"object","properties":{"name":{"type":"string","maxLength":255},"email":{"type":"string","maxLength":150,"format":"email"},"countryCode":{"type":"string","maxLength":4},"phone":{"type":"string","maxLength":11,"pattern":"^\\d{10,11}$"},"alternativeEmail":{"type":"string","maxLength":150,"format":"email"},"address":{"$ref":"#/components/schemas/AddressSellerClientRequest"}}},"AddressSellerClientRequest":{"type":"object","properties":{"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"district":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"zipCode":{"type":"string"}}},"BuyerV2Response":{"type":"object","properties":{"uuid":{"type":"string"},"document":{"type":"string"},"name":{"type":"string"},"countryCode":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"alternativeEmail":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ErrorDetail":{"type":"object","properties":{"status":{"type":"string"},"code":{"type":"string","enum":["PAYMENT-0000","PAYMENT-0500","PAYMENT-9999","BAR-7001","BAD_REQUEST","FORBIDDEN","METHOD_NOT_ALLOWED","NOT_ACCEPTABLE","UNSUPPORTED_MEDIA_TYPE"]},"title":{"type":"string","enum":["BUSINESS_SELLER","BUSINESS_CHECKOUT","BUSINESS_COMMON","BUSINESS_SECURITY","BUSINESS_SUBSCRIPTION","INVALID_REQUEST_PARAM","BUSINESS_METRIC","BUSINESS_ACCOUNTANCY","BUSINESS_NOTIFICATION","BUSINESS_BARTE","BUSINESS_COMPANY","BUSINESS_INVOICE","BUSINESS_TRANSFER","BUSINESS_CARD","BUSINESS_ORDER","card_not_supported"]},"description":{"type":"string"},"action":{"type":"string"},"additionalInfo":{"type":"object","additionalProperties":{"type":"object"}}}},"Metadata":{"type":"object","properties":{"totalRecords":{"type":"integer"},"totalPages":{"type":"integer"},"requestDatetime":{"type":"string","format":"date-time"}}}}},"paths":{"/v2/buyers/{uuid}":{"put":{"tags":["API v2 para criação de buyers"],"summary":"Atualiza um buyer por seu UUUID","description":"Atualiza os dados de um buyer específico com base no UUID fornecido.","operationId":"updateBuyerByUuid","parameters":[{"name":"uuid","in":"path","description":"UUID do buyer","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Dados do buyer a serem atualizados","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBuyerV2Request"}}}},"responses":{"200":{"description":"buyer atualizado com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerV2Response"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Acesso proibido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"buyer não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
# Listar Compradores
## Lista buyers
> Retorna uma lista de buyers com base nos parâmetros de consulta fornecidos.
```json
{"openapi":"3.0.3","info":{"title":"API de Buyers","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de Produção"},{"url":"https://sandbox-api.barte.com","description":"Servidor de Sandbox"}],"security":[{"X-Token-Api":[]}],"components":{"securitySchemes":{"X-Token-Api":{"type":"apiKey","name":"X-Token-Api","in":"header"}},"schemas":{"BuyerV2Response":{"type":"object","properties":{"uuid":{"type":"string"},"document":{"type":"string"},"name":{"type":"string"},"countryCode":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"alternativeEmail":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ErrorDetail":{"type":"object","properties":{"status":{"type":"string"},"code":{"type":"string","enum":["PAYMENT-0000","PAYMENT-0500","PAYMENT-9999","BAR-7001","BAD_REQUEST","FORBIDDEN","METHOD_NOT_ALLOWED","NOT_ACCEPTABLE","UNSUPPORTED_MEDIA_TYPE"]},"title":{"type":"string","enum":["BUSINESS_SELLER","BUSINESS_CHECKOUT","BUSINESS_COMMON","BUSINESS_SECURITY","BUSINESS_SUBSCRIPTION","INVALID_REQUEST_PARAM","BUSINESS_METRIC","BUSINESS_ACCOUNTANCY","BUSINESS_NOTIFICATION","BUSINESS_BARTE","BUSINESS_COMPANY","BUSINESS_INVOICE","BUSINESS_TRANSFER","BUSINESS_CARD","BUSINESS_ORDER","card_not_supported"]},"description":{"type":"string"},"action":{"type":"string"},"additionalInfo":{"type":"object","additionalProperties":{"type":"object"}}}},"Metadata":{"type":"object","properties":{"totalRecords":{"type":"integer"},"totalPages":{"type":"integer"},"requestDatetime":{"type":"string","format":"date-time"}}}}},"paths":{"/v2/buyers":{"get":{"tags":["API v2 para criação de buyers"],"summary":"Lista buyers","description":"Retorna uma lista de buyers com base nos parâmetros de consulta fornecidos.","operationId":"listBuyers","parameters":[{"name":"document","in":"query","description":"Documento do buyer","schema":{"type":"string"}},{"name":"email","in":"query","description":"Email do buyer","schema":{"type":"string"}},{"name":"name","in":"query","description":"Nome do buyer","schema":{"type":"string"}},{"name":"page","in":"query","description":"Número da página para paginação","schema":{"type":"integer","default":0}},{"name":"size","in":"query","description":"Tamanho da página para paginação","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Lista de buyers recuperada com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/BuyerV2Response"}},"totalElements":{"type":"integer"},"totalPages":{"type":"integer"},"page":{"type":"integer"},"size":{"type":"integer"}}}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Acesso proibido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
# Buscar Comprador
## Recupera um buyer por UUID
> Retorna os detalhes de um buyer específico com base no UUID fornecido.
```json
{"openapi":"3.0.3","info":{"title":"API de Buyers","version":"2.0.0"},"servers":[{"url":"https://api.barte.com","description":"Servidor de Produção"},{"url":"https://sandbox-api.barte.com","description":"Servidor de Sandbox"}],"security":[{"X-Token-Api":[]}],"components":{"securitySchemes":{"X-Token-Api":{"type":"apiKey","name":"X-Token-Api","in":"header"}},"schemas":{"BuyerDetailV2Response":{"type":"object","properties":{"uuid":{"type":"string"},"document":{"type":"string"},"name":{"type":"string"},"countryCode":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"alternativeEmail":{"type":"string"},"address":{"$ref":"#/components/schemas/AddressResponse"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AddressResponse":{"type":"object","properties":{"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"district":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"zipCode":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"ErrorDetail":{"type":"object","properties":{"status":{"type":"string"},"code":{"type":"string","enum":["PAYMENT-0000","PAYMENT-0500","PAYMENT-9999","BAR-7001","BAD_REQUEST","FORBIDDEN","METHOD_NOT_ALLOWED","NOT_ACCEPTABLE","UNSUPPORTED_MEDIA_TYPE"]},"title":{"type":"string","enum":["BUSINESS_SELLER","BUSINESS_CHECKOUT","BUSINESS_COMMON","BUSINESS_SECURITY","BUSINESS_SUBSCRIPTION","INVALID_REQUEST_PARAM","BUSINESS_METRIC","BUSINESS_ACCOUNTANCY","BUSINESS_NOTIFICATION","BUSINESS_BARTE","BUSINESS_COMPANY","BUSINESS_INVOICE","BUSINESS_TRANSFER","BUSINESS_CARD","BUSINESS_ORDER","card_not_supported"]},"description":{"type":"string"},"action":{"type":"string"},"additionalInfo":{"type":"object","additionalProperties":{"type":"object"}}}},"Metadata":{"type":"object","properties":{"totalRecords":{"type":"integer"},"totalPages":{"type":"integer"},"requestDatetime":{"type":"string","format":"date-time"}}}}},"paths":{"/v2/buyers/{uuid}":{"get":{"tags":["API v2 para recuperação de buyers"],"summary":"Recupera um buyer por UUID","description":"Retorna os detalhes de um buyer específico com base no UUID fornecido.","operationId":"getBuyerByUuid","parameters":[{"name":"uuid","in":"path","description":"UUID do buyer","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"buyer recuperado com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerDetailV2Response"}}}},"401":{"description":"Não autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Acesso proibido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"buyer não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
# Criar Pedido
{% openapi src="/files/PKgWzb0jHKYWKAl6hGAO" path="/v2/orders" method="post" %}
[orders.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-cf422825efaf7f05954b2a7898501cff722e5124%2Forders.yaml?alt=media)
{% endopenapi %}
# Buscar Pedido
{% openapi src="/files/PKgWzb0jHKYWKAl6hGAO" path="/v2/orders/{uuid}" method="get" %}
[orders.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-cf422825efaf7f05954b2a7898501cff722e5124%2Forders.yaml?alt=media)
{% endopenapi %}
# Atualizar Descrição do Pedido
{% openapi src="/files/PKgWzb0jHKYWKAl6hGAO" path="/v2/orders/{uuid}" method="patch" %}
[orders.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-cf422825efaf7f05954b2a7898501cff722e5124%2Forders.yaml?alt=media)
{% endopenapi %}
# Cancelar Pedido
{% openapi src="/files/PKgWzb0jHKYWKAl6hGAO" path="/v2/orders/{uuid}" method="delete" %}
[orders.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-cf422825efaf7f05954b2a7898501cff722e5124%2Forders.yaml?alt=media)
{% endopenapi %}
# Listar Pedidos
{% openapi src="/files/PKgWzb0jHKYWKAl6hGAO" path="/v2/orders" method="get" %}
[orders.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-cf422825efaf7f05954b2a7898501cff722e5124%2Forders.yaml?alt=media)
{% endopenapi %}
# Simular Parcelamento
{% openapi src="/files/PKgWzb0jHKYWKAl6hGAO" path="/v2/orders/installments-payment" method="get" %}
[orders.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-cf422825efaf7f05954b2a7898501cff722e5124%2Forders.yaml?alt=media)
{% endopenapi %}
# Cobranças
# Buscar Cobrança
{% openapi src="/files/27DhkZaWrlPgRGphMFmZ" path="/v2/charges/{uuid}" method="get" %}
[v2-charges-14-10-25-23-12.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-e3e7d4c9222a461746185a96a4a9484774d1a637%2Fv2-charges-14-10-25-23-12.yaml?alt=media)
{% endopenapi %}
# Cancelar Cobrança
{% openapi src="/files/27DhkZaWrlPgRGphMFmZ" path="/v2/charges/{uuid}" method="delete" %}
[v2-charges-14-10-25-23-12.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-e3e7d4c9222a461746185a96a4a9484774d1a637%2Fv2-charges-14-10-25-23-12.yaml?alt=media)
{% endopenapi %}
# Listar Cobranças
{% openapi src="/files/27DhkZaWrlPgRGphMFmZ" path="/v2/charges" method="get" %}
[v2-charges-14-10-25-23-12.yaml](https://1326398544-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhY03QzfTvLWOjOsYfPiz%2Fuploads%2Fgit-blob-e3e7d4c9222a461746185a96a4a9484774d1a637%2Fv2-charges-14-10-25-23-12.yaml?alt=media)
{% endopenapi %}
---
[Next Page](/llms-full.txt/1)