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/cardsHeaders
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çafalse: não realiza a validação zero-dólar
Response
⚠️ 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:
Observações importantes
O token retornado representa o cartão de forma segura
O status
ACTIVEindica que o cartão está pronto para usoO 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
checkZeroDollarnão seja realizado, a tokenização será criada com statusPENDINGe será automaticamente atualizada paraACTIVEapó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 leva o cardToken e, quando o portador está presente, o cvv. Em cobranças feitas sem o portador presente, não envie o cvv e declare o storedCredential, como em Cobranças com cartão salvo.
⚠️ 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 leva o cardToken e o cvv.
Endpoint
Headers
Body
Response
📌 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 confirmadoSENT→ cobrança criada e aguardando pagamentoCANCELED→ pedido canceladoFAILED→ 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:
Confirmação do pagamento
Após a criação de um pedido:
A API pode retornar o pedido como
PAIDde forma síncronaMesmo 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:
uuiddo pedidouuidda 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
metadatapara 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
Last updated
Was this helpful?

