inquireCardDetail

POST /v2/pds/memberships/inquireCardDetail

With this API call, Mini Program Platform can request the merchant to query the details of 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

cardNo

String 

No

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 @ # ?

"011164508621375700010170***"

appId

String

Yes

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

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

"2102010113769***"

loginIdentity

LoginIdentity

No

Indicates the login identity of the user.

-

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.

cardFields

Array<CardField>

No

Indicates the personal user information and membership card details. Specify this parameter if the membership card exists.

Maximum size: 10 elements

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 query card details is successful.

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

U

The status of the request to query card details 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 query card details is 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.

Sample

The data flow of sending a request to query card details is illustrated as follows:

inquireCardDetail

The above diagram consists of the following steps:

  1. Mini Program Platform calls this API to send a request to the merchant to query card details.
  2. The merchant server processes the request and queries the card information.
  3. The merchant returns the card information to Mini Program Platform.

Request

Query card details based on cardNo

copy
{
    "cardNo": "011164508621375700010170***"
}

Query isMerchantMember based on loginIdentity

copy
{
  "appId": "xxx",
  "loginIdentity": {
    "identityType": "MOBILE_PHONE",
    "identityNo": "xxxxx"
  }
}

Response

Query card details based on cardNo

copy
{
  "cardFields": [
    {
      "fieldCode": "POINT",
      "fieldValue": "123"
    },
    {
      "fieldCode": "BALANCE",
      "fieldValue": {
        "currency": "SGD",
        "value": 100
      }
    },
    {
      "fieldCode": "LEVEL",
      "fieldValue": "GOLD"
    },
    {
      "fieldCode": "FIRST_NAME",
      "fieldValue": "John"
    },
    {
      "fieldCode": "LAST_NAME",
      "fieldValue": "Doe"
    },
    {
      "fieldCode": "GENDER",
      "fieldValue": "M"
    },
    {
      "fieldCode": "BIRTH_DATE",
      "fieldValue": "2002-07-25"
    },
    {
      "fieldCode": "MOBILE_PHONE",
      "fieldValue": "+658812****"
    },
    {
      "fieldCode": "EMAIL",
      "fieldValue": "email@example.com"
    }
  ],
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  }
}

Query isMerchantMember based on loginIdentity

copy
{
  "cardFields": [
    {
      "fieldCode": "MOBILE_PHONE",
      "fieldValue": "+1234567890"
    }
  ],
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  }
}

the response sample above, the value of result.resultStatus is S, which means the request to inquire about the card details is successful.