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

# Transações

> Gerencie e consulte transações de pagamento com PIX, cartão e boleto. Acompanhe status, histórico e detalhes completos

## Visão geral

As **Transações** representam todas as operações de pagamento realizadas através da Alpa Gateway API. Cada transação contém informações completas sobre o pagamento, incluindo método utilizado, status, valores e dados do cliente.

## Pré-requisitos

Antes de começar, você precisa:

* Uma conta ativa na Alpa
* Sua API Key configurada (veja [Autenticação](/authentication))
* Conhecimento básico de APIs REST

## Funcionalidades

* **Múltiplos métodos de pagamento**: PIX, Cartão de Crédito/Débito, Boleto
* **Rastreamento em tempo real**: Acompanhe o status de cada transação
* **Histórico completo**: Consulte todas as transações com paginação
* **Detalhes do cliente**: Informações completas do pagador
* **Webhooks**: Receba notificações automáticas de mudanças de status
* **Filtros avançados**: Busque por status, método de pagamento, período e mais

## Criando uma transação

### Requisição Básica - PIX

```bash theme={null}
curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/transactions" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Pedido #001",
    "paymentMethod": "PIX",
    "amountCents": 9900,
    "clientName": "João Silva",
    "clientEmail": "joao@example.com",
    "clientPhone": "11999999999",
    "clientDocument": "12345678900"
  }'
```

### Resposta

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "displayId": "52a8d85b-160b-4f06-b7cb-34845c1955f2",
    "amountCents": 9900,
    "amount": 99.00,
    "currency": "BRL",
    "paymentMethod": "PIX",
    "status": "PENDING",
    "pixCopiaECola": "00020101021226940014br.gov.bcb.pix...",
    "pixExpiresAt": "2025-12-30T01:00:00-03:00",
    "client": {
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "11999999999",
      "document": "12345678900"
    },
    "createdAt": "2025-12-30T00:00:00.000Z"
  }
}
```

<Note>
  O campo `displayId` é preenchido com o ID externo gerado pela adquirente após o processamento. O campo `pixCopiaECola` contém o código PIX copia-e-cola pronto para uso.
</Note>

## Campos disponíveis

### Campos obrigatórios

| Campo            | Tipo   | Descrição                                                    |
| ---------------- | ------ | ------------------------------------------------------------ |
| `product`        | string | Nome ou descrição do produto/serviço. Máximo 255 caracteres. |
| `amountCents`    | number | Valor em centavos. Exemplo: 9900 = R\$ 99,00.                |
| `clientName`     | string | Nome completo do cliente. Máximo 255 caracteres.             |
| `clientEmail`    | string | Email válido do cliente.                                     |
| `clientDocument` | string | CPF ou CNPJ do cliente (apenas números). Mínimo 11 dígitos.  |

### Campos opcionais

| Campo            | Tipo              | Descrição                                                        | Padrão  |
| ---------------- | ----------------- | ---------------------------------------------------------------- | ------- |
| `paymentMethod`  | string            | Método de pagamento: `"PIX"`, `"CARD"`, `"BOLETO"`.              | `"PIX"` |
| `clientPhone`    | string            | Telefone do cliente (apenas números). Exemplo: `11999999999`.    | —       |
| `installments`   | number            | Número de parcelas (apenas cartão). Mínimo: 1, Máximo: 12.       | 1       |
| `paymentLinkId`  | string (UUID)     | ID do link de pagamento associado.                               | —       |
| `dueDate`        | string (ISO 8601) | Data de vencimento da cobrança.                                  | —       |
| `metadata`       | object            | Dados adicionais personalizados (ex: `orderId`, `source`).       | —       |
| `postbackUrl`    | string (URL)      | URL para receber notificações de mudança de status da transação. | —       |
| `trackingParams` | object            | Parâmetros UTM para rastreamento de campanhas.                   | —       |

## 📖 Exemplos Completos

### Transação com Cartão de Crédito

```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    product: 'Curso Online',
    paymentMethod: 'CARD',
    amountCents: 19900, // R$ 199,00
    installments: 3,
    clientName: 'Maria Santos',
    clientEmail: 'maria@example.com',
    clientPhone: '11988888888',
    clientDocument: '98765432100'
  })
});
```

### Transação com Boleto

```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    product: 'Assinatura Mensal',
    paymentMethod: 'BOLETO',
    amountCents: 29900, // R$ 299,00
    clientName: 'Pedro Oliveira',
    clientEmail: 'pedro@example.com',
    clientPhone: '11977777777',
    clientDocument: '12345678900'
  })
});
```

### Transação com Metadata (integração de parceiros)

```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    product: 'Pedido #4836572',
    paymentMethod: 'PIX',
    amountCents: 670000, // R$ 6.700,00
    clientName: 'Ana Costa',
    clientEmail: 'ana@example.com',
    clientPhone: '11966666666',
    clientDocument: '11122233344',
    metadata: {
      orderId: '4836572',
      source: 'checkout-parceiro',
      campaign: 'black-friday'
    }
  })
});
```

## Consultando transações

### Listar Todas as Transações

```bash theme={null}
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/transactions?page=1&limit=20" \
  -H "Authorization: Bearer SUA_API_KEY"
