> ## 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.

# Consultar transação

> Corpo completo de resposta ao consultar uma transação pelo ID

# Consultar Transação

> Recupere os dados completos e o status atual de uma transação pelo seu ID

## 🛠️ Endpoint

```text theme={null}
GET /api/v1/transactions/{id}
```

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

### Exemplo

```bash theme={null}
curl -X GET 'https://api.velfy.com/api/v1/transactions/918234' \
  -u "sk_xxx:pk_xxx"
```

## 📥 Corpo da Resposta

```json theme={null}
{
  "success": true,
  "status": 200,
  "data": {
    "id": 918234,
    "status": "paid",
    "amount": 10000,
    "companyId": 42,
    "installments": 1,
    "paidAmount": 10000,
    "refundedAmount": 0,
    "paymentMethod": "pix",
    "metadata": null,
    "acquirerType": "woovi",
    "secureId": "9c1a9b2e-7c3d-4e11-9a2f-3a1c5f0e9d21",
    "secureUrl": "https://pay.velfy.com/checkout/9c1a9b2e-7c3d-4e11-9a2f-3a1c5f0e9d21",
    "externalId": "pedido-123",
    "customer": {
      "name": "João da Silva",
      "email": "joao@example.com",
      "phone": "11999998888",
      "externalRef": null,
      "document": { "number": "12345678900", "type": "cpf" }
    },
    "shipping": null,
    "pix": {
      "qrcode": "00020126580014br.gov.bcb.pix0136...6304ABCD",
      "expirationDate": "2026-07-30T12:00:00.000Z"
    },
    "traceable": false,
    "createdAt": "2026-07-28T12:00:00.000Z"
  }
}
```

### Campos da Resposta

| Campo            | Tipo             | Descrição                                                                                            |
| ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| `id`             | `number`         | Identificador da transação                                                                           |
| `status`         | `string`         | Status atual — veja a [tabela de status](/api-reference/payments/transactions#status-poss%C3%ADveis) |
| `amount`         | `number`         | Valor total, em centavos                                                                             |
| `companyId`      | `number`         | Identificador da empresa/conta                                                                       |
| `installments`   | `number`         | Número de parcelas (cartão)                                                                          |
| `paidAmount`     | `number`         | Valor pago, em centavos                                                                              |
| `refundedAmount` | `number`         | Valor estornado, em centavos                                                                         |
| `paymentMethod`  | `string`         | `pix`, `credit_card` ou `boleto`                                                                     |
| `metadata`       | `string \| null` | Valor enviado em `metadata` na criação                                                               |
| `acquirerType`   | `string`         | Adquirente/processador usado internamente                                                            |
| `secureId`       | `string`         | Identificador do checkout hospedado                                                                  |
| `secureUrl`      | `string`         | Página de checkout hospedada pela Velfy para esta transação                                          |
| `externalId`     | `string`         | Valor enviado em `externalRef` na criação                                                            |
| `customer`       | `object`         | Dados do pagador (`name`, `email`, `phone`, `document`)                                              |
| `shipping`       | `object \| null` | Endereço, frete e status de entrega, quando aplicável                                                |
| `pix`            | `object`         | Presente apenas para transações PIX (`qrcode`, `expirationDate`)                                     |
| `traceable`      | `boolean`        | Se a transação está marcada como rastreável                                                          |
| `createdAt`      | `string`         | Data de criação (ISO 8601)                                                                           |

<Info>
  Transações de **boleto** não retornam o objeto `pix` — os dados do boleto (`url`, `barcode`, `digitableLine`) são retornados apenas na resposta de criação. Use o [webhook](/api-reference/payments/webhooks) ou o `status` para acompanhar a compensação.
</Info>

## ❗ Erros

| Status HTTP | Quando acontece                                   |
| ----------- | ------------------------------------------------- |
| `401`       | Credenciais inválidas ou ausentes                 |
| `404`       | Transação não encontrada para a conta autenticada |

***

## 🎯 Próximos Passos

<CardGroup cols={2}>
  <Card title="📝 Criando Transações" color="#631286" icon="rectangle-list" href="/api-reference/payments/transactions">
    Veja os campos de criação de cobrança
  </Card>

  <Card title="🔗 Webhooks" color="#631286" icon="webhook" href="/api-reference/payments/webhooks">
    Receba atualizações de status automaticamente
  </Card>
</CardGroup>