跳转到主要内容
WEBHOOK
institutionAccountNotify
{
  "bizType": "INSTITUTION",
  "bizId": "2060249001916727296",
  "bizStatus": "INSTITUTION_ACCOUNT_SUCCESS",
  "clientId": "caoLHPyfvjtnJPJe",
  "data": "{\"request_id\":\"2060249001916727296\",\"account_id\":\"53695180\",\"customer_id\":\"2060249001845424128\",\"display_name\":\"ABC\",\"status\":\"ACTIVE\",\"created\":1780036614339}"
}
{
  "returnCode": "SUCCESS",
  "returnMessage": null
}

​
概述

本页说明 webhook institutionAccountNotify。完整的参数、响应结构与示例由上方关联的 OpenAPI 定义渲染。 创建子账户成功或失败时，GatePay 会向商户在后台配置的回调地址发送通知。商户应在该地址接收并解析消息，并返回 HTTP 200 表示已成功接收。

​
说明

  • 建议基于 bizId 或 data.request_id 做幂等处理。
  • 验签、重试、data 解析与成功应答见 通知概览；签名规则见 安全与签名。

​
触发情形

  • 创建子账户申请处理完成（成功或失败）时，GatePay 向商户配置的 callback URL 发送通知
  • 若通知投递失败，重试规则见 通知概览

​
消息结构

字段名类型说明
bizTypestring描述通知类别， INSTITUTION-创建子账户
bizIdstring创建申请单号
bizStatusstring业务状态 INSTITUTION_ACCOUNT_SUCCESS-创建成功 INSTITUTION_ACCOUNT_FAIL-创建失败
client_idstring创建子账户的商户client_id
datastring消息内容 JSON 字符串

​
data 解析后内容

字段名类型说明
request_idstring创建申请单号
account_idstring子账户 ID
customer_idstring平台侧客户 ID
display_namestring展示名
statusstring账户状态 已创建-ACTIVE 创建失败-FAIL
createdint64创建时间（毫秒）

​
回调示例

创建子账户成功通知： 
{
  "bizType": "INSTITUTION",
  "bizId": "2060249001916727296",
  "bizStatus": "INSTITUTION_ACCOUNT_SUCCESS",
  "clientId": "caoLHPyfvjtnJPJe",
  "data": "{\"request_id\":\"2060249001916727296\",\"account_id\":\"53695180\",\"customer_id\":\"2060249001845424128\",\"display_name\":\"ABC\",\"status\":\"ACTIVE\",\"created\":1780036614339}"
}
data 解析后内容： 
{
  "request_id": "2060249001916727296",
  "account_id": "53695180",
  "customer_id": "2060249001845424128",
  "display_name": "ABC",
  "status": "ACTIVE",
  "created": 1780036614339
}

​
创建子账户失败通知

{
  "bizType": "INSTITUTION",
  "bizId": "2060249001916727297",
  "bizStatus": "INSTITUTION_ACCOUNT_FAIL",
  "clientId": "caoLHPyfvjtnJPJe",
  "data": "{\"request_id\":\"2060249001916727297\",\"account_id\":\"\",\"customer_id\":\"2060249001845424128\",\"display_name\":\"ABC\",\"status\":\"FAIL\",\"created\":1780036614339}"
}

请求体

application/json

创建子账户结果回调通知体

​
bizType
string
必填

描述通知类别，INSTITUTION-创建子账户

​
bizId
string
必填

创建申请单号

​
bizStatus
string
必填

业务状态 INSTITUTION_ACCOUNT_SUCCESS-创建成功 INSTITUTION_ACCOUNT_FAIL-创建失败

​
clientId
string
必填

创建子账户的商户 client_id

​
data
string
必填

消息内容 JSON 字符串，解析后参见 CreateSubAccountCallbackData。

响应

200 - application/json

返回 HTTP 200 表示商户已成功接收回调。

商户接收回调后的返回结果。

​
returnCode
string
必填

返回状态码，例如 SUCCESS。

​
returnMessage
string | null

返回消息。