Concepts
When using our subscriptions product, it is important to understand several terms and concepts before proceeding. In this section, we will outline the main pieces of information required to start using recurring.
Types of subscriptions
Our current subscriptions product only supports “PAYMENT” (our money-in products) as a subscriptions type.
PAYMENT subscriptions action - commonly known as subscriptions, Xendit can help merchants collect payments on a scheduled basis (yearly/ monthly/ weekly) as defined by our merchants.
It is important to note that "PAYMENT" subscriptions action only works for payment channels with auto debit/ merchant initiated transactions enabled (merchants can deduct end users’ balance directly without any PIN or OTP). End users will need to perform a one-time authorization with the payment provider before Xendit can charge the end user on a scheduled basis.
Account Linking (for PAYMENT subscriptions type)
Tokenization/ 3DS/ account linking is the crucial first step to start using the Xendit subscriptions product for payments. There are 2 ways to complete account linking for end users -
- Using Xendit's account linking UI
- Merchants building their own UI (with PCI DSS)
Merchants will have to redirect the end user to either (1) or (2) to select payment methods and input their OTP and/or PIN with the payment provider. Once that is completed, merchants will receive an ID called payment_method_id which will be used when communicating with Xendit on which payment method to use in the subscriptions plan.
Subscriptions Concepts
To understand how subscriptions works in Xendit, there are several concepts that developers have to grasp. These concepts relate to the data and objects which are used in our process to help merchants with their subscriptions set up.
| Concept | Description |
|---|---|
| Customer Object | The data object about the end user. Xendit uses this to send notifications, display relevant subscriptions information, or payment methods related to the end user. |
| Schedule Object | The data object about the logic of when a subscriptions action should happen. This object contains merchant defined information about subscriptions timings - i.e. the intervals (day/ month/ year) between each payment. For example, if a merchant wants to collect payments every quarter, the schedule is set up within this object. |
| Plan Object | The key data object that will help you orchestrate your subscriptions logic. subscriptions plan object will take in the customer object, schedule object (optional), and payment_method_id (optional) to set up the subscription for a particular end user. The subscriptions plan object also takes in other parameters for more detailed customization (e.g. notifications, immediate payments). |
| Cycle Object | The data object that is auto-generated based off the subscriptions plan object. Each subscriptions cycle object represents an individual billing instance (for a monthly subscriptions plan set up for a year, there will be 12 subscriptions cycles generated). Ad hoc changes can be made for a specific cycle without affecting the base subscriptions plan object. The subscriptions plan object has a one to many relationship with the subscriptions cycle object. |
| Attempts | A subscriptions attempt refers to each individual subscriptions action (e.g. payments) made in order to succeed the subscriptions cycle object. A subscriptions cycle can have multiple attempts depending on the retry configuration (e.g. if a cycle has 2 retries configured, there can be up to a total of 3 attempts). All subscriptions attempts will be stored and nested within the subscriptions cycle object. The subscriptions cycle object has a one to many relationship with subscriptions attempts. |
| action_id | action_id refers to the unique ID of the action associated with each attempt (e.g. payment_id). In one run of an attempt, there can be multiple action_id if the merchant configured multiple payment methods during the creation of subscriptions plan. Based on the rank of each payment method, Xendit will run through each payment method until we receive either one successful payment or if all payments failed. A subscriptions attempt has a one to many relationship with action_id. |
Subscriptions Entities Relationship Diagram
Last Updated on 2023-05-23