# Frequent Payments

Tokenize payment details once, charge variable amounts on demand.

## Overview

Frequent payments allow you to save (tokenize) customer payment details and then charge them variable amounts whenever needed, without requiring the customer to re-enter their payment information each time.

## Key Features

- **One-Time Setup**: Customer provides payment details once
- **Variable Amounts**: Charge different amounts for each transaction
- **On-Demand Charging**: You control when to charge
- **Flexible Limits**: Set min/max per transaction or total
- **No Recurring Schedule**: Unlike subscriptions, you trigger each payment
- **Multiple Payment Methods**: Support for cards, MB WAY, Multibanco, Direct Debit, Virtual IBAN


## vs. Other Payment Types

| Feature | Single | Frequent | Subscription |
|  --- | --- | --- | --- |
| Setup | One payment | Tokenize once | Tokenize once |
| Charging | One-time | On-demand | Automatic/Scheduled |
| Amount | Fixed | Variable | Fixed |
| Control | Customer | Merchant | Automatic |


## Use Cases

- **Top-ups**: Variable amounts for account credits
- **On-Demand Services**: Uber, food delivery, etc.
- **Variable Billing**: Usage-based charges
- **Prepaid Cards**: Loading variable amounts
- **Pay-as-you-go**: Cloud services, API usage
- **Taxi/Ride Services**: Different fares per ride
- **Marketplace Purchases**: Different cart totals


## How It Works

### Step 1: Create Frequent Payment (Tokenize)


```bash
POST /frequent

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

Customer provides payment details once. Response:


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

### Step 2: Capture Funds On-Demand


```bash
POST /capture/:id

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

Response:


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

### Step 3: Repeat as Needed

Capture additional amounts anytime:


```bash
POST /capture/:id

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

## Supported Payment Methods

| Payment Method | Tokenization | On-Demand Capture |
|  --- | --- | --- |
| Credit/Debit Card | ✅ | ✅ |
| MB WAY | ✅ | ✅ |
| Multibanco | ✅ | ❌ (Customer-initiated) |
| Direct Debit | ✅ | ✅ |
| Virtual IBAN | ✅ | ❌ (Customer-initiated) |


**Note**:

- For **Multibanco** and **Virtual IBAN**, the frequent payment creates a fixed reference that customers can use multiple times to send funds at their discretion.
- For **Credit Card**, **MB WAY**, and **Direct Debit**, you can initiate captures on-demand.


## Payment Limits

Control spending limits to protect both you and your customers:

### Per-Capture Limits


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

### Total Spending Limit


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

### Unlimited Payments


```json
{
  "unlimited_payments": true  // Allows unlimited payments for all payment methods
}
```

## Use Case Examples

### Ride-Sharing Service

**Setup**:


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

**Each Ride**:


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

### Cloud Service (Pay-as-you-go)

**Setup**:


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

**Monthly Charges**:


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

### Food Delivery

**Setup**:


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

**Each Order**:


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

### Prepaid Mobile Top-Up

**Setup**:


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

**Each Top-Up**:


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

## Managing Frequent Payments

### Get Details


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

### Update Limits


```bash
PATCH /frequent/{id}

{
  "max_value": 200.00
}
```

### Deactivate


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

**Effect**: No more captures allowed, existing reference/token invalidated.

## Integration with Checkout

Use Checkout to tokenize payment details:


```bash
POST /checkout

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

Handle success callback:


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

## Best Practices

1. **Clear Authorization**: Inform customers they're authorizing future charges
2. **Spending Limits**: Set reasonable limits to build trust
3. **Transaction Descriptions**: Use clear, recognizable descriptive text
4. **Notification Emails**: Email customers after each capture
5. **Easy Deactivation**: Let customers deactivate frequent payments easily
6. **Failed Payment Handling**: Retry logic and customer notification
7. **Audit Trail**: Keep detailed logs of all captures


## Security

- **Tokenization**: Card details never stored, only secure tokens
- **PCI Compliance**: Easypay handles all PCI compliance
- **3DS Authentication**: Additional security layer for card payments
- **Spending Limits**: Protect against excessive charges
- **Customer Control**: Customers can deactivate anytime


## Next Steps

- [Frequent Payment API Reference](/openapi#tag/Frequent-Payment) - Complete API documentation
- [Checkout](/docs/products/checkout) - Tokenize via Checkout
- [Payment Types Guide](/docs/guides/payment-types) - Compare payment types