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.

  • Maximum length: 255 characters

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.

  • Maximum length: 64 characters.
  • Characters not allowed: special characters such as @, #, ?

"CARD_12232332321***"

topupAmount

Amount

Yes

Indicates the amount to top up.

{

"currency": "SGD",

"value": 100

}

extendInfo

String

No

Indicates the extended information about this API.

  • Maximum length: 2048 characters
  • Characters not allowed: special characters such as @ # ?

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

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.

  • Maximum length: 2048 characters
  • Characters not allowed: special characters such as @ # ?

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 SUCCESS and result.resultMessage is SUCCESS.

U

The status of the top-up is unknown.

The corresponding result.resultCode is UNKNOWN_EXCEPTION and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.".

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:

topup

The above diagram consists of the following steps:

  1. 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.
  2. The merchant processes the request and adds the top-up amount to the prepaid card with the card number.
  3. The merchant returns the top-up transaction result to Mini Program Platform.

Request

copy
{
    "requestOrderId": "TOPUP_2109220000014775***",
    "cardNo": "CARD_12232332321***",
    "topupAmount": {
        "currency": "SGD",
        "value": 100
    },
    "extendInfo": {
        "paymentAmount": {
            "currency": "SGD",
            "value": 100
        }
    }
}

Response

copy
{
    "referenceOrderId": "1443352",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "success",
        "resultStatus": "S"
    }
}

result.resultStatus is S, which means the top-up is successful.