API Create plan

Endpoint: /api/v1/subs/plans

Method: POST

Header Params

Param	Required	Type	Description	Note
X-APPOTAPAY-AUTH	required	String	How to generate JWT_TOKEN
Content-Type	required	String	Value: application/json
X-Request-ID	optional	String	UUIDv4 format. Request ID to check when a problem occurs	max:42
Language	optional	String	The value vi or en corresponding to the payment link will be Vietnamese or English, (default: vi)	in:vi,en

{
    "X-APPOTAPAY-AUTH": "JWT_TOKEN",
    "Content-Type": "application/json",
    "X-Request-ID": "Your_Unique_id",
    "Language": "vi"
}

Request params

Param	Required	Type	Description	Note
partnerRefId	Required	String	Unique reference code of partner	min:1, max: 50, format: alphanumeric
customerId	Required	String	Customer ID
currency	Required	String	Currency unit	in: VND
amount	Required	Integer	Payment amount
paymentMethods	Required	Array	Payment method list
paymentMethods.*.paymentMethodId	Required	String	Payment method ID
paymentMethods.*.rank	Required	Integer	Indicate the order which payments methods will be attempted for a payment cycle instance. Available values - 1 to 5	min: 1
immediateActionType	Optional	String	Charge immediately when successfully creating the plan, null: charge at anchorDate time - FULL_AMOUNT: charge when successfully initializing the plan	in: FULL_AMOUNT
failedCycleAction	Required	String	Action of plan when the payment cycle fails - STOP: Stop the plan - RESUME: Skip the failed cycle and proceed to the next cycle	in: STOP, RESUME
schedule	Required	Object	Object containing the configurations of how Subscriptions cycles will be scheduled
schedule.interval	Required	String	The type of interval between consecutive Subscriptions cycles.	in: DAY, WEEK, MONTH
schedule.intervalCount	Required	Integer	The number of units of interval between consecutive Subscriptions cycles	min: 1
schedule.totalRecurrence	Optional	Integer	The total number of times the end user will be charged If the parameter is not used, Subscriptions plan will run on indefinitely	min: 1
schedule.anchorDate	Optional	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	format: ISO-8601
schedule.retryInterval	Optional	String	The type of interval between failed attempt and retries.	in: DAY
schedule.retryIntervalCount	Optional	Integer	The number of times you will retry a failed Subscriptions cycle. If no value is passed into	min:1
schedule.totalRetry	Optional	Integer	The number of times you will retry a failed Subscriptions cycle. If no value is passed into total_retry, it will be null by default and no retries will be triggered	min:1, max: 10

Example Request

{
    "partnerRefId": "ASKJLKALK299",
    "customerId": "01HRVGAJSP7SX83X7AQ9QQYMBE",
    "currency": "VND",
    "amount": 85000,
    "paymentMethods": [
        {
            "paymentMethodId": "01HRVJY8ZMZFHRHE3KG2S24KKW",
            "rank": 1
        }
    ],
    "immediateActionType": "FULL_AMOUNT",
    "failedCycleAction": "STOP",
    "schedule": {
        "interval": "DAY",
        "intervalCount": 1,
        "totalRecurrence": 3,
        "anchorDate": "2024-01-13T15:23:40+07:00",
        "retryInterval": "DAY",
        "retryIntervalCount": 1,
        "totalRetry": 1
    }
}

Response data

Success

Http Status Code 200 - OK

Success responses will contain a single Plan object

Failure

HTTP Status Code != 200

Error response params

Param	Required	Type	Description
errorCode	required	Integer	Error code
message	required	String	Error message
errors	optional	Array	Detailed error description
errors.*.field	optional	String	Field data is corrupted
errors.*.reason	optional	String	Description of the data field in error

{
    "errorCode": 1,
    "message": "Missing or Invalid Params",
    "errors": [
        {
            "field": "partnerRefId",
            "reason": "The partner ref id field is required."
        }
    ]
}

Common error code table

Full error code, please check this error code list

Error code	Description
0	Success
1	Missing or Invalid Params
11	Partner is not found
13	Partner has been blocked
14	API Key is invalid
15	API Key is not activated or blocked
92	IP is not allowed to access
99	Undefined error, please contact AppotaPay for more detailed information
401	Unauthorized
500	Server error
3002	Duplicate partnerRefId, please try again
3003	Customer not exist
3004	Payment method not exist
3012	Payment method is invalid