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

{
  "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"
    }
  ]
}

{
  "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"
    }
  ]
}

{
  "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"
    }
  ]
}

startDate é uma data no horário de Brasília (America/Sao_Paulo). A data de hoje cobra na hora, e uma data futura agenda a cobrança. Se o seu servidor ou a sua biblioteca usam UTC por padrão, converta antes de enviar: depois das 21h, a data UTC já é o dia seguinte e o pedido fica agendado para amanhã. Por exemplo, em JavaScript new Date().toISOString().slice(0, 10) devolve a data UTC. Para cobrar na hora, você também pode não enviar o campo.

Response

{
    "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"
        }
    ]
}

{
    "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"
        }
    ]
}

{
    "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"
        }
    ]
}

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

Criar Pedido

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.

Fluxo resumido

Você cria o pedido via API
A Barte processa a cobrança
O cliente realiza o pagamento
O status da transação é atualizado
Um webhook é enviado ao seu sistema
Seu sistema valida o evento e confirma o pagamento

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)

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
Enviar no startDate a data do servidor sem converter para o horário de Brasília
Expor sua chave de API no frontend

PreviousPedidos

NextPedido com Pré-captura

Last updated 1 day ago

Was this helpful?