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

# Transações

> Como criar, consultar, capturar, cancelar e exportar transações.

Transações representam pagamentos avulsos processados pela Veepag. Use este fluxo quando você precisa cobrar um cliente diretamente, consultar o histórico de pagamentos, capturar uma autorização ou cancelar/estornar uma operação.

## Criar uma transação

`POST /v1/transaction` cria uma transação avulsa. Para pagamento com cartão, envie os dados em `paymentProfile`: número, validade, nome do portador e, quando necessário, CVV.

No exemplo abaixo, criamos uma transação no sandbox com um cliente informado no próprio payload.

```bash theme={null}
curl --request POST 'https://sandbox.api.veepag.com/v1/transaction' \
  --header 'apiKey: keyId.secret' \
  --header 'Content-Type: application/json' \
  --data '{
    "companyId": "company_id",
    "amount": 9900,
    "installments": 1,
    "capture": true,
    "paymentProfile": {
      "cardNumber": "4111111111111111",
      "cardExpiration": "10/2026",
      "holderName": "MARIA SILVA",
      "cardCvv": "123"
    },
    "client": {
      "name": "Maria Silva",
      "doc": "12345678909",
      "email": "maria.silva@example.com"
    }
  }'
```

<Note>
  Em transações, envie `amount` em centavos. Por exemplo, `9900` representa R\$ 99,00.
</Note>

## Consultar transações

`GET /v1/transaction` retorna um objeto paginado. Ele é indicado para telas administrativas, conciliação e buscas operacionais.

Use `rangeTime` com `sort.property` para filtros temporais. Isso deixa a consulta mais clara e ajuda a evitar buscas amplas demais.

```bash theme={null}
curl --request GET 'https://sandbox.api.veepag.com/v1/transaction?page=1&limit=20&sort.property=createdAt&sort.order=desc' \
  --header 'apiKey: keyId.secret'
```

`GET /v2/transaction` retorna um array direto, sem paginação. Ele exige `companyId` e um filtro por período de até 7 dias ou um identificador (`id` ou `tid`).

## Capturar uma autorização

`POST /v1/transaction/capture` captura uma transação previamente autorizada. Use esse endpoint quando o pagamento foi autorizado antes, mas a captura ficou para uma etapa posterior.

A captura usa o valor salvo na própria transação (`transaction.amount.value`). O campo `amount` existe no DTO, mas não é usado pelo fluxo atual de captura.

```json theme={null}
{
  "companyId": "company_id",
  "transactionId": "transaction_id"
}
```

Também é aceito `tid`. Pelo menos um identificador é necessário em runtime.

## Cancelar uma transação

`PUT /v1/transaction/cancel` cancela ou estorna uma transação.

```json theme={null}
{
  "companyId": "company_id",
  "transactionId": "transaction_id",
  "cancelSubscription": false
}
```

Se `cancelSubscription` for `true`, a assinatura vinculada também pode ser cancelada. Use essa opção com cuidado quando a transação fizer parte de uma recorrência.

## Exportar transações

`GET /v1/transaction/exports` exporta até 10.000 itens. Se o filtro exceder esse limite, reduza o período ou refine os filtros.

<Tip>
  Para exportações grandes, prefira períodos menores. Isso melhora o tempo de resposta e facilita conferir os dados depois.
</Tip>