# Autorizações e Capturas

Certos métodos de pagamento como cartão de crédito e MB WAY passam por duas fases distintas: *autorização* e *captura*. As nossas integrações permitem-lhe mover através delas separadamente (emitindo primeiro uma autorização de cartão e depois capturando os fundos) ou num único passo referido nas nossas APIs como `sale` (autorização seguida de captura).

## Compreender o Fluxo

### Autorização

A autorização é o primeiro passo do processo e envolve garantir que o comprador tem fundos ou crédito suficiente disponível para fazer o pagamento. Se sim, os fundos são retidos: o cliente não os pode usar para pagar outros bens ou serviços, mas ainda não foram transferidos para a conta do comerciante. Se o comerciante não capturar os fundos nos dias seguintes, a retenção é levantada.

**Pontos-Chave**:

- Verifica que o cliente tem fundos suficientes
- Retém fundos (ainda não transferidos)
- A retenção expira se não for capturada dentro do prazo
- Não ocorre movimento de dinheiro


**Casos de Uso**:

- Verificar método de pagamento antes de fornecer serviço
- Reter fundos para pedidos que são enviados mais tarde
- Reservar quantia para alugueres ou depósitos
- Implementar divisões/multi-capturas


### Captura

Uma captura é a transferência efetiva de fundos do comprador para o comerciante.

**Pontos-Chave**:

- Transfere dinheiro do cliente para o comerciante
- Pode ser parcial ou total
- Desencadeia o processamento final do pagamento


### Venda

Em muitas das nossas integrações, especificar `sale` como o tipo de operação executará automaticamente uma autorização e uma captura, transferindo imediatamente os fundos do cliente para o comerciante num único passo (se bem-sucedido).

**Pontos-Chave**:

- Pagamento de passo único
- Autorização + Captura combinadas
- Transferência imediata de fundos
- Implementação mais simples


## Quando Usar Cada Método

### Use Autorização + Captura Quando:

1. **Cumprimento Adiado**: Não envia produtos imediatamente

```
Exemplo: E-commerce com envio de 2-3 dias
- Dia 1: Autorizar pagamento quando pedido é feito
- Dia 3: Capturar quando item é enviado
```
2. **Negócios Baseados em Serviços**: Serviço é fornecido após reserva

```
Exemplo: Reserva de hotel
- Reserva: Autorizar para reter fundos
- Check-out: Capturar quantia real
```
3. **Quantia Final Variável**: Quantia final desconhecida na reserva

```
Exemplo: Aluguer de carro
- Autorizar quantia estimada
- Capturar quantia real baseada no uso
```


### Use Venda Quando:

1. **Produtos Digitais Imediatos**: Entrega instantânea

```
Exemplo: Subscrição SaaS, e-books, downloads digitais
```
2. **Transações Presenciais**: Ponto de venda

```
Exemplo: Loja física, restaurante
```
3. **Serviços Imediatos**: Serviço fornecido instantaneamente

```
Exemplo: Cursos online, acesso a streaming
```


## Métodos de Pagamento Suportados

| Método de Pagamento | Autorização | Captura | Venda |
|  --- | --- | --- | --- |
| Cartão de Crédito/Débito | ✅ | ✅ | ✅ |
| MB WAY | ✅ | ✅ | ✅ |
| Apple Pay | ✅ | ✅ | ✅ |
| Google Pay | ✅ | ✅ | ✅ |
| Samsung Pay | ✅ | ✅ | ✅ |
| Multibanco | ❌ | ❌ | ✅ |
| Débito Direto | ❌ | ❌ | ✅ |
| IBAN Virtual | ❌ | ❌ | ✅ |


## Exemplos de Implementação

### Venda de Passo Único


```bash
# Criar uma venda (autorização + captura num passo)
curl -X POST 'https://api.test.easypay.pt/2.0/single' \
  -H 'AccountId: SEU_ACCOUNT_ID' \
  -H 'ApiKey: SUA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "sale",
    "value": 50.00,
    "currency": "EUR",
    "method": "cc",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'
```

### Autorização e Captura em Dois Passos

**Passo 1: Autorizar o pagamento**


