Unified Subscription Creation

The merchant business system initiates a subscription via the Unified Subscription API, suitable for scenarios where the merchant customizes the cashier or directly integrates specific payment methods.

API Description

API

Request API: /api/subscription/unifiedCreate

Request Method: POST

Request Type: application/json or application/x-www-form-urlencoded

Request Parameters

Field Name	Variable Name	Required	Type	Example Value	Description
Merchant No	mchNo	Yes	String(30)	M1621873433953	Merchant Number
App ID	appId	Yes	String(24)	60cc09bce4b0f1c0b83761c9	App ID
Merchant Order No	mchOrderNo	Yes	String(30)	20160427210604000490	Merchant generated order number
Plan ID	planId	No	String	P_123456	Subscription Plan ID, choose one with planCode
Plan Code	planCode	No	String	PLAN_VIP_MONTHLY	Subscription Plan Code, choose one with planId
Subscription cycle	cycleIndex	integer	1	Subscription cycle
Payment Method Code	wayCode	Yes	String	KAKAO	Specific payment method code, e.g., KAKAO, ALIPAY_HK etc.
Country	country	No	String(2)	KR	Country Alpha-2 Code
Currency	currency	Yes	String(3)	KRW	Three-letter currency code
Client IP	clientIp	Yes	String(32)	210.73.10.148	Client IP address
Subject	subject	Yes	String(64)	Membership Subscription	Product title
Body	body	Yes	String(256)	Monthly membership subscription service	Product description
User ID	mchUserId	Yes	String(256)	user1008	Merchant system user ID
User Email	email	No	String(256)	abc@gmail.com	User email
Return URL	returnUrl	No	String(128)	https://merchant.com/subReturn	Sync jump Return URL for results
<!--	Extended Parameters	extParam	No	String(1024)	{"role":"vip"}
Test Mode	testMode	No	Boolean	false	Whether to force test mode
Request Time	reqTime	Yes	long	1622016572190	Request timestamp (13 digits)
API Version	version	Yes	String(3)	1.0	API version, fixed: 1.0
Sign	sign	Yes	String(32)	C380BEC2BFD727A4B6845133519F3AD6	Signature value, see signature algorithm
Sign Type	signType	Yes	String(32)	MD5	Signature type, currently only supports MD5

Request Example Data

{
  "mchOrderNo": "sub1624005107281",
  "planCode": "VIP_MONTHLY",
  "wayCode": "PAYPAL",
  "subject": "Monthly Membership",
  "body": "Premium Membership Service",
  "currency": "USD",
  "mchUserId": "user_001",
  "clientIp": "192.168.1.1",
  "notifyUrl": "https://merchant.com/notify",
  "returnUrl": "https://merchant.com/return",
  "reqTime": "1622016572190",
  "version": "1.0",
  "signType": "MD5",
  "mchNo": "M1623984572",
  "appId": "60cc09bce4b0f1c0b83761c9",
  "sign": "84F606FA25A6EC4783BECC08D4FDC681"
}

Response Parameters

Field Name	Variable Name	Required	Type	Example Value	Description
Return State	code	Yes	int	0	0-Success, others-Error, see error codes
Return Msg	msg	No	String(128)	Signature failed	Specific error reason
Sign Info	sign	No	String(32)	CCD9083A6DAD9A2DA9F668C3D4517A84	Signature for data
Return Data	data	No	Object	{}	Returned subscription data

Data Format (SubscriptionRS)

Field Name	Variable Name	Type	Example Value	Description
Subscription ID	subscriptionId	String	SUB_20210618001	Payment system subscription ID
Merchant No	mchNo	String	M1621873433953	Merchant Number
App ID	appId	String	60cc09bce4b0f1c0b83761c9	App ID
Currency	currency	String	USD	Currency
Plan ID	planId	String	PLAN_001	Subscription Plan ID
Plan Code	planCode	String	VIP_MONTH	Subscription Plan Code
Merchant Order No	mchOrderNo	String	sub1624005107281	Merchant passed order number
Merchant User ID	mchUserId	String	user_001	Merchant User ID
Payment Order ID	payOrderId	String	P202106181642329900002	Payment Order ID for refund
State	state	Byte	0	0-Init, 1-Pending, 2-Active, 3-Paused, 4-Overdue, 5-Canceled, 6-Completed, 7-Invalid
Current Period Start	currentPeriodStart	Long	1624005107281	Current billing cycle start timestamp (Optional)
Current Period End	currentPeriodEnd	Long	1626597107281	Current cycle end/next billing timestamp (Optional)
Cancel At Period End	cancelAtPeriodEnd	Boolean	false	Whether to cancel at the end of the period
Is Active	isActive	Boolean	false	Whether currently valid based on state and time
Pay Data Type	payDataType	String	payurl	payurl-Jump link method
Pay Data	payData	String	http://pay.enjoy.link/pay.html	Payment parameters used to initiate payment
Channel Err Code	errCode	String	DEFAULT_ERROR	Error code from upstream channel
Channel Err Msg	errMsg	String	Some error with system	Error description from upstream channel

Response Example Data

{
  "code": 0,
  "msg": "SUCCESS",
  "data": {
    "subscriptionId": "SUB_20210618001",
    "mchOrderNo": "sub1624005107281",
    "state": 0,
    "isActive": false,
    "payDataType": "payurl",
    "payData": "https://https://cashier-hub.enjoypayment.com/..."
  },
  "sign": "F4DA202C516D1F33A12F1E547C5004FD"
}