issueBenefit

2023-04-28 21:00

URL: https://www.isv.host:port/isv/provided/path/for/benefit/issue

With this API call, our server can request an Independent Software Vendor (ISV) to issue the benefit to a user when the user collects the benefit. The user then can redeem the benefit in mini programs, physical stores, or other scenarios.

The message structure of this API is defined by us. When the ISV develops this API, follow the specifications below.

Note:
When calling this API once, multiple benefits with the same benefitTemplateId can be issued to a user. (The number of benefits is defined by the quantity field.)
When the value of quantity is greater than 1, all benefits need to be issued successfully or this API call will fail. Partial success is not accepted. If the ISV issues all benefits successfully, the value of benefitInstanceId in the response must be the same as the value of quantity in the request.
One of the following fields must be returned in the response for the user to redeem the benefit:
benefitCode: redeem the benefit with the benefit code.
benefitCode and benefitPin: redeem the benefit with the benefit code and benefit pin.
benefitUrl: redeem the benefit with an URL.
If the ISV returns error codes not defined by us, we handle them as system errors.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field	Data type	Required	Description	Example
benefitIssueRequestId	String	Yes	Indicates the unique ID assigned by our server to identify an issuing request. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? A benefitIssueRequestId can correspond to multiple benefit instances. Note: This field is an API idempotency field. For the issuing requests which are initiated with the same benefitIssueRequestId, the ISV must return the same result. For details about API idempotency, see the Idempotency chapter.	-
userId	String	Yes	Indicates the unique ID assigned by the super app to identify a user. Maximum length: 32 characters Characters not allowed: special characters such as @ # ?	-
clientCode	String	Yes	Indicates codes to identify different super apps. Valid values are: `TRUEMONEY`: TrueMoney `ALIPAY_HK`: Alipay HK `TNG`: Touch 'n Go `ALIPAY_CN`: Alipay CN `GCASH`: Gcash `DANA`: Dana `KAKAOPAY`: KakaoPay `BKASH`: bKash `CHOPE`: Chope `LAZADA`: Lazada	-
benefitTemplateId	String	Yes	Indicates the unique ID assigned by the ISV to identify one type of benefit. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	-
quantity	Integer	Yes	Indicates the number of benefits to issue. This value is a positive integer. Value range: unlimited	-
benefitIssueDate	String	Yes	Indicates the actual time to issue the benefit. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".	UTC+05:30: "2019-04-04T12:08:56+05:30" UTC+0: "2019-04-04T12:08:56Z"
amount	Amount	No	Indicates the amount of the benefit.	-
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 2048 characters Characters not allowed: special characters such as @ # ? Can be empty. Note: This field is required when extended information is added as the business expands.	"{\"k1\":\"v1\",\"k2\":\"v2\"}"

Response parameters

Field	Data type	Required	Description	Example
success	Boolean	Yes	Indicates whether the issuing is successful. For example, "true", "false".	true
resultCode	String	No	Indicates the result codes. Maximum length: 64 characters Characters not allowed: special characters such as @ # ? Can be empty. Note: This field is required when the value of success is `false`.	-
resultMessage	String	No	Indicates the result messages that describe result codes in detail. Maximum length: 256 characters Characters not allowed: special characters such as @ # ? Can be empty.	-
benefitDetails	List<ExternalBenefitDetail>	No	Indicates the details of the benefit. Note: This field is required when the value of success is `true`.	-

Error codes

Error codes are usually classified into the following categories:

Common error codes are common across all Open APIs for ISVs.
API-specific error codes are listed in the following table:

Error code	Result status	Error message	Further action
BENEFIT_TEMPLATE_ILLEGAL	F	The benefit template is invalid.	Check the benefit template and try again later.
BENEFIT_AMOUNT_ILLEGAL	F	The benefit amount is invalid.	Check the benefit amount and try again later.
BENEFIT_OUT_OF_BUDGET	F	The benefit is out of budget.	-
FUND_OUT_OF_BALANCE	F	The balance of our server in the ISV is insufficient.	Recharge and try again later.
USER_NOT_MATCH_CONDITION	F	The user is not qualified to collect the benefit.	Inform the user of being ineligible for the benefit.

Samples

Request

copy
{
    "benefitIssueRequestId": "20211111010101000001234",
    "userId": "2088120000001234",
    "clientCode": "ALIPAY_HK",
    "benefitTemplateId": "202001010101011234",
    "quantity": 1,
    "benefitIssueDate": "2019-04-04T12:08:56+05:30",
    "amount": {
        "currency": "USD",
        "value": "100"
    },
    "extendInfo": "{\"k1\":\"v1\",\"k2\":\"v2\"}"
}

Response

copy
{
    "success": true,
    "resultCode": "",
    "resultMessage": "",
    "benefitDetails": [
        {
            "benefitInstanceId": "20211212010101000001234",
            "benefitTemplateId": "202001010101011234",
            "amount": {
                "currency": "USD",
                "value": "100"
            },
            "status": "ACTIVATED",
            "activateTime": "2019-04-04T12:08:56+05:30",
            "expireTime": "2019-05-04T12:08:56+05:30",
            "benefitCode": "QAZWSX123",
            "benefitPin": "ZXCVBN321",
            "benefitUrl": "",
            "extendInfo": "{\"k1\":\"v1\",\"k2\":\"v2\"}"
        }
    ]
}