# Pedido com Cartão Tokenizado
***
### 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.md). 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.md)
{% 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.md)
{% endcontent-ref %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.barte.com/guias/passo-a-passo-do-vendedor/2o-criando-pedidos-or-links-de-pagamento-or-assinaturas/pedidos/pedido-com-cartao-tokenizado.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.