Subscription
Description
- After a customer purchases a product and pays for it successfully, KooGallery calls this interface to send you a request containing information about the product and customer. When receiving the request, the ISV server executes product subscription and informs KooGallery about the subscription result.
- A unique instance ID (instanceId) should be returned for the order. The instance IDs (instanceId) of different subscription orders must be different. You are advised to use the businessId provided by KooGallery to ensure that the instanceId is globally unique.
- If the interface fails to respond, KooGallery will notify you by sending an email to the email address bound to your Huawei Cloud account. The interface exception information will be displayed on the Transaction Management > Service Interface Messages page. Rectify the exception as soon as possible to avoid order cancellation.
If the subscription interface fails to be called, KooGallery will retry to call it 60 times (once every three minutes). If the interface exception is resolved, the next call will be successful and the order is placed successfully. Otherwise, KooGallery determines that the order fails to be placed and automatically cancels the order. If more than five orders failed in a month due to interface failures, KooGallery will remove the product from the catalog.
- Check the email address bound to your Huawei Cloud account and the Message Center. If you receive an email or message about an interface calling failure, resolve the exception as soon as possible.
- KooGallery monitors interface exceptions. If subscriptions to a SaaS product frequently fail due to interface exceptions, KooGallery will remove the product from the catalog.
- When processing an interface request, the ISV server must ensure idempotence.
KooGallery may resend requests for a single order. If receiving a duplicate order, the ISV server needs to return a success response and the information about the successfully created application instance, rather than create a new SaaS instance.
The following figure shows the process of purchasing a product.
Request Message
The following table describes the request parameters. In KooGallery, requests are generated based on the subscription mode of products released by sellers. You need to provide services based on requests.
Request method: GET
Parameter |
Mandatory |
Type |
Maximum Length of Characters |
Description |
---|---|---|---|---|
authToken |
Yes |
String |
50 |
Security verification token. For details, see authToken Value. |
timeStamp |
Yes |
String |
20 |
Time (UTC time) when a request is initiated. Format: yyyyMMddHHmmssSSS |
activity |
Yes |
String |
20 |
Interface request ID, which is used to distinguish interface request scenarios. For new subscriptions, the value is newInstance. |
customerId |
Yes |
String |
100 |
Unique ID of a customer on Huawei Cloud. |
customerName |
No |
String |
64 |
Customer's username on Huawei Cloud. |
userId |
No |
String |
64 |
Unique ID mapping the username used to log in to the system as an Identity and Access Management (IAM) user. Optional. If this parameter is required, select To create an account based on IAM username for User Authorization Required when releasing the product. |
userName |
No |
String |
64 |
Username of the customer used to log in to the system as an IAM user. Optional. If this parameter is required, select To create an account based on IAM username for User Authorization Required when releasing the product. |
mobilePhone |
No |
String |
256 |
Customer's mobile number. Optional. If this parameter is required, select To create an account based on phone number for User Authorization Required when releasing the product. The value is an encrypted mobile number. The mobile number encryption rules are as follows: The value consists of a 16-bit encryption initialization vector (IV) and a Base-encoded mobile number ciphertext, as follows:
For an example of the mobile number decryption code, see ISV Server Decrypting the Mobile Number and Email Address.
NOTE:
This parameter does not contain the country code. If a customer does not bind the mobile number, the parameter cannot be obtained. |
No |
String |
256 |
Customer's email address. Optional. If this parameter is required, select To create an account based on email address for User Authorization Required when releasing the product. The value is an encrypted email address. The email address encryption rules are as follows: The value consists of a 16-bit encryption IV and a Base-encoded email ciphertext, as follows:
For an example of the email address decryption code, see ISV Server Decrypting the Mobile Number and Email Address. |
|
businessId |
Yes |
String |
64 |
KooGallery business ID. The value of businessId is different for each request. |
orderId |
Yes |
String |
64 |
KooGallery order ID. |
skuCode |
No |
String |
64 |
Product specification ID. When renewing the subscription of a yearly/monthly product, a customer can change the billing mode (for example, from monthly to yearly). In this case, the productId corresponding to the instanceId of the instance enabled by the customer changes, but the value of skuCode does not change.
NOTE:
After a product is approved and successfully released to KooGallery, you can obtain this parameter in the Seller Console. On the Product Management > My Products page, locate the product and click Details in the Operation column. The parameter can be obtained on the displayed page. |
productId |
Yes |
String |
64 |
Product ID. The value of productId varies between products of the same skuCode depending on the billing mode. For example, when you release a product and add a new specification, an skuCode value is generated. After yearly and monthly billing prices are configured, two productId values are generated.
NOTE:
After a product is approved and successfully released to KooGallery, you can obtain this parameter in the Seller Console. On the Product Management > My Products page, locate the product and click Details in the Operation column. The parameter can be obtained on the displayed page. |
testFlag |
No |
String |
2 |
Whether a request is submitted for debugging.
|
trialFlag |
No |
String |
2 |
Whether an instance is created for a trial.
|
expireTime |
No |
DateTime |
20 |
Expiration time. Format: yyyyMMddHHmmss
NOTE:
|
chargingMode |
No |
Integer |
[3] |
Billing mode. 0: pay-per-use. 1: yearly/monthly/daily. 3: one-time payment. |
saasExtendParams |
No |
String |
2048 |
Extension parameters. These parameters are optional. The extension parameters are a JSON string carried in the url parameter in the form of urlEncode(base64(saasExtendParams)). After obtaining the value of the saasExtendParams parameter, the ISV server needs to use base64Decode(urlDecode(saasExtendParams)) to obtain the JSON string of the extension parameters. For example, emailDomainName and extendParamName in the JSON string [{"name":"emailDomainName","value":"test.xxxx.com"},{"name":"extendParamName","value":"extendParamValue"}] are the parameter values set during product release. |
amount |
No |
Integer |
4 |
Product attribute of the quantity type. This parameter is optional. Attribute name: quantity (customizable) Unit: none
NOTE:
When customers subscribe to multi-SKU SaaS products (billing mode: yearly/monthly or one-time) with specifications that contain the quantity type attribute, they specify or modify the number or usage times. Example: 30 users |
diskSize |
No |
Integer |
4 |
Product attribute of the quantity type. Optional. Attribute name: disk size (customizable) Unit: GB
NOTE:
When customers subscribe to multi-SKU SaaS products (billing mode: yearly/monthly or one-time) with specifications that contain the disk size attribute, they specify or modify the disk size. Example: 100 GB |
bandWidth |
No |
Integer |
4 |
Product attribute of the quantity type. Optional. Attribute name: bandwidth (customizable) Unit: Mbit/s
NOTE:
When customers subscribe to multi-SKU SaaS products (billing mode: yearly/monthly or one-time) with specifications that contain the bandwidth attribute, they specify or modify the amount of bandwidth. Example: 20 Mbit/s |
periodType |
No |
String |
10 |
Period type.
NOTE:
This parameter is only required for yearly/monthly product subscriptions (the value of chargingMode is set to 1). Yearly subscription: year Monthly subscription: month Daily subscription: day If chargingMode is set to 3, do not transfer this parameter. |
periodNumber |
No |
Integer |
5 |
Number of periods.
NOTE:
This parameter is only required for yearly/monthly product subscriptions (the value of chargingMode is set to 1). Enter a positive integer, for example, 1, 2, and 3. |
orderAmount |
No |
bigdecimal |
20 |
Order amount.
NOTE:
This parameter is required only for common product subscriptions. The amount is the actual payment amount, which you can check during reconciliation. The amount is greater than or equal to 0 and can contain a maximum of three decimal places. Unit: USD |
provisionType |
No |
Integer |
2 |
Instance provisioning mode.
NOTE:
|
acceptanceTime |
No |
String |
20 |
Acceptance time.
NOTE:
The value is the time when billing for the product starts. If provisionType is set to Provision after acceptance, this parameter is required. Format: yyyyMMddHHmmssSSS |
startTime |
No |
String |
20 |
Start time. Format: yyyyMMddHHmmss
NOTE:
This parameter is transferred only for pay-per-use packages. |
- On May 12, 2018, interface parameters trialFlag and skuCode were added.
- Set these parameters for products released or product specifications added after May 12, 2018. All three values of trialFlag must be successfully debugged.
- If a product was successfully released before May 12, 2018 and does not involve the free trial, the interface debugging is not required.
- On August 9, 2018, the interface for releasing SaaS products whose billing mode is one-time was added. If this billing mode is selected for a product release, the interface must be successfully debugged based on the SaaS Product Access Guide.
- On September 27, 2019, interface parameters amount, diskSize, and bandWidth were added for attributes of the quantity type.
If product specifications that are priced using a custom template contain attributes of the quantity type, such as number, bandwidth, and disk size, create the attributes on the product attribute management page, and navigate to the Application Access Debugging page to set related parameters and debug the interfaces. After the debugging is successful, you can release the product specifications.
- For details, see Interface Debugging.
Example request:
https://isvserver.com/produceAPI?activity=newInstance&businessId=03pf80c2bae96vc49b80b917bea776d7&customerId=3736bb8ad93b43fca8012c64a82cec25 &expireTime=20180725000000&orderId=HWS001014ED483AA1E8&productId= 005a8781ef0c4a47a3dbfc4c1e72871e&saasExtendParams=W3sibmFtZSI6ImVtYWlsMTEiLCJ2YWx1ZSI6ImVtYWlsMTFlbWFpbDExIn0seyJuYW1lIjoiZW1haWwyMiIsInZhbHVlIjoiZW1haWwyMmVtYWlsMjIifV0%3D&timeStamp=20170725025113409&testFlag=0&authToken=09lsS5y+KCtxBu+ON4TXv1SrjH5KVYka9sx2MauHrQU=
Response Message
The following table describes the response parameters.
Parameter |
Mandatory |
Type |
Maximum Length of Characters |
Description |
---|---|---|---|---|
resultCode |
Yes |
String |
6 |
Invocation result code. For details, see Invocation Result Codes. |
resultMsg |
No |
String |
255 |
Invocation result description. |
encryptType |
No |
String |
2 |
Algorithms for encrypting sensitive information. 1: AES256_CBC_PKCS5Padding (default) 2: AES128_CBC_PKCS5Padding
NOTE:
If the value of this parameter is AES256_CBC_PKCS5Padding, 1 is returned; if the value is AES128_CBC_PKCS5Padding, 2 is returned. |
instanceId |
No |
String |
64 |
Instance ID, which is a unique ID provided by a seller. You are advised to use the businessId provided by KooGallery to ensure that the instanceId is globally unique.
NOTE:
The businessId in each request sent by KooGallery is different. If you use the businessId as the instanceId, use the businessId in the first request sent by KooGallery. If instanceId is generated in other ways, for example, using a universally unique identifier (UUID), ensure that it is globally unique. Identical values of instanceId will cause a failure of enabling a SaaS application instance. |
appInfo |
No |
AppInfo |
N/A |
Application instance information. After a customer purchases a product, return a service login address (website address) or an access address that does not require login for the customer to perform subsequent operations.
NOTE:
You must provide customers who purchase your SaaS products with the application usage information, including the addresses, accounts, and passwords. If the usage information can be sent through SMS messages, emails, or other methods, this parameter is not required in the interface response. Otherwise, the application instance information must be returned in the interface response. You can use the memo parameter to specify usage instructions or other information if any. appInfo is a JSON string. For details about its data structure, see the following table. |
The following table describes the data structure of appInfo.
Parameter |
Mandatory |
Type |
Maximum Length of Characters |
Description |
---|---|---|---|---|
frontEndUrl |
Yes |
String |
512 |
Frontend URL. URL of the website that the customer can access to use the subscribed product. |
adminUrl |
No |
String |
512 |
Management address. URL of the backend website that the customer can access to manage the subscribed product. |
userName |
No |
String |
128 |
Encrypted administrator account. The account (usually an email address or mobile number) used by the customer to access the management backend of the seller after purchasing a product. The value consists of a 16-bit encryption IV and a Base-encoded username ciphertext, as follows:
|
password |
No |
String |
128 |
Encrypted initial password of the administrator. The password (usually generated by the seller) used by the customer to access the administration backend of the seller after purchasing a product. The value consists of a 16-bit encryption IV and a Base-encoded password ciphertext, as follows:
|
ip |
No |
String |
64 |
IP address of the website. |
memo |
No |
String |
1024 |
Remarks. |
- For details about how to obtain the accessKey, see Obtaining the Key.
- The lengths of the username and password ciphertexts are verified, which include the IVs.
- When processing an interface request, the ISV server must ensure idempotence.
KooGallery may resend requests for a single order. If receiving a duplicate order, the ISV server needs to return a success response and the information about the successfully created application instance, rather than create a new SaaS instance.
- If a SaaS instance information (for example, the adminUrl) changes, invoke the interface again in KooGallery. When the same orderId is provided by KooGallery, the ISV server returns information about the updated SaaS instance information.
For security purposes, KooGallery does not store SaaS instance information for a long time.
In the ISV production interface response messages, only the value of the memo parameter can include Chinese characters.
Example response:
{ "resultCode":"000000", "resultMsg":"success.", "instanceId":"03pf80c2bae96vc49b80b917bea776d7", "encryptType":"1", "appInfo":{ "frontEndUrl":"http://www.isvserver.com", "adminUrl":"http://www. isvserver.com", "userName":"luQg154bx766030TobyT0ghfQRx3tvVEdpwMRg==", "password":"7Bx4DyX7980a59T0qbhnpfhCz82Uc5cZQQtExg==" } }
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot