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.

Subscription link

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.