Sub-account Creation Result Notification

{
  "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

institutionAccountWebhook

{
  "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
}

Overview

This page documents webhook institutionAccountWebhook. Parameters, response schema, and examples are rendered from the linked OpenAPI definition above. When sub-account creation succeeds or fails, GatePay sends a POST request to the callback URL configured by the merchant. The merchant should receive and parse the notification at that URL and return HTTP 200 to acknowledge receipt.

Notes

Use bizId or data.request_id for idempotency after parsing data.
Signature verification, retries, parsing data, and the success response are covered in Notifications Overview; see Security and Signature for signing rules.

Trigger scenarios

When sub-account creation completes (success or failure), GatePay sends a notification to your callback URL
If delivery fails, see retry rules in Notifications Overview

Message Structure

Field	Type	Description
`bizType`	string	Notification type; INSTITUTION = sub-account creation
`bizId`	string	Creation request ID
`bizStatus`	string	Business status: INSTITUTION_ACCOUNT_SUCCESS = created, INSTITUTION_ACCOUNT_FAIL = creation failed
`client_id`	string	Merchant client_id that created the sub-account
`data`	string	Message content, JSON string; parsed structure is described in the table below

Parsed `data` Content

Field	Type	Description
`request_id`	string	Creation request ID
`account_id`	string	Sub-account ID
`customer_id`	string	Customer ID on the platform side
`display_name`	string	Display name
`status`	string	Account status: ACTIVE = created, FAIL = creation failed
`created`	int64	Creation time (milliseconds)

Callback examples

Full payload sent by GatePay:

{
  "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}"
}

Parsed content of data:

{
  "request_id": "2060249001916727296",
  "account_id": "53695180",
  "customer_id": "2060249001845424128",
  "display_name": "ABC",
  "status": "ACTIVE",
  "created": 1780036614339
}

Sub-account creation failed

{
  "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}"
}

Body

application/json

Callback notification body for sub-account creation result

bizType

string

required

Notification type; INSTITUTION = sub-account creation

bizId

string

required

Creation request ID

bizStatus

string

required

Business status: INSTITUTION_ACCOUNT_SUCCESS = created, INSTITUTION_ACCOUNT_FAIL = creation failed

clientId

string

required

Merchant client_id that created the sub-account

data

string

required

Message body as a JSON string; parsed structure see CreateSubAccountCallbackData.

Response

200 - application/json

Return HTTP 200 to indicate the callback notification has been received.

Merchant acknowledgement returned after receiving the callback.

returnCode

string

required

Return status code, for example SUCCESS.

returnMessage

string | null

Return message.

⌘I

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

Sub-account Creation Result Notification

Overview

Notes

Trigger scenarios

Message Structure

Parsed `data` Content

Callback examples

Sub-account creation failed

Body

Response

​Overview

​Notes

​Trigger scenarios

​Message Structure

​Parsed data Content

​Callback examples

​Sub-account creation failed

Body

Response

Overview

Notes

Trigger scenarios

Message Structure

Parsed `data` Content

Callback examples

Sub-account creation failed