Skip to main content
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

FieldTypeDescription
bizTypestringNotification type; INSTITUTION = sub-account creation
bizIdstringCreation request ID
bizStatusstringBusiness status: INSTITUTION_ACCOUNT_SUCCESS = created, INSTITUTION_ACCOUNT_FAIL = creation failed
client_idstringMerchant client_id that created the sub-account
datastringMessage content, JSON string; parsed structure is described in the table below

​
Parsed data Content

FieldTypeDescription
request_idstringCreation request ID
account_idstringSub-account ID
customer_idstringCustomer ID on the platform side
display_namestringDisplay name
statusstringAccount status: ACTIVE = created, FAIL = creation failed
createdint64Creation 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.