> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payments.bob.company/llms.txt
> Use this file to discover all available pages before exploring further.

# Transação de cartão

> Estrutura e atributos de uma transação de cartão de crédito na API Bob Payments

<Note>
  **Em breve.** O pagamento com cartão de crédito ainda não está disponível na Bob. Esta referência descreve a estrutura que a API vai retornar quando lançar — por enquanto, use **PIX**.
</Note>

Para aceitar cartão de crédito você **não** envia os dados do cartão para a API Bob. O número do cartão, CVV e validade são coletados e tokenizados no navegador pelo pacote de checkout da Bob (`@bobpayments/checkout-sdk`) — a sua aplicação e a API só recebem um token seguro.

<Warning>
  Nunca envie cartão bruto (PAN, CVV ou validade) para a API Bob. Use o pacote de checkout JS da Bob para tokenizar o cartão no browser. Veja o [SDK Checkout](/pages/sdk/checkout).
</Warning>

## Estrutura

Uma transação de cartão de crédito é representada pela seguinte estrutura:

```json theme={"system"}
{
  "id": "clx7a8b9c0d1e2f3g4h5",
  "externalId": "pedido_123",
  "amountCents": 25000,
  "product": "Assinatura Pro",
  "paymentMethod": "credit_card",
  "status": "paid",
  "card": {
    "brand": "visa",
    "last4": "4242"
  },
  "customerEmail": "joao@email.com",
  "customerName": "João Silva",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678900"
  },
  "createdAt": "2026-02-28T09:00:00.000Z",
  "updatedAt": "2026-02-28T09:00:00.000Z"
}
```

## Atributos

<ResponseField name="id" type="string">
  Identificador único da transação no formato CUID.
</ResponseField>

<ResponseField name="externalId" type="string">
  Identificador da transação no seu sistema. Use para cruzar dados sem armazenar o `id` interno. Deve ser único por projeto.
</ResponseField>

<ResponseField name="amountCents" type="integer">
  Valor da transação em centavos. Exemplo: `25000` = R\$ 250,00.
</ResponseField>

<ResponseField name="product" type="string">
  Nome ou descrição do produto/serviço cobrado.
</ResponseField>

<ResponseField name="paymentMethod" type="string">
  Método de pagamento da transação. Para cartão, o valor é `credit_card`. A Bob gerencia internamente o processamento da tentativa.
</ResponseField>

<ResponseField name="status" type="string">
  Status atual da transação.

  <Note>
    | Status            | Descrição                                                 |
    | ----------------- | --------------------------------------------------------- |
    | `pending`         | **Transação criada, ainda sem confirmação final**         |
    | `waiting_payment` | **Aguardando autenticação 3DS ou confirmação assíncrona** |
    | `paid`            | **Pagamento aprovado**                                    |
    | `failed`          | **O processamento não foi concluído**                     |
    | `refunded`        | **O valor foi devolvido ao cliente**                      |
    | `cancelled`       | **A transação foi cancelada**                             |
  </Note>

  Não considere apenas o HTTP `201` como confirmação de pagamento — use webhook e/ou consulta de status para confirmar o desfecho financeiro.
</ResponseField>

<ResponseField name="card" type="object | null">
  Dados de exibição do cartão, seguros para armazenar e mostrar ao comprador. `brand` é a bandeira e `last4` são os quatro últimos dígitos. **PAN, CVV e validade nunca são retornados** — o cartão é tokenizado no browser pelo pacote de checkout da Bob.
</ResponseField>

<ResponseField name="customerEmail" type="string | null">
  E-mail do comprador. Atalho direto ao campo `customer.email`, disponível no nível raiz da transação.
</ResponseField>

<ResponseField name="customerName" type="string | null">
  Nome do comprador. Atalho direto ao campo `customer.name`, disponível no nível raiz da transação.
</ResponseField>

<ResponseField name="customer" type="object">
  Dados do comprador vinculado à transação. Consulte a [entidade Customer](/pages/customers/reference).
</ResponseField>

<ResponseField name="createdAt" type="date-time">
  Data e hora de criação da transação.
</ResponseField>

<ResponseField name="updatedAt" type="date-time">
  Data e hora da última atualização.
</ResponseField>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Cartão de crédito" icon="credit-card" href="/pages/credit-card/overview">
    Modos de integração, tokenização via SDK e configuração de rota.
  </Card>

  <Card title="SDK Checkout" icon="browser" href="/pages/sdk/checkout">
    Tokenize o cartão no navegador sem tocar em PAN ou CVV.
  </Card>
</CardGroup>