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

# Criando transações

> Visão geral do endpoint de criação de cobranças (PIX, cartão e boleto)

# Criando Transações

> Um único endpoint para cobrar via PIX, cartão de crédito ou boleto

Toda cobrança na Velfy Payments é criada através do mesmo endpoint. O método de pagamento é definido pelo campo `paymentMethod` no corpo da requisição.

## 🚀 Como Funciona

<CardGroup cols={2}>
  <Card title="📤 Você cria a cobrança" color="#631286" icon="paper-plane">
    Envie os dados da venda e o método de pagamento desejado (`pix`, `credit_card` ou `boleto`)
  </Card>

  <Card title="💳 Cliente paga" color="#631286" icon="credit-card">
    O cliente paga via PIX, cartão ou boleto, conforme o método escolhido
  </Card>

  <Card title="⚡ Confirmação instantânea" color="#631286" icon="bolt">
    Você recebe a confirmação em tempo real via webhook
  </Card>

  <Card title="🔍 Consulte quando quiser" color="#631286" icon="magnifying-glass" href="/api-reference/payments/get-transaction">
    Use o endpoint de consulta para verificar o status a qualquer momento
  </Card>
</CardGroup>

## 🛠️ Endpoint

```text theme={null}
POST /api/v1/transactions
```

Autenticado via [Basic Auth](/api-reference/payments/authentication) com sua secret key e public key.

## 📊 Campos Comuns

Independente do método de pagamento, toda requisição compartilha estes campos:

### Campos Obrigatórios

| Campo                      | Tipo      | Descrição                                                |
| -------------------------- | --------- | -------------------------------------------------------- |
| `paymentMethod`            | `string`  | `pix`, `credit_card` ou `boleto`                         |
| `amount`                   | `number`  | Valor total da cobrança, em **centavos**                 |
| `customer`                 | `object`  | Dados do pagador                                         |
| `customer.name`            | `string`  | Nome completo                                            |
| `customer.email`           | `string`  | E-mail                                                   |
| `customer.document.type`   | `string`  | `cpf` ou `cnpj`                                          |
| `customer.document.number` | `string`  | Número do documento (somente dígitos)                    |
| `items`                    | `array`   | Itens da venda (mínimo 1)                                |
| `items[].title`            | `string`  | Nome do item                                             |
| `items[].unitPrice`        | `number`  | Preço unitário, em centavos                              |
| `items[].quantity`         | `number`  | Quantidade                                               |
| `items[].tangible`         | `boolean` | `true` para produto físico, `false` para digital/serviço |

### Campos Opcionais

| Campo            | Tipo     | Descrição                                                                                     |
| ---------------- | -------- | --------------------------------------------------------------------------------------------- |
| `customer.phone` | `string` | Telefone do cliente                                                                           |
| `shipping`       | `object` | Endereço e valor de frete                                                                     |
| `externalRef`    | `string` | Identificador da cobrança no seu sistema                                                      |
| `postbackUrl`    | `string` | URL para onde a Velfy enviará os [webhooks](/api-reference/payments/webhooks) desta transação |
| `metadata`       | `string` | Campo livre para informações adicionais                                                       |
| `ip`             | `string` | IP do comprador — **obrigatório para cartão de crédito**                                      |

## 💳 Métodos de Pagamento

Cada método adiciona campos específicos dentro de um objeto próprio (`pix`, `card` ou `boleto`):

<CardGroup cols={3}>
  <Card title="PIX" color="#631286" icon="qrcode" href="/api-reference/payments/pix">
    QR Code e copia e cola
  </Card>

  <Card title="Cartão de crédito" color="#631286" icon="credit-card" href="/api-reference/payments/credit-card">
    Tokenização e cobrança
  </Card>

  <Card title="Boleto" color="#631286" icon="barcode" href="/api-reference/payments/boleto">
    Boleto bancário
  </Card>
</CardGroup>

## 📥 Resposta

Toda chamada bem-sucedida retorna o mesmo envelope:

```json theme={null}
{
  "success": true,
  "message": "Transaction created",
  "status": 201,
  "data": { }
}
```

O conteúdo de `data` varia conforme o método de pagamento — veja exemplos completos em cada página específica.

## 📋 Status Possíveis

| Status              | Descrição                             |
| ------------------- | ------------------------------------- |
| `pending`           | Cobrança criada, aguardando pagamento |
| `processing`        | Pagamento em processamento            |
| `paid` / `approved` | Pagamento confirmado                  |
| `refused`           | Pagamento recusado                    |
| `refunded`          | Pagamento estornado                   |
| `chargedback`       | Chargeback recebido                   |
| `in_protest`        | Chargeback em contestação             |

<Info>
  Para ver o corpo completo de resposta e como consultar uma transação já criada, veja [Consultar transação](/api-reference/payments/get-transaction).
</Info>

***

## 🎯 Próximos Passos

<CardGroup cols={2}>
  <Card title="🔍 Consultar Transação" color="#631286" icon="magnifying-glass" href="/api-reference/payments/get-transaction">
    Veja o corpo completo de resposta do GET
  </Card>

  <Card title="🔗 Webhooks" color="#631286" icon="webhook" href="/api-reference/payments/webhooks">
    Configure notificações em tempo real
  </Card>
</CardGroup>