```

### Resposta

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "displayId": "TRX-2025-001234",
      "amountCents": 9900,
      "amount": 99.00,
      "currency": "BRL",
      "paymentMethod": "PIX",
      "status": "COMPLETED",
      "client": {
        "name": "João Silva",
        "email": "joao@example.com"
      },
      "createdAt": "2025-12-30T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
```

### Buscar Transação Específica

```bash theme={null}
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/transactions/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"
```

### Filtros Disponíveis

```bash theme={null}
# Filtrar por status
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/transactions?status=COMPLETED" \
  -H "Authorization: Bearer SUA_API_KEY"

# Filtrar por método de pagamento
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/transactions?paymentMethod=PIX" \
  -H "Authorization: Bearer SUA_API_KEY"

# Filtrar por período
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/transactions?startDate=2025-01-01&endDate=2025-12-31" \
  -H "Authorization: Bearer SUA_API_KEY"

# Combinar filtros
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/transactions?status=COMPLETED&paymentMethod=PIX&page=1&limit=50" \
  -H "Authorization: Bearer SUA_API_KEY"
```

## 📊 Status da Transação

| Status       | Descrição             | Ação                    |
| ------------ | --------------------- | ----------------------- |
| `PENDING`    | Aguardando pagamento  | Aguardar confirmação    |
| `PROCESSING` | Processando pagamento | Aguardar processamento  |
| `COMPLETED`  | Pagamento confirmado  | Liberar produto/serviço |
| `FAILED`     | Pagamento falhou      | Tentar novamente        |
| `CANCELLED`  | Transação cancelada   | Criar nova transação    |
| `REFUNDED`   | Pagamento reembolsado | Registrar reembolso     |
| `EXPIRED`    | Transação expirada    | Criar nova transação    |

## Métodos de pagamento

### PIX

* **Tempo de expiração**: 30 minutos (padrão)
* **Confirmação**: Instantânea
* **Retorno**: Código copia-e-cola e data de expiração
* **Webhook**: `transaction.completed` quando confirmado

```json theme={null}
{
  "pixCopiaECola": "00020101021226940014br.gov.bcb.pix...",
  "pixExpiresAt": "2025-12-30T01:00:00-03:00"
}
```

### Cartão de Crédito

* **Parcelamento**: Até 12x
* **Confirmação**: Imediata ou em até 2 dias úteis
* **Retorno**: Status da autorização
* **Webhook**: `transaction.completed` ou `transaction.failed`

### Cartão de Débito

* **Parcelamento**: Não disponível
* **Confirmação**: Imediata
* **Retorno**: Status da autorização
* **Webhook**: `transaction.completed` ou `transaction.failed`

### Boleto

* **Vencimento**: 3 dias úteis (padrão)
* **Confirmação**: 1-3 dias úteis após pagamento
* **Retorno**: URL do boleto e código de barras
* **Webhook**: `transaction.completed` quando compensado

```json theme={null}
{
  "boletoUrl": "https://boleto.usealpa.com/...",
  "boletoBarcode": "34191.79001 01043.510047 91020.150008 1 84350000002000",
  "boletoExpiresAt": "2025-01-02T23:59:59.000Z"
}
```

## Postback URL

Se você prefere receber notificações de status por transação sem precisar cadastrar uma assinatura de webhook global, use o campo `postbackUrl` na criação da transação.

