Onerway
POST

Create a Global Account

View as Markdown
Use this endpoint to initialize a Global Account for a customer, including the bank country or region and supported collection currencies.

Request

apikeystringrequired
Account service API key request header assigned by Onerway. Use the value for the same environment as the request base URL.
Example:replace_with_account_service_apikey
requestIdstringrequired
Request ID used for idempotency control and request tracing.
Example:REQ-GA-20260423-0001
customerIdstringrequired
Customer identifier for which the Global Account is opened. For direct merchant calls, use the customer identifier associated with the apikey. For platform calls, use the child customer identifier that the caller is authorized to operate.
Example:801172
onBehalfOfstringoptional
Child customer identifier when a platform merchant calls on behalf of a child customer. When provided, it must match customerId and the caller must be authorized for that customer.
Example:456
bankCountrystringrequired
Country or region code of the bank where the Global Account is opened. Use the two-letter ISO 3166-1 alpha-2 format.
Example:US
supportCurrenciesarray<string>required
Supported currency entry for this Global Account. Use three-letter ISO 4217 currency codes.
Example:["USD","EUR"]
webhookUrlstringoptional
Asynchronous notification URL for account-service events related to the Global Account.
Example:https://developers.onerway.com/example-account-webhook
Constraints
Rule
Must be a valid URL when provided.
globalAccountNamestringrequired
Display name of the Global Account, used for account information display and merchant-side identification.
Example:Acme USD Collection
Constraints
Rule
Use letters, numbers, spaces, Chinese characters, underscores, dots, or hyphens.

Request example

curl -X POST 'https://sandbox-api.onerway.com/account-server/api/v1/account/global/create' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "requestId": "REQ-GA-20260423-0001",
  "customerId": "801172",
  "bankCountry": "US",
  "supportCurrencies": [
    "USD",
    "EUR"
  ],
  "webhookUrl": "https://merchant.example.com/hooks/account",
  "globalAccountName": "Acme USD Collection"
}'

Response

successboolean
Whether the Global Account creation request was processed successfully. When this value is false, read respCode and respMsg for the failure reason and do not rely on data as a created account result.
respCodestring
Business response code for Global Account APIs. The success response code is 20000.
respMsgstring
Human-readable prompt or error message for the response code.
Created Global Account information.
Structured error details returned by the Account service.

Response example

{
  "success": true,
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "globalAccountId": "2002"
  }
}
No error responses are documented for this endpoint.

Setup

Configure the Account service base URL, apikey, x-timestamp, and outbound IP allowlist before calling account balance, account transaction, account statement, and Global Account APIs.

Get Global Account details

Retrieve Global Account details by Global Account ID or account number.