8. Create&Update Template

2026-06-07 16:39

POST POST /api/open/v1/alipayhk/merchant/template/sync

Merchants can use this API to synchronize the display template of the bill account binding page to AlipayHK. The template can define account binding forms and one-time payment forms that are rendered in the AlipayHK Bills & Utilities experience.

Request

Header

Name	Type	Required	Max Length	Description	Sample
version	String	Y	8	API version	1.0.0
function	String	Y	128	API interface	alipay.intl.merchant.account.bind.template.manage
clientId	String	Y	8	Client ID	2110200000000044
reqTime	String	Y	-	Request time	2001-07-04T12:08:56+05:30
reqMsgId	String	Y	64	Request message ID	fj398457jd8iue98d8w7w93j
reserve	String	N	256	Reserved for future implementation	{}

Body

Name	Type	Required	Description	Sample
operationType	String	Y	Operation type. Supported values: `CREATE`, `UPDATE`.	CREATE
outTemplateId	String	Y	Merchant-side template ID. `clientId + outTemplateId` is used as the idempotency key.	20250815xxxxxxxx
status	String	C	Template status. Required when `operationType` is `UPDATE`. Supported values: `VALID`, `INVALID`.	VALID
merchantName	Object	Y	Merchant display name in multiple languages.	`{"en_US":"SmarTone","zh_HK":"數碼通","zh-CN":"数码通"}`
icon	String	Y	Merchant icon URL.	https://example.com/icon.png
supportAutoDebit	Boolean	Y	Indicates whether the template supports auto-debit.	true
notice	Object	N	Notice text shown at the bottom of the page, in multiple languages.	`{"en_US":"Tips: xxxx","zh_HK":"提示：xxxx","zh-CN":"提示：xxxx"}`
sections	String	Y	Template section definition. This field must be provided as a JSON string.	See the `Section` definition and examples below.
extendInfo	String	N	Extended information in JSON string format.	`{"key":"value"}`

Notes:

C means conditional.
To update template content, send the full latest template payload with operationType=UPDATE.
To deactivate a template, send operationType=UPDATE with status=INVALID.

Section

Name	Type	Required	Description	Sample
sectionCode	String	Y	Section code. Supported values: `BIND`, `SINGLE_PAYMENT`.	BIND
menuLayout	String	Y	Selector layout of the form menu. Supported values: `PICKER` `RADIO` `NONE`	PICKER
menuTitle	Object	Y	Title shown above the form selector, in multiple languages.	`{"en_US":"Type","zh_HK":"類型","zh-CN":"类型"}`
forms	Array\	Y	Form definitions under the section.	See `Form`.

Form

Name	Type	Required	Description	Sample
formCode	String	Y	Merchant-defined form code.	aaa
formName	Object	Y	Form display name in multiple languages.	`{"en_US":"Residential customers","zh_HK":"住宅客戶","zh-CN":"住宅客户"}`
merchantId	String	Y	Merchant ID associated with the form.	2160400000002012
subMerchantId	String	N	Sub-merchant ID associated with the form.	12345
billType	String	Y	Bill type.	TELECOM
subBillType	String	Y	Bill sub-type.	MOBILE_SERVICE
fields	Array\	Y	Input field definitions under the form.	See `Field`.

Field

Name	Type	Required	Description	Sample
fieldCode	String	Y	Merchant-defined field code.	billNo
displayName	Object	Y	Field display name in multiple languages.	`{"en_US":"Bill Number","zh_HK":"賬單號碼","zh-CN":"账单号码"}`
format	String	Y	Field format. Supported values: `NUMBER`, `STRING`, `PICKER`, `DATE`, `OTP`.	NUMBER
pickerList	Array\	C	Option list for `PICKER` fields only.	See `Picker`.
validateRule	String	N	Validation rule. For `NUMBER`, use `min,max`. For `STRING`, use a regular expression.	`1,100`

Picker

Name	Description	Type	Required	Sample
name	Option display name in multiple languages.	Object	Y	`{"en_US":"Bill Number","zh_HK":"賬單號碼","zh-CN":"账单号码"}`
code	Option code.	String	Y	BJ

Localized Text

Use a JSON object to provide multilingual text. The following structure is recommended:

copy
{
  "en_US": "Sample English Text",
  "zh_HK": "示例繁體文本",
  "zh-CN": "示例简体文本"
}

OTP Field Behavior

When format is OTP, AlipayHK performs the verification step before the form is submitted. For example, if fieldCode is phoneNo, the value returned later in the binding or single payment submission payload is already verified by AlipayHK.

Sections Format

The sections field must be sent as a JSON string. The unescaped structure is as follows:

copy
[
  {
    "sectionCode": "BIND",
    "menuLayout": "PICKER",
    "menuTitle": {
      "en_US": "Bill Type",
      "zh_HK": "帳單類型",
      "zh-CN": "账单类型"
    },
    "forms": [
      {
        "formCode": "aaa",
        "formName": {
          "en_US": "Home Customer",
          "zh_HK": "住宅客戶",
          "zh-CN": "住宅客户"
        },
        "merchantId": "2160400000002012",
        "subMerchantId": "12345",
        "billType": "TELECOM",
        "subBillType": "MOBILE_SERVICE",
        "fields": [
          {
            "fieldCode": "billNo",
            "displayName": {
              "en_US": "Bill Number",
              "zh_HK": "賬單號碼",
              "zh-CN": "账单号码"
            },
            "format": "NUMBER",
            "validateRule": "1,100"
          },
          {
            "fieldCode": "name",
            "displayName": {
              "en_US": "Registered Customer Name",
              "zh_HK": "註冊客戶姓名",
              "zh-CN": "注册客户姓名"
            },
            "format": "STRING",
            "validateRule": "^[A-Za-z ]{1,100}$"
          }
        ]
      },
      {
        "formCode": "bbb",
        "formName": {
          "en_US": "IDDD1666 Customer",
          "zh_HK": "IDDD1666客戶",
          "zh-CN": "IDDD1666客户"
        },
        "merchantId": "2160400000002014",
        "subMerchantId": "67890",
        "billType": "TELECOM",
        "subBillType": "MOBILE_SERVICE",
        "fields": [
          {
            "fieldCode": "billNo",
            "displayName": {
              "en_US": "Bill Number",
              "zh_HK": "賬單號碼",
              "zh-CN": "账单号码"
            },
            "format": "NUMBER",
            "validateRule": "1,100"
          },
          {
            "fieldCode": "name",
            "displayName": {
              "en_US": "Registered Customer Name",
              "zh_HK": "註冊客戶姓名",
              "zh-CN": "注册客户姓名"
            },
            "format": "STRING",
            "validateRule": "^[A-Za-z ]{1,100}$"
          }
        ]
      }
    ]
  }
]

