Updated on 2024-03-05 GMT+08:00

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:

  • iv+base64(AES_CBC(accessKey,mobilePhone))
  • The number of digits to be encrypted is specified by the seller when releasing the product.

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.

email

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:

  • iv+base64(AES_CBC(accessKey,email))
  • The number of digits to be encrypted is specified by the seller when releasing the product.

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.

  • 1: debugging request.
  • 0: non-debugging request.

    The default value is 0.

trialFlag

No

String

2

Whether an instance is created for a trial.

  • 0: no.
  • 1: yes.
  • N/A

expireTime

No

DateTime

20

Expiration time.

Format: yyyyMMddHHmmss

NOTE:
  • This parameter is requested if the product is billed by yearly/monthly.
  • This parameter is not requested if the product is billed by one-time payment.
  • The expiration time is calculated based on the order creation time and product subscription duration. It may be different from the actual expiration time of the order in the request information and is for reference only. Do not use it for other purposes.

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:
  • Provision upon subscription (By default, KooGallery calls the newInstance interface in polling mode.)
  • Provision after acceptance (The SaaS product involves service supervision.)
    1. When a customer purchases the product, KooGallery calls the subscription interface, and you need to return the result code 000004 (request being processed) or 000000 (order created successfully).
    2. After you confirm to deliver the product, KooGallery calls the subscription interface, and you need to return the result code 000000.
    3. When the customer accepts the product, KooGallery calls the subscription interface and transfers the acceptance time to you. In this case, return the result code 000000.

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:

  • iv+base64(AES_CBC(accessKey,userName))

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:

  • iv+base64(AES_CBC(accessKey,pwd))

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=="
    }
}