> For the complete documentation index, see [llms.txt](https://docs.payr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payr.com/payment-interface/payr-sdk/features/recurring-payments.md).

# Recurring Payments

### Overview

With recurring payments, users can:

* Set up automated monthly rent payments
* Pause and resume recurring payments
* Update payment methods for recurring payments

**Important:** Recurring payments are available for **card payments only**. APMs and wallet payments do not support recurring functionality.

### How Recurring Payments Work

#### Setup Flow

1. **User selects recurring option** — During payment setup, user chooses to enable recurring payments
2. **First payment** — User completes the initial payment with 3DS authentication
3. **Automated payments** — Future payments are automatically charged on the scheduled date
4. **Notifications** — User receives notifications before each payment and after completion

### SDK Implementation

#### Enable Recurring Payments

Add the `recurring` feature flag when initializing the SDK:

```javascript
PAYR.init({
  apiBaseUrl: 'https://api.mypayr.co.uk',
  authToken: token,
  container: '#payr-payment-form',
  features: {
    recurring: true  // Enable recurring payment setup and management
  },
  onSuccess: (result) => {
    console.log('Payment successful:', result);
  },
  onError: (error) => {
    console.error('Payment failed:', error);
  }
});
```

#### What Happens When Enabled

When `recurring: true` is set:

* Users see a **payment breakdown** showing base amount and processing fees
* Option to set up recurring payment schedules appears
* Users can manage existing recurring payments (pause/resume/cancel)
* Payment method management for recurring payments is available

#### Trigger a Recurring Payment

Mark a payment as recurring using the `is_recurring` parameter in `PAYR.pay()`:

```javascript
await PAYR.pay({
  pure_amount: 850.00,
  currency: 'GBP',
  reference: 'rent-monthly-feb-2024',
  is_recurring: true  // Mark as recurring payment
});
```

The first payment will require full 3DS authentication. Subsequent automated payments will use the saved payment method.

#### Important: Onboarding Requirements

**Recurring payments require an installments schedule to be configured during user onboarding.**

When calling the `/onboarding/` endpoint, include the `installments` array with the payment schedule:

```json
{
  "user_id": 12345,
  "email": "user@example.com",
  // ... other user fields
  "tenant": [{
    "rent_due_day": 1,
    "amount": "850.00",
    "frequency": "every_1_month",
    // ... other tenant fields
  }],
  "installments": [
    {
      "installment_number": 1,
      "due_date": "2026-03-12",
      "amount": 85000  // Amount in pence (£850.00)
    },
    {
      "installment_number": 2,
      "due_date": "2026-04-12",
      "amount": 85000
    },
    // Add installments for each payment in the schedule
  ],
  "kyc": { /* ... */ }
}
```

**Installments fields:**

* `installment_number` (integer, required) — Sequential payment number (1, 2, 3...)
* `due_date` (date, required) — Due date for each recurring payment (YYYY-MM-DD)
* `amount` (integer, required) — Payment amount in **pence** (e.g., 85000 = £850.00)

**Note:** Installments are optional. However, if provided, all fields inside each installment object are required.

***

#### Managing Recurring Payments

Users can manage their recurring payments through the payment interface:

**View Active Schedules**

* See all active recurring payment schedules
* View next payment date and amount
* Check payment history

**Pause Recurring Payments**

* Temporarily pause automated payments
* Resume at any time
* Next payment date adjusts automatically

**Cancel Recurring Payments**

* Stop automated payments permanently
* Option to make manual payments instead

**Update Payment Method**

* Change the card used for recurring payments
* New card must pass 3DS authentication
* Takes effect on the next payment

***

### Benefits

**For Users**

* No risk of missing rent payments
* Automatic payment each month
* Easy to manage and control
* Peace of mind for students

**For Landlords**

* Consistent, on-time payments
* Reduced payment delays
* Lower administrative overhead
* Improved cash flow

***

### Important Limitations

**Card Payments Only**

* Recurring payments require saved card payment methods
* APMs (Alipay, WeChat Pay, UnionPay) do not support recurring
* Wallet payments (Apple Pay, Google Pay) do not support recurring

***

### Failed Recurring Payments

If a recurring payment fails:

1. **User is notified** - Email/SMS notification sent immediately
2. **Retry logic** - System may retry the payment (configurable by Payr)
3. **Manual payment option** - User can make a manual payment
4. **Update payment method** - User can update their card details
5. **Webhook sent** - Your backend receives `payment_failed` webhook

***

### Support

Need help with recurring payment setup? Contact **<support@mypayr.co.uk>**