notifyCardRegistration

POST /v2/pds/memberships/notifyCardRegistration

When a user registers as a new member in a mini program, Mini Program Platform calls this API to request the merchant to create a new membership card for the user.

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

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 notifyCardRegistration requests that are initiated with the same requestId value, the merchant must return the same result. For details about API idempotency, see the Idempotency chapter.

"011164508621375700010170***"

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

"1236450862137570***"

registrationFields

Array<CardField>

Yes

Indicates the information that the user fills in to register as a new member.

Maximum size: 10 elements

[

{

"fieldCode": "EMAIL",

"fieldValue": "email@example.com"

}

]

extendInfo

String

No

Indicates the extended information about this API. For example, if the user inputs the referral code, the Mini Program Platform can pass the referral code in JSON format via this parameter.

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

{

"referralCode":"12345"

}

Response parameters

Field

Data type

Required

Description

result

Result

Yes

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

extendInfo

String

No

Indicates the extended information about the response.

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

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 request for member card registration is successful.

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

U

The status of the request for member card registration 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 for member card registration 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: This API does not have its dedicated error codes.

Samples

The data flow of sending a request for membership card registration is illustrated as follows:

notifyCardRegistration

The above diagram consists of the following steps:

  1. Mini Program Platform calls this API to send user registration information to the merchant.
  2. The merchant processes the request and creates a new membership card.
  3. The merchant returns the result to Mini Program Platform.

Request

copy
{
    "appId": "2102010113769***",
    "customerBelongsTo": "TNG",
    "customerId": "1236450862137570***",
    "requestId": "011164508621375700010170***",
    "registrationFields": [
        {
            "fieldCode": "USER_NAME",
            "fieldValue": "John Doe"
        },
        {
            "fieldCode": "GENDER",
            "fieldValue": "M"
        },
        {
            "fieldCode": "BIRTH_DATE",
            "fieldValue": "2002-07-25"
        },
        {
            "fieldCode": "MOBILE_PHONE",
            "fieldValue": "+658812****"
        },
        {
            "fieldCode": "EMAIL",
            "fieldValue": "email@example.com"
        }
    ]
}

Response

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

result.resultStatus is S, which means the request for membership card registration is successful.