Quando o status mudar para `COMPLETED` ou `FAILED`, a Alpa enviará automaticamente um `POST` para a URL informada com o seguinte payload:

```json theme={null}
{
  "id": "5e1f52d9-1477-414c-a113-38dd87290ede",
  "displayId": "52a8d85b-160b-4f06-b7cb-34845c1955f2",
  "status": "COMPLETED",
  "amountCents": 9900,
  "amount": 99.00,
  "currency": "BRL",
  "paymentMethod": "PIX",
  "product": "Pedido #001",
  "client": {
    "name": "João Silva",
    "email": "joao@example.com",
    "document": "12345678900",
    "phone": "11999999999"
  },
  "createdAt": "2025-12-30T00:00:00.000Z",
  "updatedAt": "2025-12-30T00:01:00.000Z"
}
```

O cabeçalho `X-Webhook-Signature` é enviado com assinatura HMAC-SHA256 para validação de autenticidade (mesmo formato dos [webhooks](/pages/guides/features/webhooks#validando-a-assinatura)). Seu endpoint deve responder com status `2xx` para confirmar o recebimento.

```bash theme={null}
curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/transactions" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Pedido #001",
    "amountCents": 9900,
    "clientName": "João Silva",
    "clientEmail": "joao@example.com",
    "clientDocument": "12345678900",
    "postbackUrl": "https://meusite.com.br/postback/alpa"
  }'
```

## 🔔 Webhooks

Configure webhooks para receber notificações automáticas sobre mudanças de status:

```javascript theme={null}
// Eventos disponíveis
const events = [
  'transaction.completed', // Pagamento confirmado
  'transaction.failed',    // Pagamento falhou
  'transaction.created',   // Transação criada
  'transaction.updated',   // Status atualizado
];
```

Veja o [guia completo de webhooks](/pages/guides/features/webhooks) para mais detalhes.

## Segurança

### Validação de Dados

Sempre valide os dados antes de criar uma transação:

```javascript theme={null}
function validateTransaction(data) {
  // Validar valor mínimo
  if (data.amountCents < 100) {
    throw new Error('Valor mínimo: R$ 1,00');
  }
  
  // Validar email
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(data.client.email)) {
    throw new Error('Email inválido');
  }
  
  // Validar CPF/CNPJ
  if (!isValidDocument(data.client.document)) {
    throw new Error('CPF/CNPJ inválido');
  }
  
  return true;
}
```

### Proteção contra Duplicatas

Use `metadata` para rastrear transações e evitar duplicatas:

```javascript theme={null}
const transaction = await alpa.transactions.create({
  // ... outros campos
  metadata: {
    orderId: 'ORD-2025-001',
    idempotencyKey: generateUniqueKey()
  }
});
```

## Boas práticas

1. **Sempre use webhooks**: Não confie apenas em polling para verificar status
2. **Armazene o ID da transação**: Guarde o `id` e `displayId` no seu banco de dados
3. **Trate erros adequadamente**: Implemente retry com backoff exponencial
4. **Valide dados do cliente**: Verifique CPF/CNPJ, email e telefone antes de enviar
5. **Use metadata**: Armazene informações adicionais para rastreamento
6. **Monitore expiração**: PIX expira em 30 minutos, boleto em 3 dias
7. **Implemente timeout**: Configure timeout adequado nas requisições

## Casos de uso

### E-commerce

Processe pagamentos de produtos com múltiplos métodos e parcelamento.

### Assinaturas

Crie transações recorrentes para cobranças mensais.

### Marketplace

Gerencie transações entre múltiplos vendedores.

### Doações

Aceite doações via PIX com confirmação instantânea.

### Serviços

Cobre por serviços prestados com boleto ou cartão.

## 📚 Próximos Passos

<CardGroup cols={2}>
  <Card title="Referência da API" icon="code" href="/pages/transactions/reference">
    Veja todos os endpoints disponíveis
  </Card>

  <Card title="Links de pagamento" icon="link" href="/pages/guides/features/payment-links">
    Crie links para receber pagamentos
  </Card>

  <Card title="Webhooks" icon="bell" href="/pages/guides/features/webhooks">
    Configure notificações em tempo real
  </Card>
</CardGroup>