Overview

This topic describes the process flow and API reference for an Independent Software Vendor (ISV) to offer benefits in the super app.

Prerequisites

Before you start, learn how APIs work and how requests and responses are structured:

• Message structure

Message structure mainly includes request header, request body, response header, and response body.

• Idempotency

If an API call is idempotent, it returns the same result no matter how many times the API call is made.

• Message signing

Message transmission security is guaranteed by signing a request and validating the signature of the response.

Message signing and signature validation are mandatory for all requests and responses.

• Error codes

If an error occurs when the ISV calls an API, the error code and the error message are returned in the

response for troubleshooting.

How it works

To offer a benefit to an user, refer to the following process flow:

Flow 1: Synchronize benefit

The ISV first needs to synchronize the benefit to our server. The corresponding data flow is illustrated as below:

1. The ISV server calls the syncBenefit API to request to synchronize the benefit to our server.
2. Our server returns the result of whether the request of the benefit synchronization is accepted by our server.
3. Our server reviews the benefit.
4. When the benefit fails to pass our review, our server calls the notifyBenefitSync API to asynchronously send the reason for failure to the ISV.
5. Our server performs the internal processing.
6. When the internal processing fails, our server calls the notifyBenefitSync API to asynchronously send the reason for failure to the ISV.
7. When the internal process succeeds, our server synchronizes the benefit to the super app server. (At this moment, the operator of the super app does not release the benefit, which means users cannot view and collect the benefit in the super app.)
8. The super app server returns the result of benefit synchronization to our server.
9. Our server calls the notifyBenefitSync API to notify the ISV server of the synchronization result.
10. The ISV server returns the result of whether it received the notification from our server.
11. In addition, the ISV can call the inquireBenefitSync API to inquire about the synchronization result anytime.
12. Our server returns the inquiry result to the ISV server.

Flow 2: Issue benefit

After the operator of the super app manually releases the benefit, users can view and collect the benefit. The corresponding data flow is illustrated as below:

1. A user collects the benefit in the super app.
2. The super app server requests our server to issue the benefit.
3. Our server calls the issueBenefit API to request the ISV server to issue the benefit to the user.
4. The ISV returns the result of the issuing to our server.

• When the ISV server issues the benefit successfully, the user collects the benefit successfully.
• When the ISV server fails to issue the benefit due to errors that cannot be retried, the user fails to collect the benefit.
• When the ISV server fails to issue the benefit due to errors that can be retried or when the super app does not receive the issuing result, the super app server re-initiates the request multiple times. (The number of times to re-initiate the request is defined by the super app.) When the ISV issues the benefit successfully after multiple retries, the user collects the benefit successfully.

5. Our server returns the issuing result to the super app server.
6. When the ISV still fails to issue the benefit after multiple retries, the super app server requests our server to reverse the issuing.
7. Our server calls the reverseBenefitIssue API to reverse the issuing. (After the reversal, the benefit is still available in the super app for the user to collect.)
8. The ISV returns the reversal result to our server.
9. Our server returns the reversal result to the super app server.
10. The super app server returns the issuing result or the reversal result to the user. (The user fails to collect the benefit when the reversal is successful.)
11. In addition, our server can call the inquireBenefitIssue API to inquire about the result of the issuing anytime.
12. The ISV server returns the inquiry result to our server.

Flow 3: Synchronize used benefit

When the user redeems the benefit in a mini program, the ISV synchronizes the used benefit to the super app for deactivating. Then the used benefit cannot be further used. The corresponding data flow is illustrated as below:

1. The user uses the benefit in a mini program.
2. The mini program server requests the ISV server to deactivate the used benefit.
3. The ISV server deactivates the used benefit.
4. The ISV server returns the result of deactivating to the mini program server.
5. The mini program server returns the result to the user. The user knows whether the benefit is used successfully.
6. The ISV server calls the syncUsedBenefit API to synchronize the used benefit to our server.
7. Our server synchronizes the used benefit to the super app server.
8. The super app server deactivates the used benefit.
9. The super app server returns the result of deactivating to our server. When the deactivating is successful, the used benefit cannot be further used.
10. Our server returns the result to the ISV server.

API list

Refer to the following two tables for the APIs that are used in the above process flow, along with their descriptions.

APIs developed by us

APIs developed by the ISV

Before you dive into the specific content of each API, learn the following notes:

• The ISV should develop the APIs based on the following requirements:

• The business process of benefit offering is defined by us.
• The request parameters, response parameters, and error codes are defined by us.

• If the ISV returns an error code not defined by us, we will handle it as a system error.