AlipayHKAlipayHKDOCS

4. 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

2023042122001432271433274247

circleStore

BusinessDistrictCircleStoreVO

O

Information needed to tage a merchant

"circleStore": {

"merchantPms": {

"partnerId": "20230324",

"merchantId": "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": "20230324",

"merchantId": "20230324",

"merchantName": "Test Merchant",

"storeId": "20230324",

"storeName": "Test Store"

},

businessDistrictSubject

BusinessDistrictSubjectVOString

M

Mall Information

The IDs assigned by AlipayHK to distinguish different groups

"businessDistrictSubject": {

"mallGroupLabel": "20230316",

"mallLabel": "20230316001"

}

MerchantPmsVO

Field

Type

Length

Required

Remarks

Sample

partnerId

java.lang.String

O

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

2088021966641234

merchantId

java.lang.String

O

The secondary merchant IDs assigned by partners to each merchant

SECM0001

merchantName

java.lang.String

O

Merchant Name

Test Merchant

storeId

java.lang.String

O

The store IDs assigned by partners to each stores

STORE0001

storeName

java.lang.String

O

Store Name

Test Store

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

copy
{
  "saveWayType": "MERCHANT_PMS",
  "ipayTradeNo": "",
  "circleStore": {
    "merchantPms": {
      "partnerId": "20230324",
      "merchantId": "20230324",
      "merchantName": "Test Merchant",
      "storeId": "20230324",
      "storeName": "Test Store"
    },
    "businessDistrictSubject": {
      "mallGroupLabel": "20230316",
      "mallLabel": "20230316001"
    }
  }
}
copy
{
  "saveWayType": "IPAY_TRADE_NO",
  "ipayTradeNo": "2022082939007101030400063632",
  "circleStore": {
    "merchantPms": {
      "partnerId": "",
      "merchantId": "",
      "merchantName": "",
      "storeId": "",
      "storeName": ""
    },
    "businessDistrictSubject": {
      "mallGroupLabel": "20230316",
      "mallLabel": "20230316"
    }
  }
}

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.