# Create a Global Account

> Create a Global Account for acquiring-side collection and payout scenarios.

```yaml
openapi: 3.1.0
info:
  title: Create a Global Account
  version: 1.0.0
  description: Create a Global Account for acquiring-side collection and payout scenarios.
paths:
  /api/v1/account/global/create:
    post:
      summary: Create a Global Account
      description: Create a Global Account for acquiring-side collection and payout
        scenarios.
      parameters:
        - name: apikey
          in: header
          required: true
          description: Account service API key request header assigned by Onerway. Use the
            value for the same environment as the request base URL.
          schema:
            type: string
            description: Account service API key request header assigned by Onerway. Use the
              value for the same environment as the request base URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                requestId:
                  type: string
                  description: Request ID used for idempotency control and request tracing.
                customerId:
                  type: string
                  description: 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.
                onBehalfOf:
                  type: string
                  description: 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.
                bankCountry:
                  type: string
                  description: Country or region code of the bank where the Global Account is
                    opened. Use the two-letter [ISO 3166-1
                    alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
                    format.
                supportCurrencies:
                  type: array
                  description: Supported currency entry for this Global Account. Use three-letter
                    [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                    currency codes.
                  items:
                    type: string
                webhookUrl:
                  type: string
                  description: Asynchronous notification URL for account-service events related to
                    the Global Account.
                  x-onerway-constraints:
                    - kind: rule
                      text: Must be a valid URL when provided.
                globalAccountName:
                  type: string
                  description: Display name of the Global Account, used for account information
                    display and merchant-side identification.
                  x-onerway-constraints:
                    - kind: rule
                      text: Use letters, numbers, spaces, Chinese characters, underscores, dots, or
                        hyphens.
              required:
                - requestId
                - customerId
                - bankCountry
                - supportCurrencies
                - globalAccountName
            examples:
              create-global-account:
                summary: Create a Global Account
                value:
                  requestId: REQ-GA-20260423-0001
                  customerId: "801172"
                  bankCountry: US
                  supportCurrencies:
                    - USD
                    - EUR
                  webhookUrl: https://merchant.example.com/hooks/account
                  globalAccountName: Acme USD Collection
      responses:
        "200":
          description: Global Account created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: 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.
                  respCode:
                    type: string
                    description: Business response code for Global Account APIs. The success
                      response code is `20000`.
                  respMsg:
                    type: string
                    description: Human-readable prompt or error message for the response code.
                  data:
                    type: object
                    properties:
                      globalAccountId:
                        type: string
                        description: Global Account ID generated by Onerway. Use it for subsequent
                          detail queries, status tracking, and reconciliation.
                      onBehalfOf:
                        type:
                          - string
                          - "null"
                        description: Child customer identifier echoed by Onerway.
                        x-onerway-value:
                          nullable: true
                          empty: true
                          when:
                            en: Returned when the request was made on behalf of a child customer.
                            zh: 代子客户调用时返回。
                    description: Created Global Account information.
                  error:
                    type:
                      - object
                      - "null"
                    properties:
                      type:
                        type: string
                        description: Standardized error type.
                      code:
                        type: string
                        description: External business error code, usually aligned with `respCode`.
                      message:
                        type: string
                        description: Human-readable error message.
                      param:
                        type:
                          - string
                          - "null"
                        description: Request field that caused the error.
                        x-onerway-value:
                          nullable: true
                          empty: true
                          when:
                            en: Returned when the error can be associated with a request field.
                            zh: 错误可关联到请求字段时返回。
                      requestId:
                        type:
                          - string
                          - "null"
                        description: Request ID used for troubleshooting.
                        x-onerway-value:
                          nullable: true
                          empty: true
                          when:
                            en: Returned when the request ID is available in the failure context.
                            zh: 失败上下文中可取得请求 ID 时返回。
                    description: Structured error details returned by the Account service.
                    x-onerway-value:
                      nullable: true
                      when:
                        en: Returned when the Global Account request fails.
                        zh: Global Account 请求失败时返回。
              examples:
                create-global-account:
                  summary: Global Account created
                  value:
                    success: true
                    respCode: "20000"
                    respMsg: Success
                    data:
                      globalAccountId: "2002"
```