Version: Lastest

Plan Object

Subscriptions plan object will take in the customer object, schedule object to set up the subscription payments behaviour for a particular end user.

Each object has the following structure:

Param	Type	Description
planRefId	String	Unique reference code of partner. Partner-provided identifier for the plan.
planId	String	AppotaPay-generated subscription plan ID
customerId	String	Customer ID
currency	String	Currency unit
amount	Integer	Payment amount
paymentMethods	Array	Payment method list (Only show if the integration model is Merchant hosted)
paymentMethods.*.paymentMethodId	String	Payment method ID
paymentMethods.*.rank	Integer	Indicate the order which payments methods will be attempted for a payment cycle instance. Available values - 1 to 5
immediateActionType	String	Charge immediately when successfully creating the plan, null: charge at anchorDate time - FULL_AMOUNT: charge when successfully initializing the plan
failedCycleAction	String	Action of plan when the payment cycle fails - STOP: Stop the plan - RESUME: Skip the failed cycle and proceed to the next cycle
serviceName	String	Service name of subscription plan (Only show if the integration model is Checkout Page)
status	String	Status: - PENDING: request to initiate plan has been sent, wait exact status from AppotaPay - REQUIRES_ACITON: additional actions need to be performed to activate plan - ACTIVE: plan is activated to perform recurring payment with specific schedule - INACTIVE: plan is inactivated or created unsuccessfully
actions	Array	If status is REQUIRES_ACTION, the object has specific information to perform the next action to activate the payment method
actions.*.url	String	URL to perform action
actions.*.action	String	The purpose the corresponding action - AUTH: Trigger this action in order to authorize linking or payment - RESEND_AUTH: Trigger this action in order to resend the authorization code to the end-customer - PAY : Trigger this action in order to input payment information and make a payment (this action is only show with the Checkout Page model)
actions.*.method	String	HTTP method for calling the url. - GET - POST
schedule	Object	Object containing the configurations of how Subscriptions cycles will be scheduled
schedule.interval	String	The type of interval between consecutive Subscriptions cycles
schedule.intervalCount	String	The number of units of interval between consecutive Subscriptions cycles
schedule.totalRecurrence	Integer	The total number of times the end user will be charged If the parameter is not used, Subscriptions plan will run on indefinitely
schedule.anchorDate	String	Time to make recurring payments Default: the date of schedule creation Supported values: Timestamps between 1st to 28th of a month Note: if anchorDate is null or date of schedule creation falls on 29/30/31, anchor date will be defaulted to 1st of next month
schedule.retryInterval	String	The type of interval between failed attempt and retries.
schedule.retryIntervalCount	Integer	The number of units of retryInterval between consecutive retries
notificationConfig.[subscription.cycle.retrying]	Array	Specify which channel you want to notify your customer through when the cycle is unsuccessful, so it's necessary to attempt the next time Accepted value ["EMAIL"]
notificationConfig.[subscription.cycle.succeeded]	Array	Specify which channel you want to notify your customer through when the cycle is successfully completed Accepted value ["EMAIL"]
notificationConfig.[subscription.cycle.failed]	Array	Specify which channel you want to notify your customer through when the cycle failed Accepted value ["EMAIL"]
notificationConfig.[subscription.plan.activated]	Array	Specify which channel you want to notify your customer through when the subscription plan is activated Accepted value ["EMAIL"]
notificationConfig.[subscription.plan.inactivated]	Array	Specify which channel you want to notify your customer through when the subscription plan is inactivated Accepted value ["EMAIL"]
currencyExchange	Object
currencyExchange.amount	Number	Exchange amount Supports 2 decimals, eg: 12.02
currencyExchange.currency	String	Currency unit Support: USD
createdAt	String	Creation time (standard format: ISO-8601)
updatedAt	String	Last updated time (standard format: ISO-8601)

Example

{
    "planRefId": "ASKJLKALK299",
    "planId": "01HRVJZV0W9NK63SDDXHW04T9H",
    "customerId": "01HRVM5AA6JCKZJ8ERZ6MKKFJZ",
    "currency": "VND",
    "amount": 85000,
    "paymentMethods": [
        {
            "paymentMethodId": "01HRVM7BFCP1QH7R6MFPASVH0W",
            "rank": 1
        }
    ],
    "immediateActionType": "FULL_AMOUNT",
    "failedCycleAction": "STOP",
    "status": "PENDING",
    "actions": [],
    "schedule": {
        "interval": "DAY",
        "intervalCount": 1,
        "totalRecurrence": 3,
        "anchorDate": "2024-01-13T15:23:40+07:00",
        "retryInterval": "DAY",
        "retryIntervalCount": 1
    },
    "createdAt": "2024-01-29T11:36:02+07:00",
    "updatedAt": "2024-01-29T11:36:04+07:00"
}

Plan Object

Example​

Example