Skip to main content
POST
/
webhook
/
institution
/
v1
/
accounts
/
callback
curl --request POST \
  --url https://openplatform.gateapi.io/webhook/institution/v1/accounts/callback \
  --header 'Content-Type: application/json' \
  --header 'X-GatePay-On-Behalf-Of: <x-gatepay-on-behalf-of>' \
  --data '
{
  "bizType": "INSTITUTION",
  "bizId": "35778162074976257",
  "bizStatus": "INSTITUTION_ACCOUNT_SUCCESS",
  "clientId": "ktBVqBBHrEHJmfZH",
  "data": "{\"request_id\":\"35778162074976257\",\"account_id\":\"2124543768\",\"customer_id\":\"1234\",\"display_name\":\"my test\",\"status\":\"ACTIVE\",\"created\":1764139242707}"
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.gate.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This page documents the POST /webhook/institution/v1/accounts/callback endpoint. The full schema, parameters, 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

​
Notification Fields

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)

​
Example

Full payload sent by GatePay: 
{
  "bizType": "INSTITUTION",
  "bizId": "35778162074976257",
  "bizStatus": "INSTITUTION_ACCOUNT_SUCCESS",
  "clientId": "ktBVqBBHrEHJmfZH",
  "data": "{\"request_id\":\"35778162074976257\",\"account_id\":\"2124543768\",\"customer_id\":\"1234\",\"display_name\":\"my test\",\"status\":\"ACTIVE\",\"created\":1764139242707}"
}
Parsed content of data: 
{
  "request_id": "35778162074976257",
  "account_id": "2124543768",
  "customer_id": "1234",
  "display_name": "my test",
  "status": "ACTIVE",
  "created": 1764139242707
}

Headers

​
X-GatePay-On-Behalf-Of
string
required

Required delegated subject header. Provide the initiating account ID for this transaction. It can be an institution account ID or a sub-account ID.

Body

application/json

Callback notification body for sub-account creation result

​
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

​
clientId
string

Merchant client_id that created the sub-account

​
data
string

Message content, JSON string; parsed structure see CreateSubAccountCallbackData

Response

200

Acknowledge receipt; merchant must return HTTP 200