reverseBenefitIssue

2023-04-28 21:00

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

With this API call, our server can request an Independent Software Vendor (ISV) to reverse the issuing based on the following scenarios:

When the ISV fails to issue benefits after multiple retries. Then our server calls this API to reverse the issuing.
When the ISV successfully issue benefits to our server but our server fails to issue benefits to the super app. Then our server call this API to reverse the issuing.

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

Note:
When the reversal is successful, the budget and other related information of the benefit need to be restored for users to collect the benefit later.
When the value of quantity is greater than 1, all benefits need to be reversed successfully or this API call will fail. Partial success is not accepted.
When the ISV successfully issue multiple benefits to our server but our server fails to issue these benefits to the super app. Then our server call this API to reverse these benefits.
If all benefits are reversed successfully, the reversal is successful.
If some of benefits are failed to reverse, the reversal is failed.
When the ISV fails to issue benefits after multiple retries. Then our server calls this API to reverse these benefits. In this scenario, the reversal must be successful.
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

benefitIssueRequestId

String

Yes

Indicates the unique ID assigned by our server to identify a issuing to be reversed.

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 requests to reverse the benefit issuing which are initiated with the same benefitIssueRequestId, the ISV must return the same result. For details about API idempotency, see the Idempotency chapter.

Response parameters

Field	Data type	Required	Description	Example
success	Boolean	Yes	Indicates whether the reversing is successful.	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.	-

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.

Samples

Request

copy
{
    "benefitIssueRequestId": "20211111010101000001234"
}

Response

copy
{
    "success": true,
    "resultCode": "",
    "resultMessage": ""
}

Error code	Result status	Error message	Further action
ISSUE_REQUEST_ID_NOT_EXIST	F	When the issuing request ID does not exist and the ISV does not have the corresponding issuing record, we consider that the issuing does not need to be reversed.	Check the issuing request ID and try again later.
CANNOT_REVERSE_USED	F	The issuing failed to be reversed because the benefit has already been used.	-