```bash
curl -X POST 'https://api.test.easypay.pt/2.0/single' \
  -H 'AccountId: SEU_ACCOUNT_ID' \
  -H 'ApiKey: SUA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "authorisation",
    "value": 100.00,
    "currency": "EUR",
    "method": "cc",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'
```

Resposta:


```json
{
  "status": "success",
  "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
  "method": "cc"
}
```

**Passo 2: Capturar os fundos autorizados**


```bash
curl -X POST 'https://api.test.easypay.pt/2.0/capture/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8' \
  -H 'AccountId: SEU_ACCOUNT_ID' \
  -H 'ApiKey: SUA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": 100.00
  }'
```

## Multi-Capturas

Também é possível emitir uma autorização para um valor que será posteriormente dividido entre diferentes capturas. Um exemplo é uma loja que suporta pagamentos divididos para pedidos de múltiplos fornecedores. A quantia total do pedido é autorizada mas as diferentes capturas podem ser emitidas em momentos diferentes, após cada fornecedor confirmar ou enviar os bens.

### Exemplo de Multi-Captura


```bash
# Passo 1: Autorizar a quantia total do pedido
POST /single
{
  "type": "authorisation",
  "value": 150.00,
  "method": "cc"
}

# Passo 2: Capturar para o produto A (quando enviam)
POST /capture/:id
{
  "value": 75.00,
  "descriptive": "Eletrónica"
}

# Passo 3: Capturar para o produto B (quando enviam)
POST /capture/:id
{
  "value": 75.00,
  "descriptive": "Livros"
}
```

## Períodos de Retenção de Autorização

O período de retenção de autorização varia por método de pagamento e emissor do cartão:

| Método de Pagamento | Período de Retenção Típico |
|  --- | --- |
| Cartão de Débito | 3-7 dias |
| MB WAY | 7 dias |


**Importante**: Capture sempre dentro do período de retenção, ou a autorização será automaticamente libertada.

## Capturas Parciais

Pode capturar menos do que a quantia autorizada:


```bash
# Autorizado: €100
# Capturar apenas €75
POST /capture/:id
{
  "value": 75.00
}
```

**Resultado**: €75 são capturados, autorização de €25 é libertada.

## Anular uma Autorização

Se precisar cancelar uma autorização antes de expirar:


```bash
POST /void/{authorization-id}
{
  "descriptive": "Cliente cancelou o pedido"
}
```

Isto liberta imediatamente a retenção nos fundos do cliente.

## Boas Práticas

1. **Capture Prontamente**: Não espere até o último dia do período de retenção
2. **Comunique Claramente**: Informe os clientes sobre retenções nas suas contas
3. **Anule Autorizações Não Usadas**: Não deixe autorizações expirarem naturalmente
4. **Use Texto Descritivo**: Ajude os clientes a identificar transações
5. **Monitorize Períodos de Retenção**: Acompanhe autorizações para garantir capturas atempadas
6. **Considere Multi-Captura**: Para pedidos complexos com múltiplos envios


## Fluxos Comuns

### Fluxo de E-Commerce


```
1. Cliente faz pedido → Autorizar pagamento
2. Pedido é embalado → Preparar para envio
3. Item é enviado → Capturar pagamento
4. OU pedido cancelado → Anular autorização
```

### Fluxo de Reserva de Hotel


```
1. Cliente reserva quarto → Autorizar quantia esperada
2. Check-in → Verificar autorização ainda válida
3. Check-out → Calcular quantia final
4. Capturar quantia real (pode ser mais ou menos que autorizado)
```

### Fluxo de Marketplace


```
1. Cliente pede de múltiplos fornecedores → Autorizar total
2. Fornecedor 1 envia → Capturar quantia do fornecedor 1
3. Fornecedor 2 envia → Capturar quantia do fornecedor 2
4. Cada captura pode acontecer independentemente
```

## Próximos Passos

- [Métodos de Pagamento](/docs/guides/payment-methods) - Aprenda quais métodos suportam aut/captura
- [Tipos de Pagamento](/docs/guides/payment-types) - Compreenda diferentes fluxos de pagamento
- [Webhooks](/docs/guides/webhooks) - Receba notificações para eventos de aut/captura
- [Referência da API](/openapi) - Documentação detalhada de endpoints