AlipayHKAlipayHKDOCS

5. Collect PMS Information

API Path

/api/open/alipayhk/businessdistrict/circleStore/save

Sample: https://open.alipay.hk/api/open/alipayhk/businessdistrict/circleStore/save

API Request

Request

Header

Name

Description

Type

Length

Required

Remarks

Sample

client-id

Client ID

String

M

211020000000000000044

signature

Message signature information

String

M

algorithm=sha256withrsa,keyVersion=2,signature=xxxxxxxxxxxyyyyyyyyyyyyyyzzzzzzzzz==

encrypt

Message encryption information

String

O

algorithm=rsa, keyVersion=2

Content-type

HTTP content type

String

M

application/json; charset=UTF-8

Body

Field

Type

Length

Required

Remarks

Sample

saveWayType

saveWayType

M

AlipayHK provides below two options for PMS information collection

  • MERCHANT_PMS
  • IPAY_TRADE_NO
  • MERCHANT_PMS
  • IPAY_TRADE_NO

ipayTradeNo

String

O

Transaction No. created by AlipayHK

Required if saveWayType=IPAY_TRADE_NO

2023042122001432271433274247

circleStore

BusinessDistrictCircleStoreVO

O

Information needed to tage a merchant

"circleStore": {

"merchantPms": {

"partnerId": "20230324",

"merchantAccountId": "20230324",

"merchantName": "Test Merchant",

"storeId": "20230324",

"storeName": "Test Store"

},

"businessDistrictSubject": {

"mallGroupLabel": "20230316",

"mallLabel": "20230316001"

}

}

BusinessDistrictCircleStoreVO

Field

Type

Length

Required

Remarks

Sample

merchantPms

MerchantPmsVO

O

PMS Information

If the merchant accept the AlipayHK as a payment method, it must has PMS information associated

    "merchantPms": {

      "partnerId": "2088021966641234",

      "merchantAccountId": "SECM0001",

      "merchantName": "Nike",

      "storeId": "STORE0001",

      "storeName": "Nike Times Square",

      "mallName": "Times Square",

      "storeNo": "B1-001"

    }

businessDistrictSubject

BusinessDistrictSubjectVOString

M

Mall Information

The IDs assigned by AlipayHK to distinguish different groups

"businessDistrictSubject": {

"mallGroupLabel": "20230316",

"mallLabel": "20230316001"

}

actionType

String

M

Action type:

• in — register (default)

• out — remove (out-circle)

subjectType

String

O

Subject type, used only for request validation, not persisted:

• mall — mall subject

• subject — points subject

subject

subjectIdString64

O

Points subject ID. Required when subjectType=subject.2160120146500000
autoEarnPointsBoolean

O

Whether to enable auto-earn-points, used only for routing, not persisted:
• true 
• false(default)

true

pmsLabel

String

128

PMS label. Required when actionType=out, used to locate the record to remove.

2023041219161407000009000012056

MerchantPmsVO

Field

Type

Length

Required

Remarks

Sample

partnerId

java.lang.String

O

The IDs assigned by AlipayHK to each payment partner or KA merchant

  • Required when subjectType=MERCHANT_PMS.

2088021966641234

merchantAccountId

java.lang.String

O

The secondary merchant IDs assigned by partners to each merchant

  • Required when subjectType=MERCHANT_PMS.

SECM0001

merchantName

java.lang.String

O

Merchant Name

Test Merchant

storeId

java.lang.String

O

The store IDs assigned by partners to each stores

  • Required when subjectType=MERCHANT_PMS.

STORE0001

storeName

java.lang.String

O

Store Name

Test Store

mallName

java.lang.String

O

Mall name

storeNo

java.lang.String

O

Store number in the mall

BusinessDistrictSubjectVO

Field

Type

Length

Required

Remarks

Sample

mallGroupLabel

java.lang.String

M

The IDs assigned by AlipayHK to each group

20230316

mallLabel

java.lang.String

M

The IDs assigned by AlipayHK to each mall

20230316

Response

Header

Name

