Help Center/ KooGallery/ Access Guide/ SaaS Access Guide V1.0 (Existing Products)/ Interface Description/ Subscription
Updated on 2024-08-20 GMT+08:00
View PDF
Share

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. Use businessId provided by KooGallery to ensure that instanceId is globally unique.

    Pay-per-use products are traded by specification. If a specification in an order has multiple pay-per-use billing items, you need to create instances for these billing items separately based on orderId (the same order ID) and productId (different product IDs). That is, in pay-per-use transactions, an order has multiple instances.

  • 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, your server must ensure idempotency.

    KooGallery may resend requests for a single order. If receiving a duplicate order, your server needs to return a success response and the information about the successfully created app instance, rather than create a SaaS instance.

    In pay-per-use transactions, ensure idempotency based on the order ID (orderId) and product ID (productId).

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 you. You need to provide services based on requests.

Request method: GET

Parameter

Mandatory

Type

Maximum Length

Description

authToken

Yes

String

50

Security verification token.

For details about the values, see authToken Value.

timeStamp

Yes

String

20

UTC timestamp when a request is initiated.

Format: yyyyMMddHHmmssSSS

activity

Yes

String

20

Request ID, which is used to distinguish the scenario.

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.

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

For details about the example code of mobile number decryption, 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.

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

For details about the example code of email address decryption, 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

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, productId corresponding to 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 different billing modes under the same skuCode.

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 required for a yearly/monthly/daily product.
  • This parameter is required for a pay-per-use package.
  • This parameter is not required for a pay-per-use specification.
  • This parameter is not required for a product billed by uses.
  • 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.

5: pay-per-use package.

saasExtendParams

No

String

2,048

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, your 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/daily product or pay-per-use package subscriptions (the value of chargingMode is set to 1 or 5).

Yearly subscription: year

Monthly subscription: month

Daily subscription: day

If chargingMode is set to 3 or 0, do not pass this parameter.

periodNumber

No

integer

5

Number of periods.

NOTE:

This parameter is only required for yearly/monthly/daily product or pay-per-use package subscriptions (the value of chargingMode is set to 1 or 5).

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

Description

resultCode

Yes

String

6

Result code.

For details, see Invocation Result Codes.

resultMsg

No

String

255

Result message.

encryptType

No

String

2

Algorithm 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.

Use businessId provided by KooGallery to ensure that instanceId is globally unique.

NOTE:

The value of businessId in each request sent by KooGallery is different. If you use businessId as instanceId, use 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 app instance.

appInfo

No

AppInfo

N/A

App instance information.

After a customer purchases a product, return a login address (website address) or an 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 app 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 response. Otherwise, the app instance information must be returned in the 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 AppInfo data structure.

Parameter

Mandatory

Type

Maximum Length

Description

frontEndUrl

Yes

String

512

Frontend URL.

URL of the website that the customer can access to use the purchased product.

adminUrl

No

String

512

Management URL.

URL of the backend website that the customer can access to manage the purchased product.

userName

No

String

128

Encrypted administrator account.

Account (usually an email address or mobile number) used by a 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.

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

password

No

String

128

Encrypted initial password of the administrator.

Password (usually generated by you) used by a customer to access the management backend. The value consists of a 16-bit encryption IV and a Base-encoded password ciphertext.

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

ip

No

String

64

IP address of the website.

memo

No

String

1,024

Remarks.
  • For details about how to obtain accessKey, see Obtaining the Key.
  • The lengths of the username and password ciphertexts are verified, which include the IVs.
  • When processing an interface request, your server must ensure idempotency.

    KooGallery may resend requests for a single order. If receiving a duplicate order, your server needs to return a success response and the information about the successfully created app instance, rather than create a SaaS instance.

  • If a SaaS instance information (for example, the adminUrl) changes, call the interface again in KooGallery. When the same orderId is provided by KooGallery, your 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==",
        "memo":"Test"
    }
}

Parent topic: Interface Description