Response

Header

Name	Description	Type	Required	Max Length	Sample
version	API version	String	M	8	1.0.0
function	API interface	String	M	128	alipay.intl.merchant.account.bind.template.manage
clientId	Client ID	String	M	8	2110200000000044
respTime	Response time	String	M	-	2001-07-04T12:08:56+05:30
reqMsgId	Request message ID	String	M	64	fj398457jd8iue98d8w7w93j
reserve	Reserved for future implementation	String	O	256	{}

Body

Name	Description	Type	Required	Sample
result	Result object.	Object	M	See `Result`.
status	Current template status. Supported values: `VALID`, `INVALID`.	String	M	VALID

Result

Name	Description	Type	Sample
resultCode	Result code.	String	SUCCESS
resultStatus	Result status. `S` for success, `F` for failure.	String	S
resultMessage	Result description.	String	success

Example

Request

Create template

copy
{
  "operationType": "CREATE",
  "outTemplateId": "20250815xxxxxxxx",
  "merchantName": {
    "en_US": "SmarTone",
    "zh_HK": "數碼通",
    "zh-CN": "数码通"
  },
  "icon": "https://example.com/icon.png",
  "supportAutoDebit": true,
  "notice": {
    "en_US": "Tips: Link your bill to receive bill reminders and make payment more easily.",
    "zh_HK": "提示：連結賬單後可接收繳費提醒，繳費更方便。",
    "zh-CN": "提示：绑定账单后可接收缴费提醒，缴费更方便。"
  },
  "sections": "[{\"sectionCode\":\"BIND\",\"menuLayout\":\"PICKER\",\"menuTitle\":{\"en_US\":\"Bill Type\",\"zh_HK\":\"帳單類型\",\"zh-CN\":\"账单类型\"},\"forms\":[{\"formCode\":\"aaa\",\"formName\":{\"en_US\":\"Home Customer\",\"zh_HK\":\"住宅客戶\",\"zh-CN\":\"住宅客户\"},\"merchantId\":\"2160400000002012\",\"subMerchantId\":\"12345\",\"billType\":\"TELECOM\",\"subBillType\":\"MOBILE_SERVICE\",\"fields\":[{\"fieldCode\":\"billNo\",\"displayName\":{\"en_US\":\"Bill Number\",\"zh_HK\":\"賬單號碼\",\"zh-CN\":\"账单号码\"},\"format\":\"NUMBER\",\"validateRule\":\"1,100\"},{\"fieldCode\":\"name\",\"displayName\":{\"en_US\":\"Registered Customer Name\",\"zh_HK\":\"註冊客戶姓名\",\"zh-CN\":\"注册客户姓名\"},\"format\":\"STRING\",\"validateRule\":\"^[A-Za-z ]{1,100}$\"}]}]}]"
}

Update template

When updating the template content, submit the full latest template payload.

copy
{
  "operationType": "UPDATE",
  "outTemplateId": "20250818xxxxxxxx",
  "status": "VALID",
  "merchantName": {
    "en_US": "SmarTone",
    "zh_HK": "數碼通",
    "zh-CN": "数码通"
  },
  "icon": "https://example.com/icon.png",
  "supportAutoDebit": true,
  "sections": "[{\"sectionCode\":\"BIND\",\"menuLayout\":\"PICKER\",\"menuTitle\":{\"en_US\":\"Bill Type\",\"zh_HK\":\"帳單類型\",\"zh-CN\":\"账单类型\"},\"forms\":[{\"formCode\":\"aaa\",\"formName\":{\"en_US\":\"Home Customer\",\"zh_HK\":\"住宅客戶\",\"zh-CN\":\"住宅客户\"},\"merchantId\":\"2160400000002012\",\"subMerchantId\":\"12345\",\"billType\":\"TELECOM\",\"subBillType\":\"MOBILE_SERVICE\",\"fields\":[{\"fieldCode\":\"billNo\",\"displayName\":{\"en_US\":\"Bill Number\",\"zh_HK\":\"賬單號碼\",\"zh-CN\":\"账单号码\"},\"format\":\"NUMBER\",\"validateRule\":\"1,100\"},{\"fieldCode\":\"name\",\"displayName\":{\"en_US\":\"Registered Customer Name\",\"zh_HK\":\"註冊客戶姓名\",\"zh-CN\":\"注册客户姓名\"},\"format\":\"STRING\",\"validateRule\":\"^[A-Za-z ]{1,100}$\"}]}]}]"
}

Deactivate template

copy
{
  "operationType": "UPDATE",
  "outTemplateId": "20250818xxxxxxxx",
  "status": "INVALID"
}

Response

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "status": "VALID"
}