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

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

{
  "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. 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

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

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

Criar Pedido com Token do Cartão

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

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

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

Criar Pedido

PreviousPedido com Pré-captura NextPedido com 3DS (3D Secure)

Last updated 5 months ago

Was this helpful?