# Recurring Payments

This guide explains how to implement subscription and recurring billing functionality with xMoney. Our API provides flexible options for managing recurring payments, trial periods, and automatic rebilling.

## Overview

Recurring payments allow merchants to charge customers on a regular schedule without requiring the customer to manually authorize each transaction. This is ideal for subscription services, membership plans, and installment payments.

## Key Concepts

### Order Types

xMoney supports several order types for different payment scenarios:

- **Purchase**: One-time payment (non-recurring)
- **Recurring**: Automated recurring payments based on a defined schedule
- **Managed**: Merchant-initiated recurring payments that are manually triggered
- **Credit**: Used for credit transactions


### Interval Types

Recurring payments can be scheduled at different intervals:

- **Day**: Daily billing (e.g., every 7 days)
- **Month**: Monthly billing (e.g., every 1 month)


## Setting Up Recurring Payments

To set up a recurring payment plan, you need to create an order with `orderType` set to `recurring` and specify the following parameters:

### Required Parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| orderType | string | Must be set to `recurring` |
| intervalType | string | Billing period type (`day` or `month`) |
| intervalValue | integer | Numeric value of the interval (e.g., 1, 7, 30) |


### Optional Parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| trialAmount | number | Amount to charge for the initial/trial period (if different from the regular amount) |
| firstBillDate | string | Date when the first recurring payment should be processed (ISO 8601 format) |
| retryPayment | string | Comma-separated list of retry intervals for failed payments (ISO 8601 Duration format) |


## API Endpoints

### Create a Recurring Payment Plan


```
POST /order
```

#### Example Request


```bash
curl -X POST \
  https://api.xmoney.com/order \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'customerId=12345&orderType=recurring&amount=29.99&currency=USD&ip=192.168.1.1&intervalType=month&intervalValue=1&description=Monthly%20Subscription&trialAmount=1.00'
```

#### Example Response


```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "orderId": 67890,
    "orderStatus": "start"
  }
}
```

### Update a Recurring Payment Plan


```
PUT /order/{id}
```

#### Example Request


```bash
curl -X PUT \
  https://api.xmoney.com/order/67890 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'customerId=12345&orderType=recurring&nextDueDate=2023-12-01T00:00:00Z&intervalType=month&intervalValue=1'
```

## Trial Periods

You can set up a trial period with a different amount by using the `trialAmount` parameter. When this parameter is provided:

1. The customer is initially charged the trial amount
2. The system automatically switches to the regular amount for subsequent billings
3. The description will show as "{intervalValue} {intervalType} subscription trial"


## Payment Retry Logic

If a recurring payment fails, xMoney will automatically retry based on:

1. The retry schedule defined in `retryPayment` parameter (if provided)
2. The system's default retry schedule if none is specified


The retry intervals should be specified using ISO 8601 Duration format. For example:

- `P1D` - retry after 1 day
- `P3D,P7D,P14D` - retry after 3 days, then 7 days, then 14 days


During retry attempts, the order status will change to `retrying`. If all retry attempts fail, the order will be marked as `complete-ok` but no further payments will be processed.

## Handling Failed Payments

For certain failure reasons, xMoney employs special handling:

- **Insufficient funds**: May attempt a micro-payment for orders over a certain amount
- **Provider errors**: Will retry after 24 hours
- **Transaction limits exceeded**: Will retry after 24 hours
- **Blacklisted cards**: Will retry according to the configured retry schedule


## Managing Recurring Orders

### Extending the Billing Period

To extend the next billing date for an active recurring order:


```bash
curl -X PUT \
  https://api.xmoney.com/order/67890 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'customerId=12345&orderType=recurring&nextDueDate=2023-12-15T00:00:00Z'
```

### Changing Payment Method

To update the payment method for future recurring payments:


```bash
curl -X PUT \
  https://api.xmoney.com/order/67890 \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'customerId=12345&orderType=recurring&transactionMethod=card&cardId=c_123456'
```

## Best Practices

1. **Clear descriptions**: Use descriptive names for subscription plans to avoid customer confusion
2. **Appropriate trial amounts**: Set trial amounts that are small enough to encourage sign-ups but sufficient to validate payment methods
3. **Strategic retry schedules**: Configure retry intervals based on your business model and customer payment patterns
4. **Customer communication**: Notify customers before rebilling and when payment methods fail
5. **Saved payment methods**: Always use the `saveCard` parameter when processing the initial payment for recurring orders


## Troubleshooting

| Issue | Possible Cause | Solution |
|  --- | --- | --- |
| Recurring payments not processing | Missing or invalid interval settings | Verify intervalType and intervalValue are correctly set |
| Trial payment processed but no rebilling | Incorrect firstBillDate | Ensure firstBillDate is in the future and in the correct format |
| Failed rebilling attempts | Expired or declined payment method | Update the payment method using PUT /order/{id} |
| Unexpected trial amount | trialAmount parameter confusion | Check if trialAmount is set correctly in your API call |


For additional assistance with recurring payments, please contact xMoney support.