# Pagar por Link

Crie ligações para receber pagamentos e partilhe-as por e-mail ou SMS. Venda produtos, receba faturas ou angarie fundos sem nem ter um website.

## O que é Pagar por Link?

Pagar por Link permite-lhe gerar ligações de pagamento únicas que pode partilhar com clientes através de qualquer canal - e-mail, SMS, redes sociais ou aplicações de mensagens. Cada ligação é criada para um pagamento específico (pagamento único, subscrição ou qualquer outro tipo de pagamento) e destina-se a um cliente ou transação. Quando os clientes clicam na ligação, são levados a uma página de pagamento alojada onde podem concluir a sua compra.

## Principais Vantagens

- **Sem website necessário**: Aceite pagamentos sem construir um website
- **Configuração rápida**: Crie ligações de pagamento em segundos através da API
- **Partilhe em qualquer lugar**: E-mail, SMS, WhatsApp, redes sociais, códigos QR
- **Otimizado para telemóvel**: Funciona perfeitamente em todos os dispositivos
- **Acompanhe pagamentos**: Monitore a utilização de ligações e o estado do pagamento
- **Personalizável**: Adicione detalhes do produto, montantes e informações do cliente


## Casos de Uso

- **Pagamentos de faturas**: Envie ligações de pagamento únicas para cada fatura em aberto
- **Bilhetes de eventos**: Envie ligações de pagamento individuais aos clientes para compra de bilhetes
- **Doações**: Envie ligações de pagamento personalizadas a doadores
- **Pagamentos de serviços**: Envie ligações de pagamento rápidas por serviços prestados
- **Vendas de produtos**: Envie ligações de pagamento para compras individuais de produtos
- **Depósitos de reservas**: Envie ligações de pagamento de depósito para agendamentos
- **Vendas remotas**: Os representantes de vendas podem enviar ligações de pagamento personalizadas aos clientes
- **Adesão a subscrições**: Envie ligações para clientes iniciarem as suas subscrições


## Como Funciona

### 1. Crie uma Ligação de Pagamento


```bash
POST https://api.prod.easypay.pt/2.0/link

{
  "value": 50.00,
  "currency": "EUR",
  "description": "Invoice #12345",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+351911234567"
  },
  "expiration_time": "2024-12-31 23:59",
  "communication_channels": ["EMAIL", "SMS"]
}
```

### 2. Receba a Ligação de Pagamento


```json
{
  "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
  "url": "https://pay.easypay.pt/a1b2c3d4",
  "qr_code": "https://cdn.easypay.pt/qrcodes/a1b2c3d4.png",
  "status": "ACTIVE",
  "value": 50.00,
  "description": "Invoice #12345"
}
```

### 3. Partilhe a Ligação

A API pode enviar automaticamente a ligação de pagamento através dos canais de comunicação especificados (EMAIL, SMS), ou pode partilhá-la manualmente através de:

- E-mail (enviado automaticamente se especificado em `communication_channels`)
- SMS (enviado automaticamente se especificado em `communication_channels`)
- WhatsApp
- Redes sociais
- Código QR (URL da imagem fornecido na resposta)


### 4. O Cliente Paga

O cliente clica na ligação e conclui o pagamento utilizando o seu método preferido.

### 5. Receba Notificação

Obtenha uma notificação de webhook quando o pagamento for concluído.

## Funcionalidades

### Comunicação Automática

Envie ligações de pagamento automaticamente aos seus clientes por e-mail ou SMS:


```json
{
  "communication_channels": ["EMAIL", "SMS"],
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+351911234567"
  }
}
```

Quando especifica `communication_channels`, a Easypay envia automaticamente a ligação de pagamento ao cliente através dos canais selecionados. Pode escolher:

- `EMAIL` - Envia ligação por e-mail para o endereço de e-mail do cliente
- `SMS` - Envia ligação por SMS para o número de telefone do cliente
- Ambos - Inclua ambos os valores no array para enviar através de ambos os canais


### Datas de Expiração

Defina quando as ligações expiram:


```json
{
  "expiration_time": "2024-12-31 23:59"
}
```

### Preenchimento Automático de Cliente

Preencha previamente as informações do cliente:


```json
{
  "customer": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+351912345678",
    "fiscal_number": "PT123456789"
  }
}
```

### Descrições Personalizadas

Adicione descrições significativas:


```json
{
  "description": "Invoice #12345 - Website Design Services",
  "key": "invoice-12345"  // Your internal reference
}
```

### Métodos de Pagamento

Suporte a todos os métodos de pagamento Easypay:

- Cartão de Crédito/Débito
- MB WAY
- Multibanco
- Apple Pay
- Google Pay
- Samsung Pay
- Débito Direto
- IBAN Virtual


## Gerir Ligações de Pagamento

### Recuperar Detalhes da Ligação


```bash
GET /link/{id}
```

### Atualizar uma Ligação


```bash
PATCH /link/{id}

{
  "description": "Updated description",
  "expiration_time": "2025-01-31 23:59"
}
```

### Cancelar uma Ligação


```bash
DELETE /link/{id}
```

## Estados da Ligação

| Estado | Descrição |
|  --- | --- |
| `ACTIVE` | A ligação está ativa e pode ser paga |
| `FINALIZED` | Pagamento concluído com sucesso |
| `EXPIRED` | A ligação expirou |
| `DISABLED` | A ligação foi cancelada manualmente |


