# Subscriptions

The Subscriptions API helps create subscription plans. Subscription plans settings for scheduling recurring payments and sending email invoices when payments are due. Once a subscription plan is created and configured on the dashboard, customers can enrol into the plan using a link.

# Using subscriptions

  • Create a Subscription Plan on the dashboard.
  • Share the subscription enrolment link with your customers. You can get it from the dashboard or from the /subscription-link API.
  • The customer can fill in their information on the enrolment screen.
  • When the customer clicks on "Pay", they are enrolled into the plan, and a new subscription is created.
  • When the customer completes the payment, the subscription is activated.

To enrol a customer into a subscription plan, create a subscription enrolment link that they can use to make their first payment.

Returns generated subscription link to enrol a customer into a subscription plan. You can use this link to direct customers to XanPay's interface for making their first payment and enrolling into a subscription plan and creating a subscription. If you already have the customer's details such as first name, last name, email and phone number, you can pre-fill these by passing a customer object in the body. Once you receive this link, your site should redirect your customer to this link.

Endpoint POST /subscription-link

Response { "subscriptionLink": URL }

Payload attributes

Parameter Required Description
subscriptionPlanId Required ID of the subscription plan into which the customer must be enrolled
customer Optional (proposed) Can be used to autofill customer details
notifyPayload Optional Custom string to be saved as a part of the charge object Note: we recommend encoding in base64
redirectUrl Optional Enables a button that takes the customer back to the specified url

Request example

curl 
  -X POST https://api.xanpay.com/subscription-link
  -u {API_KEY}:{API_SECRET}
  -d '{
	"subscriptionPlanId": "620c59bcb19850001184df71",  
	"paymentMethods": {
		"SG": ["paynow"]
	},
	"redirectUrl": "https://merchant-website.com",
	"notifyPayload": "eyJvcmRlcklkIjogIjI1MSJ9",
    "customer": {
        "email": "customer@gmail.com",
        "phone": {
            "code": "+65",
            "phone": "12345678901"
        }
    }
}'

TBD Response example

{
    "subscriptionLink": "https://checkout.xanpay.com/?"
}

# List subscriptions (proposed)

Returns a list of subscriptions with most recently created subscriptions first. Subscriptions are filtered based on the parameters specified. Pagination is supported and number of subscriptions per page can be specified using the arguments - page and limit.

Endpoint GET /subscriptions

Query parameters

Parameter Description Example
startDate Earliest subscription creation time in UTC 2021-12-14T02:10:00
endDate Latest subscription creation time in UTC 2021-12-14T02:10:00
subscriptionPlanId ID of the subscription plan 620c59bcb19850001184df71
customerCurrency Customer's currency SGD
customerEmail Customer's email customer@gmail.com
customerPhone Customer's phone number with '+' stripped. Used for filtering charges only if the customerEmail parameter is not specified. 6512345678901
page Page number of results. Default value is 1 2
limit Limit on the number of objects returned. The value is 10 by default and can range from 1 to 50 25

Request example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
"https://api.xanpay.com/subscriptions?customerEmail=customer@gmail.com"

Response example TBD: Add response example, after development

# Get a subscription (proposed)

Returns subscription details including a subscription object.

Endpoint GET /subscriptions/{id}

Response Subscription object

Request example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
"https://api.xanpay.com/subscriptions/6f7d1cc4d56bef00123b068f"

Response example TBD: Add response example, after development

# Subscription object

Below you can find description for each subscription's field.

Attributes

Parameter Description
id Unique subscription ID
subscriptionPlanId Subscription Plan ID
customer Customer object including email and phone
status Current subscription status
createdAt Timestamp of when the subscription was created
updatedAt Timestamp of when the subscription was updated
invoices List of invoices generated
charges List of associated charges
nextPayment UTC date/time of next payment due date
activeUntil UTC date/time until when an active subscription is valid until
numPaymentsComplete Number of payments completed, to be compared with numPayments in Subscription Plan

# Subscription status

Status Description
active Subscription is current and active or in grace period.
inactive Subscription is paused and awaiting payment.
completed Subscription has been completed, with all the payments made.

# Invoice object

Parameter Description
customer Customer object
chargeId Charge Id
checkoutLink Custom URL to help the user make the payment
invoiceDueOn Data by which invoice must be paid

# Subscription plans (proposed)

# Subscription plan object

The structure of the Subscription plan below provides an explanation of the various options available while setting up a Subscription plan.

Attributes

