issueCard

POST /v2/pds/memberships/issueCard

With this API call, a merchant can issue membership cards to users.

Note: For the appId, customerBelongTo, requestId, and customerId parameters, we recommend you pass the same parameter values as those in the notifyCardRegistration API. Otherwise, an error can occur when calling 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

appId

String

Yes

Indicates the unique ID assigned by Mini Program Platform to identify a mini program.

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

Note: Obtain this field via the my.getAppIdSync JSAPI or Mini Program Platform.

"2102010113769***"

customerBelongsTo

String

Yes

Indicates the super app of the user.

Valid values are:

  • ALIPAY_CN: Alipay CN
  • ALIPAY_HK: Alipay HK
  • ALIPAY_MO: Alipay MO
  • TNG: Touch 'n Go
  • GCASH: GCash
  • DANA: DANA
  • KAKAOPAY: KakaoPay
  • BKASH: bKash
  • CHOPE: Chope
  • TRUEMONEY: TrueMoney

"TNG"

requestId

String 

Yes

Indicates the unique ID generated by Mini Program Platform to identify a request for membership card registration.

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

Note: This field is an API idempotency field. For the issueCard requests that are initiated with the same requestId value, Mini Program Platform must return the same result. For details about API idempotency, see the Idempotency chapter.

"20191127190741010007013213123****"

customerId

String

Yes

Indicates the unique ID generated by Mini Program Platform to identify a user.

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

"21091129***"

externalCustomerId

String

Yes

Indicates the unique ID generated by the merchant to identify a user.

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

"merchant_01***"

externalCardNo

String

No

Indicates the unique card number generated by the merchant to identify a membership card, which is used to display the member QR code.

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

Note: Specified by the merchant to display the member QR code.

"merchant_0121_000***"

registerDate

Datetime

Yes

Indicates the date and time of membership registration, which is defined by the merchant. The value follows the ISO 8601 standard format.

"2019-11-27T00:00:00+08:00"

expireDate

Datetime

No

Indicates the date and time when the membership expires, which is defined by the merchant. The value follows the ISO 8601 standard format.

"2019-11-27T00:00:00+08:00"

cardFields

Array<CardField>

Yes

Indicates the details of the membership card, for example, the membership level or balance.

Maximum size: 10 elements

[

{

"fieldCode": "POINT",

"fieldValue": "123"

},

{

"fieldCode": "BALANCE",

"fieldValue": {

"value": 100,

"currency": "SGD"

}

}

]

extendInfo

String

No

Indicates the extended information about this API.

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

-

Response parameters

Field

Data type

Required

Description

result

Result

Yes

Indicates the request result, such as status and error codes.

cardNo

String

Yes

Indicates the unique card number returned by Mini Program Platform to identify a membership card.

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

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:

resultStatus

Description 

S

The request to issue the membership card is successful.

The corresponding result.resultCode is SUCCESS and the result.resultMessage  is Success.

U

The status of the request to issue the membership card is unknown. 

The corresponding result.resultCode is UNKNOWN_EXCEPTION and the result.resultMessage is "An API calling is failed, which is caused by unknown reasons." For details, see the Common error codes section.

F

The request to issue the membership card 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: This API does not have its dedicated error codes.

Samples

The data flow of sending a request to issue a membership card is illustrated as follows:

issueCard

The above diagram consists of the following steps:

  1. The merchant calls this API to send a request to Mini Program Platform to issue a membership card.
  2. Mini Program Platform processes the request and issues the membership card.
  3. Mini Program Platform returns the result to the merchant.

Request

copy
{
    "requestId": "2019112987210000077771990****",
    "appId": "2102010113769***",
    "customerBelongsTo": "TNG",
    "customerId": "21091129***",
    "registerDate": "2022-02-17T00:00:00.00+08:00",
    "expireDate": "2023-01-26T00:00:00.00+08:00",
    "externalCardNo": "merchant_0121_000***",
    "externalCustomerId": "merchant_01***",
    "cardFields": [
        {
            "fieldCode": "POINT",
            "fieldValue": "123"
        },
        {
            "fieldCode": "BALANCE",
            "fieldValue": {
                "value": 100,
                "currency": "SGD"
            }
        },
        {
            "fieldCode": "LEVEL",
            "fieldValue": "GOLD"
        }
    ]
}

Response

copy
{
    "cardNo": "011164508621375700010170***",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success",
        "resultStatus": "S"
    }
}

result.resultStatus is S, which means the request to issue the membership card is successful.