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

Optional Parameters

API Endpoints

Create a Recurring Payment Plan

POST /order

Example Request

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

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

Update a Recurring Payment Plan

PUT /order/{id}

Example Request

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:

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:

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

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