# Pay By Link

Create links to receive payments and share them via email or SMS. Sell products, collect invoices, or raise funds without even having a website.

## What is Pay By Link?

Pay By Link allows you to generate unique payment links that you can share with customers through any channel - email, SMS, social media, or messaging apps. Each link is created for a specific payment (single payment, subscription, or any other payment type) and is intended for one customer or transaction. When customers click the link, they're taken to a hosted payment page where they can complete their purchase.

## Key Benefits

- **No website required**: Accept payments without building a website
- **Quick setup**: Create payment links in seconds via API
- **Share anywhere**: Email, SMS, WhatsApp, social media, QR codes
- **Mobile-optimized**: Works seamlessly on all devices
- **Track payments**: Monitor link usage and payment status
- **Customizable**: Add product details, amounts, and customer information


## Use Cases

- **Invoice payments**: Send unique payment links for each outstanding invoice
- **Event tickets**: Send individual payment links to customers for ticket purchases
- **Donations**: Send personalized payment links to donors
- **Service payments**: Send quick payment links for services rendered
- **Product sales**: Send payment links for individual product purchases
- **Booking deposits**: Send deposit payment links for appointments
- **Remote sales**: Sales reps can send personalized payment links to customers
- **Subscription sign-ups**: Send links for customers to start their subscriptions


## How It Works

### 1. Create a Payment Link


```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. Receive the Payment Link


```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. Share the Link

The API can automatically send the payment link via the specified communication channels (EMAIL, SMS), or you can manually share it through:

- Email (automatically sent if specified in `communication_channels`)
- SMS (automatically sent if specified in `communication_channels`)
- WhatsApp
- Social media
- QR code (image URL provided in response)


### 4. Customer Pays

Customer clicks the link and completes payment using their preferred method.

### 5. Receive Notification

Get a webhook notification when the payment is completed.

## Features

### Automatic Communication

Send payment links automatically to your customers via email or SMS:


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

When you specify `communication_channels`, Easypay will automatically send the payment link to the customer through the selected channels. You can choose:

- `EMAIL` - Send link via email to the customer's email address
- `SMS` - Send link via SMS to the customer's phone number
- Both - Include both values in the array to send via both channels


### Expiration Dates

Set when links expire:


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

### Customer Pre-fill

Pre-fill customer information:


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

### Custom Descriptions

Add meaningful descriptions:


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

### Payment Methods

Support all Easypay payment methods:

- Credit/Debit Card
- MB WAY
- Multibanco
- Apple Pay
- Google Pay
- Samsung Pay
- Direct Debit
- Virtual IBAN


## Managing Payment Links

### Retrieve Link Details


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

### Update a Link


```bash
PATCH /link/{id}

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

### Cancel a Link


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

## Link Statuses

| Status | Description |
|  --- | --- |
| `ACTIVE` | Link is active and can be paid |
| `FINALIZED` | Payment completed successfully |
| `EXPIRED` | Link has expired |
| `DISABLED` | Link was manually cancelled |


## Best Practices

1. **Set Expiration Dates**: Always set reasonable expiration times
2. **Use Unique References**: Include your internal reference in the `key` field
3. **Pre-fill Customer Data**: Reduces friction and errors
4. **Clear Descriptions**: Help customers identify what they're paying for
5. **Track Link Status**: Monitor which links have been paid
6. **Use Webhooks**: Get notified immediately when payments complete
7. **Secure Sharing**: Only share links with intended recipients


## Integration Example

### Create and Send Payment Link


```javascript
async function sendPaymentLink(invoiceId, customer, amount) {
  // Create payment link with automatic email and SMS delivery
  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 days from now
      communication_channels: ['EMAIL', 'SMS'] // Automatically send via email and SMS
    })
  });

  const paymentLink = await response.json();

  // The link has been automatically sent to the customer via email and SMS
  // You can also use the QR code image: paymentLink.qr_code

  return paymentLink;
}
```

### Handle Payment Webhook


```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);
  }
});
```

## QR Codes

The API automatically generates a QR code image for every payment link. The QR code URL is included in the response:


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

You can use this QR code image in:

- Printed invoices and receipts
- Email communications
- Physical store displays
- Marketing materials
- Mobile apps


Simply embed the QR code image URL in your HTML or display it to customers:


```html
<img src="https://cdn.easypay.pt/qrcodes/a1b2c3d4.png" alt="Payment QR Code" />
```

## Multi-Channel Distribution

### Automatic Email and SMS

When you include `communication_channels` in your API request, Easypay automatically sends the payment link to your customer:


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

The email and SMS are professionally formatted and include:

- Payment link URL
- Payment amount and description
- Expiration date
- Your business branding (if configured)


## Security Considerations

1. **One Link Per Transaction**: Each payment link is created for one specific payment or subscription. Links should not be shared with multiple customers to create multiple separate transactions
2. **Expiration**: Set appropriate expiration times
3. **HTTPS**: All payment pages use HTTPS
4. **Verification**: Always verify payments via API or webhooks
5. **Customer Validation**: Links can optionally require specific customer details


## Monitoring and Reporting

Track payment link performance:


```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
```

## Common Scenarios

### Scenario 1: Invoice Payment

Create a unique link for each invoice, send to the specific customer, mark invoice as paid when webhook received.

### Scenario 2: Event Ticket Sales

Create a unique link for each customer purchasing a ticket, send via email or SMS, confirm ticket upon payment.

### Scenario 3: Individual Donations

Create a unique link for each donor, send directly to them, track individual donations via webhooks.

### Scenario 4: Service Deposit

Create a unique link for the deposit amount, send to the specific customer before appointment, confirm booking upon payment.

## Next Steps

- [Pay By Link API Reference](/openapi#tag/Pay-By-Link) - Complete API documentation
- [Webhooks Guide](/docs/guides/webhooks) - Receive payment notifications
- [Quick Start](/docs/quickstart) - Get started with the API