Parameter Type Description
id Required Unique subscription plan ID
name Required String describing the plan
numPayments Number Total number of payments in the plan
currency Required Currency in which the plan is created
recurringPayment Required Object defining the recurring payment terms
recurringPayment.amount Required Recurring amount in the currency specified above
recurringPayment.period Required; "days", "months" or "years" Specifies the time between 2 payments, in combination with count
recurringPayment.count Required; Numeric value from 1 to 400 Specifies the time between 2 payments, in combination with period
initialPayment.amount Optional First payment amount, to setup trials and first month discounts
initialPayment.period Optional Specifies the time between the first and second payment, in combination with initial.count
initialPayment.count Optional Specifies the time between the first and second payment, in combination with initial.period
sendEmail Boolean; true by default XanPay sends email invoices to the customer only if this is true
invoiceNotice Number of days, default 2 Number of days before the payment due date that an invoice is generated
gracePeriod Number of days, default 1 If a recurring payment is not made a few days after the due date, the subscription is paused
orders Optional List of orders
methods Optional List of permitted payment methods in the subscription
status "active" default, "inactive" Status of the plan
createdAt UTC Date-time string Timestamp when the subscription plan was created
updatedAt UTC Date-time string Timestamp when the subscription plan was updated

# Subscription plan status

Status Description
active New subscriptions can be created under this plan.
inactive New subscriptions cannot be created under this plan.

# List subscription plans

Returns a list of subscription plans with most recently created plans first. Plans are filtered based on the parameters specified. Pagination is supported and number of plans per page can be specified using the arguments - page and limit.

Endpoint GET /subscription-plans

# Get a subscription plan

Returns subscription plan details including a subscription plan object.

Endpoint GET /subscription-plans/{id}

Response Subscription plan object

Request example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
"https://api.xanpay.com/subscription-plans/6f7d1cc4d56bef00123b068f"

Response example TBD: Add response example, after development

# Workflow (proposed)

Subscriptions can be integration using our API and API notifications (Notification version 0.9 onwards only). The workflow of a subscription begins with creating a subscription plan and ends when the subscription completes.

# Create and manage subscriptions

  1. Create a Subscription Plan on the dashboard or using the API.
  2. Create a subscription enrolment link for this Subscription Plan via API or dashboard.

# Enrol customers

Share the subscription enrolment link with your customers. The customer can fill, correct or confirm this information on the enrolment screen. They are enrolled into the plan when they click Pay.

  • A Subscription object with status inactive is created, associating a subscription plan with a customer.
  • A subscription_created event notification is triggered.
  • A Charge object is created. It includes a subscriptionId which connects the charge with the subscription.
  • A charge_created event is also triggered.

# Accept first payment

When the customer makes the payment for the associated charge, the following notifications are sent:

  • Subscription status is set to active and the validity is set in the activeUntil parameter.
  • A subscription_paid event notification is triggered.
  • Charge status is set to completed.
  • A charge_completed notification is sent.

Future payments must be completed before the activeUntil date. This date is calculated by adding a time period to the activeUntil value, or to the time at which the charge is completed. This time period is intervalCount number of interval periods to the current. If the initial payment terms have been set, the first activeUntil date is set after initialIntervalCount number of initialInterval periods.

# Accept future payments

For these payments, an invoice is created, a few days before the subscription is due. The number of days is specified in invoiceNotice.

  • An subscription_invoice_due API notification is sent along with an Invoice object.
  • The Invoice object contains all the relevant information required to generate an invoice and accept payment including a checkoutLink.
  • The Invoice object also contains the invoice due date in the invoiceDueOn parameter. This is the same as the activeUntil parameter of the subscription.
  • If the subscription has the sendEmail flag enabled, then the customer also receives an email from XanPay.

When a customer confirms their details and clicks Pay, they receive payment instructions and can proceed with the payment. Once the customer makes the payment, the subscription is activated. Subscription status is set to active and the validity is increased in the activeUntil parameter. Notifications are described here.

# Paused subscriptions

If the payment is not made by date of renewal, subscription remains active until the grace period (gracePeriod) is over. If the grace period ends and payment has not been completed, the subscription is paused. The subscription_paused notification is sent.

Whenever the customer makes the payment, subscription is re-activated and the next payment is scheduled as described here.

# Completed subscriptions

A subscription is completed if all the payments have been completed.

# List of notifications

Event Data
subscription_created Subscription object with status inactive
subscription_invoice_due Invoice object
subscription_paid Subscription object with status active
subscription_paused Subscription object with status inactive
subscription_cancelled Subscription object with status cancelled
subscription_completed Subscription object with status completed

# FAQ

Q: What if a customer makes multiple payments? A: Next payment date is adjusted accordingly.

Q: What if a customer pays more than required for the entire subscription? A: A refund would need be created associated with the related charges on the dashboard.