## Boas Práticas

1. **Defina Datas de Expiração**: Sempre defina tempos de expiração razoáveis
2. **Use Referências Únicas**: Inclua a sua referência interna no campo `key`
3. **Preencha Dados do Cliente**: Reduz atrito e erros
4. **Descrições Claras**: Ajude os clientes a identificar o que estão a pagar
5. **Acompanhe o Estado da Ligação**: Monitore quais ligações foram pagas
6. **Use Webhooks**: Seja notificado imediatamente quando os pagamentos se completam
7. **Partilha Segura**: Partilhe as ligações apenas com os destinatários pretendidos


## Exemplo de Integração

### Criar e Enviar Ligação de Pagamento


```javascript
async function sendPaymentLink(invoiceId, customer, amount) {
  // Cria ligação de pagamento com envio automático por e-mail e SMS
  const response = await fetch('https://api.prod.easypay.pt/2.0/link', {
    method: 'POST',
    headers: {
      'AccountId': process.env.EASYPAY_ACCOUNT_ID,
      'ApiKey': process.env.EASYPAY_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      value: amount,
      currency: 'EUR',
      description': `Invoice #${invoiceId}`,
      key: `invoice-${invoiceId}`,
      customer: {
        name: customer.name,
        email: customer.email,
        phone: customer.phone
      },
      expiration_time: getExpirationDate(30), // 30 dias a partir de agora
      communication_channels: ['EMAIL', 'SMS'] // Envia automaticamente por e-mail e SMS
    })
  });

  const paymentLink = await response.json();

  // A ligação foi enviada automaticamente ao cliente por e-mail e SMS
  // Também pode usar a imagem do código QR: paymentLink.qr_code

  return paymentLink;
}
```

### Processar Webhook de Pagamento


```javascript
app.post('/webhooks/easypay', async (req, res) => {
  const notification = req.body;

  // Acknowledge receipt
  res.status(200).send('OK');

  // Verify and process
  if (notification.type === 'capture' && notification.status === 'success') {
    await markInvoiceAsPaid(notification.key);
    await sendPaymentConfirmation(notification.id);
  }
});
```

## Códigos QR

A API gera automaticamente uma imagem de código QR para cada ligação de pagamento. O URL do código QR é incluído na resposta:


```json
{
  "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
  "url": "https://pay.easypay.pt/a1b2c3d4",
  "qr_code": "https://cdn.easypay.pt/qrcodes/a1b2c3d4.png"
}
```

Pode usar esta imagem de código QR em:

- Faturas e recibos impressos
- Comunicações por e-mail
- Displays de loja física
- Materiais de marketing
- Aplicações móveis


Simplesmente incorpore o URL da imagem do código QR no seu HTML ou mostre aos clientes:


```html
<img src="https://cdn.easypay.pt/qrcodes/a1b2c3d4.png" alt="Código QR de Pagamento" />
```

## Distribuição Multi-Canal

### E-mail e SMS Automáticos

Quando inclui `communication_channels` no seu pedido à API, a Easypay envia automaticamente a ligação de pagamento ao seu cliente:


```json
{
  "communication_channels": ["EMAIL", "SMS"],
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+351911234567"
  }
}
```

O e-mail e SMS são formatados profissionalmente e incluem:

- URL da ligação de pagamento
- Montante e descrição do pagamento
- Data de expiração
- A imagem da sua marca (se configurada)


## Considerações de Segurança

1. **Uma Ligação Por Transação**: Cada ligação de pagamento é criada para um pagamento ou subscrição específico. As ligações não devem ser partilhadas com múltiplos clientes para criar múltiplas transações separadas
2. **Expiração**: Defina tempos de expiração apropriados
3. **HTTPS**: Todas as páginas de pagamento utilizam HTTPS
4. **Verificação**: Sempre verifique os pagamentos através da API ou webhooks
5. **Validação de Cliente**: As ligações podem opcionalmente exigir detalhes específicos do cliente


## Monitorização e Relatórios

Acompanhe o desempenho das ligações de pagamento:


```bash
# Get all links
GET /link

# Filter by status
GET /link?status=FINALIZED

# Filter by date range
GET /link?created_after=2024-01-01&created_before=2024-01-31
```

## Cenários Comuns

### Cenário 1: Pagamento de Fatura

Crie uma ligação única para cada fatura, envie ao cliente específico, marque a fatura como paga quando o webhook é recebido.

### Cenário 2: Vendas de Bilhetes de Evento

Crie uma ligação única para cada cliente que compra um bilhete, envie por e-mail ou SMS, confirme o bilhete após o pagamento.

### Cenário 3: Doações Individuais

Crie uma ligação única para cada doador, envie diretamente a ele, acompanhe doações individuais através de webhooks.

### Cenário 4: Depósito de Serviço

Crie uma ligação única para o montante do depósito, envie ao cliente específico antes do agendamento, confirme a reserva após o pagamento.

## Próximos Passos

- [Referência da API de Pagar por Link](/openapi#tag/Pay-By-Link) - Documentação completa da API
- [Guia de Webhooks](/docs/guides/webhooks) - Receba notificações de pagamento
- [Início Rápido](/docs/quickstart) - Comece com a API