# 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",
"apiKey": "e17052ffdddeffeec80a0497158fc084",
"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
- Create a Subscription Plan on the dashboard or using the API.
- 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 theactiveUntil
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 theactiveUntil
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.