topup
POST /v2/pds/memberships/topup
With this API call, Mini Program Platform can request the merchant to top up a user's membership card.
The message structure of this API is defined by us. Follow the specifications below when the merchant develops this API.
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 |
requestOrderId | String | Yes | Indicates the unique ID assigned by Mini Program Platform to identify a top-up order.
Note: This field is an API idempotency field. For the topup requests that are initiated with the same requestOrderId value, the merchant must return the same result. For details about API idempotency, see the Idempotency chapter. | "TOPUP_2109220000014775***" |
cardNo | String | Yes | Indicates the unique card number generated by Mini Program Platform to identify a card, which is returned in the issueCard API.
| "CARD_12232332321***" |
topupAmount | Yes | Indicates the amount to top up. | { "currency": "SGD", "value": 100 } | |
extendInfo | String | No | Indicates the extended information about this API.
Note: Specify the paymentAmount parameter that indicates the actual amount paid for the top-up, which is in JSON format containing an Amount object. | { "paymentAmount": { "currency": "SGD", "value": 100 } } |
Response parameters
Field | Data type | Required | Description |
result | Yes | Indicates the request result, such as status and error codes. | |
referenceOrderId | String | Yes | Indicates the unique ID returned by the merchant to identify a top-up order. Maximum length: 255 characters |
extendInfo | String | No | Indicates the extended information about the response.
|
Result process logic
In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:
Result status | Description |
S | The top-up is successful. The corresponding result.resultCode is |
U | The status of the top-up is unknown. The corresponding result.resultCode is For details, see the Common error codes section. |
F | The top-up failed. The corresponding result.resultCode and result.resultMessage can vary based on different situations. For details, see the following Error codes section. |
Error codes
Error codes are usually classified into the following categories:
- Common error codes are common for all Mini Program OpenAPIs in V2.
- API-specific error codes:
Error code | Result status | Error message |
EXPIRED_CRM_BIND_TOKEN | F | The CRM authentication token of the user is expired. |
Samples
The data flow of sending a request to top up a user's membership card is illustrated as follows:
The above diagram consists of the following steps:
- Mini Program Platform calls this API to send the top-up amount (specified in the topupAmount parameter) and the card number (specified in the cardNo parameter) to the merchant.
- The merchant processes the request and adds the top-up amount to the prepaid card with the card number.
- The merchant returns the top-up transaction result to Mini Program Platform.
Request
{
"requestOrderId": "TOPUP_2109220000014775***",
"cardNo": "CARD_12232332321***",
"topupAmount": {
"currency": "SGD",
"value": 100
},
"extendInfo": {
"paymentAmount": {
"currency": "SGD",
"value": 100
}
}
}
Response
{
"referenceOrderId": "1443352",
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success",
"resultStatus": "S"
}
}
result.resultStatus
is S
, which means the top-up is successful.