Global Account

Global Account API 用于创建和查询支持指定币种资金收付场景的账户信息。创建结果可用于后续账户信息展示、状态跟踪和对账流程。

接入准备

调用账户服务前，请先完成 账户服务接入准备。

创建 Global Account

创建 Global Account API 会根据请求中的客户、银行国家/地区和支持币种信息初始化账户。

POST

请求参数

Parameter	Type	Length	Required	Signed	Description
requestId	String	/	Yes	No	Unique request ID for idempotency and request tracing.
customerId	String	/	Yes	No	Customer identifier used for opening the Global Account.
customerType	String	/	No	No	Reserved customer type, for example PERSONAL or COMPANY.
bankCountry	String	/	Yes	No	Bank country or region code, for example US or GB.
supportCurrencies	String[]	/	Yes	No	Supported collection currency list, for example ["USD", "EUR"].
webhookUrl	String	200	No	No	Asynchronous notification URL. The value must be a valid URL and must not exceed 200 characters.
globalAccountName	String	/	Yes	No	Display name of the Global Account.

响应

Name	Type	Description
success	boolean	Business success flag.
respCode	String	Business response code.
respMsg	String	Response message or error reason.
data	Object	Created Global Account information.
└globalAccountId	String	Local Global Account primary ID.

API 使用示例

请求

{
  "requestId": "REQ-GA-20260423-0001",
  "customerId": "CUS-EXAMPLE-001",
  "bankCountry": "US",
  "supportCurrencies": ["USD", "EUR"],
  "webhookUrl": "https://merchant.example.com/hooks/account",
  "globalAccountName": "Acme USD Collection"
}

响应

{
  "success": true,
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "globalAccountId": "GAID-DEMO-0001"
  }
}

查询 Global Account 详情

查询 Global Account 详情 API 支持通过 globalAccountId 或 globalAccountNo 查询账户信息。

POST

查询条件

globalAccountId 与 globalAccountNo 至少传一个。

请求参数

Parameter	Type	Length	Required	Signed	Description
globalAccountId	String	/	Conditional	No	Global Account primary ID. Required when globalAccountNo is not provided.
globalAccountNo	String	/	Conditional	No	Global Account number. Required when globalAccountId is not provided.

响应

Name	Type	Description
success	boolean	Business success flag.
respCode	String	Business response code.
respMsg	String	Response message or error reason.
data	Object	Global Account details.
└globalAccountId	String	Primary ID.
└globalAccountNo	String	Global Account number.
└globalAccountInfoId	String	Institution-side account information ID.
└globalAccountName	String	Global Account display name.
└customerId	String	Customer identifier.
└customerName	String	Customer name.
└mainAccountNo	String	Associated main account number, if returned.
└mainAccountName	String	Associated main account name, if returned.
└iban	String	IBAN.
└bankCode	String	Bank code.
└swiftCode	String	SWIFT Code.
└bankAddress	String	Bank address.
└bankName	String	Bank name.
└bankCountry	String	Bank country or region.
└bizTypeList	String[]	Supported business type list.
└supportCurrency	String	Supported currencies, separated by commas.
└institution	String	Financial institution.
└webhookUrl	String	Notification URL.
└operatingEntity	String	Operating entity.
└status	String	Processing, Failed, Active, Suspended, or Closed.
└globalActiveTime	String	Activation time.
└addressCity	String	Bank city.
└addressPostalCode	String	Postal code.

API 使用示例

请求

{
  "globalAccountId": "GAID-DEMO-0001"
}

响应

{
  "success": true,
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "globalAccountId": "GAID-DEMO-0001",
    "globalAccountNo": "GA-DEMO-0001",
    "globalAccountName": "Acme USD Collection",
    "customerId": "CUS-EXAMPLE-001",
    "customerName": "Acme Ltd",
    "mainAccountNo": "MAIN-ACCOUNT-001",
    "mainAccountName": "Main Account",
    "iban": "GB29NWBK60161331926819",
    "bankCode": "NWBKGB2L",
    "swiftCode": "NWBKGB2LXXX",
    "bankAddress": "1 Example Street",
    "bankName": "Example Bank",
    "bankCountry": "GB",
    "bizTypeList": ["COBO", "POBO"],
    "supportCurrency": "USD,EUR",
    "institution": "Example Institution",
    "webhookUrl": "https://merchant.example.com/hooks/account",
    "operatingEntity": "Example Entity",
    "status": "Active",
    "globalActiveTime": "2026-04-23T06:31:18.266Z",
    "addressCity": "London",
    "addressPostalCode": "EC1A1BB"
  }
}

实施建议

1. 使用唯一 requestId 调用创建接口，避免重复初始化。
2. 保存 globalAccountId，并在查询详情、状态同步和后续对账中作为主要标识。
3. 使用 status 判断账户生命周期状态，在 Active 后再进入后续资金收付流程。