Global Account

The Global Account APIs create and retrieve account information for supported multi-currency pay-in and payout scenarios. The returned account information can be used for display, status tracking, and reconciliation.

Setup

Before calling account services, complete Account Service Setup.

Create Global Account

The Create Global Account API initializes a Global Account using the customer, bank country or region, and supported currency information in the request.

POST

Request Parameters

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.

Response

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 Example

Request

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

Response

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

Get Global Account Detail

The Get Global Account Detail API retrieves account information by globalAccountId or globalAccountNo.

POST

Query Condition

Provide at least one of globalAccountId or globalAccountNo.

Request Parameters

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.

Response

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 Example

Request

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

Response

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

Best Practices

1. Use a unique requestId when creating a Global Account to avoid duplicate initialization.
2. Store globalAccountId and use it as the primary identifier for detail queries, status synchronization, and reconciliation.
3. Check status before subsequent pay-in or payout flows. Continue only after the account is Active.