Description

Type

Length

Required

Remarks

Sample

client-id

Client ID

String

M

211020000000000000044

signature

Message signature information

String

M

algorithm=sha256withrsa,keyVersion=2,signature=xxxxxxxxxxxyyyyyyyyyyyyyyzzzzzzzzz==

encrypt

Message encryption information

String

O

algorithm=rsa, keyVersion=2

Content-type

HTTP content type

String

M

application/json; charset=UTF-8

Body

Field

Type

Length

Required

Remarks

Sample

result

Result|2.0

M

Response result

pmsLabel

String

M

The unique IDs assigned by AlipayHK to identify each PMS combination

2023041219161407000009000012056

Result

Field

Type

Length

Required

Description

Sample

resultCode

java.lang.String

M

Result code

SUCCESS

resultStatus

java.lang.String

M

Result status

F - failed S- success

resultMessage

java.lang.String

M

Result message

success

3. Request Example

Request

Register via PMS to subject (Auto earn points)

copy
{
  "saveWayType": "MERCHANT_PMS",
  "ipayTradeNo": "",
  "circleStore": {
    "actionType": "in",
    "subjectType": "subject",
    "subjectId": "2160120146507940",
    "autoEarnPoints": true,
    "merchantPms": {
      "partnerId": "2088021966641234",
      "merchantAccountId": "SECM0001",
      "merchantName": "Nike",
      "storeId": "STORE0001",
      "storeName": "Nike Times Square",
      "mallName": "Times Square",
      "storeNo": "B1-001"
    }
  }
}

Register via PMS to Mall

copy
{
  "saveWayType": "MERCHANT_PMS",
  "ipayTradeNo": "",
  "circleStore": {
    "actionType": "in",
    "subjectType": "mall",
    "autoEarnPoints": false,
    "merchantPms": {
      "partnerId": "2088021966641234",
      "merchantAccountId": "SECM0001",
      "merchantName": "Test Merchant",
      "storeId": "STORE0001",
      "storeName": "Test Store",
      "mallName": "Times Square",
      "storeNo": "B1-001"
    },
    "businessDistrictSubject": {
      "mallGroupLabel": "20230316",
      "mallLabel": "20230316001"
    }
  }
}

Register via transaction number

copy
{
  "saveWayType": "IPAY_TRADE_NO",
  "ipayTradeNo": "2022082939007101030400063632",
  "circleStore": {
    "actionType": "in",
    "subjectType": "mall",
    "autoEarnPoints": false,
    "merchantPms": {
      "merchantName": "",
      "storeName": ""
    },
    "businessDistrictSubject": {
      "mallGroupLabel": "20230316",
      "mallLabel": "20230316"
    }
  }
}

Removal via PMS from Brand

copy
{
  "saveWayType": "MERCHANT_PMS",
  "circleStore": {
    "actionType": "out",
    "subjectType": "subject",
    "subjectId": "2160120146507940",
    "pmsLabel": "2023041219161407000009000012056"
  }
}

Removal via PMS from mall

copy
{
  "saveWayType": "MERCHANT_PMS",
  "circleStore": {
    "actionType": "out",
    "subjectType": "mall",
    "businessDistrictSubject": {
      "mallGroupLabel": "20230316",
      "mallLabel": "20230316001"
    },
    "pmsLabel": "2023041219161407000009000012056"
  }
}

Response

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  },
  "pmsLabel":"2023041219161407000009000012056"
}

Result Code

Result Code

Result Message

SUCCESS

success

IPAY_TRADE_NO_NOT_EXIST

The ipay order number does not exist

BUSINESS_DISTRICT_NOT_EXIST

The business district does not exist

CIRCLE_STORE_FAILURE

circle store failure

STORE_IS_CIRCLED

The store has been circled

PARAM_ILLEGAL

Illegal parameters. For example, non-numeric input, invalid date.

UNKNOWN_CIRCLE_STORE_WAY_TYPE

Unknown circle store mode

UNKNOWN_EXCEPTION

API failed due to unknown reason.