# 创建 Global Account

> 创建用于收单收款与资金转出场景的 Global Account（全球收付账户）。

```yaml
openapi: 3.1.0
info:
  title: 创建 Global Account
  version: 1.0.0
  description: 创建用于收单收款与资金转出场景的 Global Account（全球收付账户）。
paths:
  /api/v1/account/global/create:
    post:
      summary: 创建 Global Account
      description: 创建用于收单收款与资金转出场景的 Global Account（全球收付账户）。
      parameters:
        - name: apikey
          in: header
          required: true
          description: Onerway 分配的账户服务 API key 请求 Header；必须使用与请求域名相同环境的值。
          schema:
            type: string
            description: Onerway 分配的账户服务 API key 请求 Header；必须使用与请求域名相同环境的值。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                requestId:
                  type: string
                  description: 请求 ID，用于幂等控制和链路追踪。
                customerId:
                  type: string
                  description: 开通 Global Account 的客户标识。商户直接调用时，传入与 `apikey`
                    关联的客户标识；平台代子客户调用时，传入调用方有权限操作的子客户标识。
                onBehalfOf:
                  type: string
                  description: 平台商户代子客户调用时传入的子客户标识。如传入，必须与 `customerId` 一致，且调用方必须具备该子客户的操作权限。
                bankCountry:
                  type: string
                  description: Global Account 开户银行所在国家或地区代码，使用 [ISO 3166-1
                    alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
                    两位字母代码。
                supportCurrencies:
                  type: array
                  description: 该 Global Account 支持的币种列表项，使用 [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                    三位字母货币代码。
                  items:
                    type: string
                webhookUrl:
                  type: string
                  description: 账户服务异步通知 URL，用于接收 Global Account 相关状态通知。
                  x-onerway-constraints:
                    - kind: rule
                      text: 如传入，必须是合法 URL。
                globalAccountName:
                  type: string
                  description: Global Account 展示名称，用于账户信息展示和商户侧识别。
                  x-onerway-constraints:
                    - kind: rule
                      text: 可使用字母、数字、空格、中文、下划线、点号或连字符。
              required:
                - requestId
                - customerId
                - bankCountry
                - supportCurrencies
                - globalAccountName
            examples:
              create-global-account:
                summary: 创建 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 已创建
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Global Account 创建请求是否处理成功。当该值为 `false` 时，请读取 `respCode` 与 `respMsg`
                      判断失败原因，不要将 `data` 作为已创建账户结果使用。
                  respCode:
                    type: string
                    description: Global Account API 业务响应码；成功响应码为 `20000`。
                  respMsg:
                    type: string
                    description: 响应码对应的提示或错误说明。
                  data:
                    type: object
                    properties:
                      globalAccountId:
                        type: string
                        description: Onerway 生成的 Global Account ID，用于后续查询详情、状态跟踪和对账。
                      onBehalfOf:
                        type:
                          - string
                          - "null"
                        description: Onerway 回显的子客户标识。
                        x-onerway-value:
                          nullable: true
                          empty: true
                          when:
                            en: Returned when the request was made on behalf of a child customer.
                            zh: 代子客户调用时返回。
                    description: 创建后的 Global Account 信息。
                  error:
                    type:
                      - object
                      - "null"
                    properties:
                      type:
                        type: string
                        description: 标准化错误类型。
                      code:
                        type: string
                        description: 对外业务错误码，通常与 `respCode` 对齐。
                      message:
                        type: string
                        description: 可读错误信息。
                      param:
                        type:
                          - string
                          - "null"
                        description: 触发错误的请求字段名。
                        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: 用于排查问题的请求 ID。
                        x-onerway-value:
                          nullable: true
                          empty: true
                          when:
                            en: Returned when the request ID is available in the failure context.
                            zh: 失败上下文中可取得请求 ID 时返回。
                    description: 账户服务返回的结构化错误信息。
                    x-onerway-value:
                      nullable: true
                      when:
                        en: Returned when the Global Account request fails.
                        zh: Global Account 请求失败时返回。
              examples:
                create-global-account:
                  summary: Global Account 已创建
                  value:
                    success: true
                    respCode: "20000"
                    respMsg: Success
                    data:
                      globalAccountId: "2002"
```