# Pagamentos Frequentes

Tokenize detalhes de pagamento uma vez, cobre montantes variáveis conforme necessário.

## Visão Geral

Pagamentos frequentes permitem-lhe guardar (tokenizar) os detalhes de pagamento do cliente e cobrar montantes variáveis sempre que necessário, sem exigir que o cliente reintroduza as suas informações de pagamento cada vez.

## Funcionalidades Principais

- **Configuração Única**: O cliente fornece os detalhes de pagamento uma vez
- **Montantes Variáveis**: Cobre diferentes montantes para cada transação
- **Cobrança a Pedido**: Você controla quando cobrar
- **Limites Flexíveis**: Defina mín/máx por transação ou total
- **Sem Agenda Recorrente**: Ao contrário das subscrições, você inicia cada pagamento
- **Múltiplos Métodos de Pagamento**: Suporte para cartões, MB WAY, Multibanco, Débito Direto, IBAN Virtual


## vs. Outros Tipos de Pagamento

| Funcionalidade | Único | Frequente | Subscrição |
|  --- | --- | --- | --- |
| Configuração | Um pagamento | Tokenizar uma vez | Tokenizar uma vez |
| Cobrança | Uma única vez | A pedido | Automático/Agendado |
| Montante | Fixo | Variável | Fixo |
| Controlo | Cliente | Comerciante | Automático |


## Casos de Uso

- **Recargas**: Montantes variáveis para créditos de conta
- **Serviços a Pedido**: Uber, entrega de comida, etc.
- **Faturação Variável**: Cobranças baseadas em uso
- **Cartões Pré-pagos**: Carregamento de montantes variáveis
- **Pagamento por Uso**: Serviços em nuvem, uso de API
- **Serviços de Táxi/Viagem**: Tarifas diferentes por viagem
- **Compras em Marketplace**: Totais de carrinho diferentes


## Como Funciona

### Passo 1: Criar Pagamento Frequente (Tokenizar)


```bash
POST /frequent

{
  "method": "cc",
  "currency": "EUR",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "max_value": 500.00  // Optional: max per capture
}
```

O cliente fornece os detalhes de pagamento uma vez. Resposta:


```json
{
  "id": "freq-123",
  "status": "active",
  "method": "cc",
  "customer": {...}
}
```

### Passo 2: Cobrar Fundos a Pedido


```bash
POST /capture/:id

{
  "value": 45.00,
  "descriptive": "Taxi ride to airport"
}
```

Resposta:


```json
{
  "id": "capture-456",
  "status": "success",
  "value": 45.00,
  "payment_id": "freq-123"
}
```

### Passo 3: Repetir Conforme Necessário

Cobre montantes adicionais a qualquer momento:


```bash
POST /capture/:id

{
  "value": 32.00,
  "descriptive": "Taxi ride downtown"
}
```

## Métodos de Pagamento Suportados

| Método de Pagamento | Tokenização | Cobrança a Pedido |
|  --- | --- | --- |
| Cartão de Crédito/Débito | ✅ | ✅ |
| MB WAY | ✅ | ✅ |
| Multibanco | ✅ | ❌ (Iniciado pelo Cliente) |
| Débito Direto | ✅ | ✅ |
| IBAN Virtual | ✅ | ❌ (Iniciado pelo Cliente) |


**Nota**:

- Para **Multibanco** e **IBAN Virtual**, o pagamento frequente cria uma referência fixa que os clientes podem usar várias vezes para enviar fundos a seu critério.
- Para **Cartão de Crédito**, **MB WAY** e **Débito Direto**, pode iniciar cobranças a pedido.


## Limites de Pagamento

Controle limites de gastos para proteger você e seus clientes:

### Limites por Cobrança


```json
{
  "min_value": 5.00,   // Minimum per capture
  "max_value": 100.00  // Maximum per capture
}
```

### Limite de Gasto Total


```json
{
  "max_value": 1000.00  // Total amount across all captures
}
```

### Pagamentos Ilimitados


```json
{
  "unlimited_payments": true  // Permite pagamentos ilimitados para todos os métodos de pagamento
}
```

## Exemplos de Caso de Uso

### Serviço de Partilha de Viagem

**Configuração**:


```json
{
  "method": "cc",
  "min_value": 5.00,
  "max_value": 200.00
}
```

**Cada Viagem**:


```json
{
  "value": 24.50,
  "descriptive": "Ride from Airport to Hotel"
}
```

### Serviço em Nuvem (Pagamento por Uso)

**Configuração**:


```json
{
  "method": "cc",
  "max_value": 5000.00,
  "unlimited_payments": false
}
```

**Cobranças Mensais**:


```json
{
  "value": 127.83,
  "descriptive": "Cloud usage - March 2024"
}
```

### Entrega de Comida

**Configuração**:


```json
{
  "method": "cc",
  "min_value": 10.00,
  "max_value": 150.00
}
```

**Cada Encomenda**:


```json
{
  "value": 34.99,
  "descriptive": "Order #789 - Pizza & Drinks"
}
```

### Recarga de Telemóvel Pré-pago

**Configuração**:


```json
{
  "method": "mbw",
  "min_value": 5.00,
  "max_value": 50.00
}
```

**Cada Recarga**:


```json
{
  "value": 20.00,
  "descriptive": "Mobile credit top-up"
}
```

## Gestão de Pagamentos Frequentes

### Obter Detalhes


```bash
GET /frequent/{id}
```

### Atualizar Limites


```bash
PATCH /frequent/{id}

{
  "max_value": 200.00
}
```

### Desativar


```bash
DELETE /frequent/{id}
```

**Efeito**: Sem mais cobranças permitidas, referência/token existente invalidado.

## Integração com Checkout

Use Checkout para tokenizar detalhes de pagamento:


```bash
POST /checkout

{
  "type": ["frequent"],
  "payment": {
    "methods": ["cc", "mbw", "dd"],
    "currency": "EUR"
  }
}
```

Trate o callback de sucesso:


```javascript
startCheckout(manifest, {
  onSuccess: (checkoutInfo) => {
    const frequentPaymentId = checkoutInfo.payment.id;
    // Save this ID for future captures
    saveToDatabase(frequentPaymentId);
  }
});
```

## Melhores Práticas

1. **Autorização Clara**: Informe os clientes que estão autorizando cobranças futuras
2. **Limites de Gastos**: Defina limites razoáveis para construir confiança
3. **Descrições de Transações**: Use texto descritivo claro e reconhecível
4. **E-mails de Notificação**: Envie e-mail aos clientes após cada cobrança
5. **Desativação Fácil**: Permita que os clientes desativem pagamentos frequentes facilmente
6. **Tratamento de Pagamentos Falhados**: Lógica de repetição e notificação ao cliente
7. **Trilha de Auditoria**: Mantenha registos detalhados de todas as cobranças


## Segurança

- **Tokenização**: Os dados do cartão nunca são armazenados, apenas tokens seguros
- **Conformidade PCI**: Easypay trata de toda a conformidade PCI
- **Autenticação 3DS**: Camada de segurança adicional para pagamentos com cartão
- **Limites de Gastos**: Proteja contra cobranças excessivas
- **Controlo do Cliente**: Os clientes podem desativar a qualquer momento


## Próximos Passos

- [Referência da API de Pagamento Frequente](/openapi#tag/Frequent-Payment) - Documentação completa da API
- [Checkout](/docs/products/checkout) - Tokenizar via Checkout
- [Guia de Tipos de Pagamento](/docs/guides/payment-types) - Comparar tipos de pagamento