# 创建持卡人

> 在商户账户下创建持卡人。

```yaml
openapi: 3.1.0
info:
  title: 创建持卡人
  version: 1.0.0
  description: 在商户账户下创建持卡人。
paths:
  /api/v1/merchant/cardholder/createCardholder:
    post:
      summary: 创建持卡人
      description: 在商户账户下创建持卡人。
      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:
                merchantNo:
                  type: integer
                  description: Onerway 分配的商户号。
                clientRequestId:
                  type: string
                  description: 幂等请求 ID。
                firstName:
                  type: string
                  description: 持卡人名。
                lastName:
                  type: string
                  description: 持卡人姓。
                email:
                  type: string
                  description: 持卡人邮箱。
                  x-onerway-constraints:
                    - kind: rule
                      text: 必须是合法邮箱地址。
                mobile:
                  type: string
                  description: 持卡人手机号。
                mobileAreaCode:
                  type: string
                  description: 手机国际区号。
                birthDay:
                  type: string
                  description: 出生日期。
                nationality:
                  type: string
                  description: 国籍，使用 ISO 3166-1 alpha-2 两位代码。
                addressRegionCode:
                  type: string
                  description: 地址国家或地区代码。
                addressStateCode:
                  type: string
                  description: 州 / 省代码。
                addressCityCode:
                  type: string
                  description: 城市代码。
                addressDetailLine1:
                  type: string
                  description: 地址行 1。
                addressDetailLine2:
                  type: string
                  description: 地址行 2。
                addressPostalCode:
                  type: string
                  description: 邮编。
                remark:
                  type: string
                  description: 备注。
              required:
                - merchantNo
                - clientRequestId
                - firstName
                - lastName
                - email
            examples:
              default:
                summary: 创建持卡人
                value:
                  addressCityCode: SZ
                  addressDetailLine1: Example address line 1
                  addressPostalCode: "518000"
                  addressRegionCode: CN
                  addressStateCode: GD
                  birthDay: 1990-01-01
                  clientRequestId: REQ_CH_20260101_001
                  email: example_cardholder@example.com
                  firstName: Alex
                  lastName: Chen
                  merchantNo: 88888
                  mobile: "13800138000"
                  mobileAreaCode: "+86"
                  nationality: CN
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: 业务响应码；`20000` 表示成功。
                  respMsg:
                    type: string
                    description: 响应信息。
                  data:
                    type:
                      - object
                      - "null"
                    properties:
                      cardholderId:
                        type: integer
                        description: Onerway 生成的持卡人 ID。
                      firstName:
                        type: string
                        description: 持卡人名。
                      lastName:
                        type: string
                        description: 持卡人姓。
                      email:
                        type: string
                        description: 持卡人邮箱。
                      mobile:
                        type:
                          - string
                          - "null"
                        description: 持卡人手机号。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No mobile number is provided.
                            zh: 未提供手机号时返回 `null`。
                      mobileAreaCode:
                        type:
                          - string
                          - "null"
                        description: 手机国际区号。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No mobile area code is provided.
                            zh: 未提供手机号区号时返回 `null`。
                      birthDay:
                        type:
                          - string
                          - "null"
                        description: 出生日期。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No date of birth is provided.
                            zh: 未提供出生日期时返回 `null`。
                      nationality:
                        type:
                          - string
                          - "null"
                        description: 国籍，使用 ISO 3166-1 alpha-2 两位代码。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No nationality is provided.
                            zh: 未提供国籍时返回 `null`。
                      addressRegionCode:
                        type:
                          - string
                          - "null"
                        description: 地址国家或地区代码。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No address region is provided.
                            zh: 未提供地址国家或地区时返回 `null`。
                      addressStateCode:
                        type:
                          - string
                          - "null"
                        description: 州 / 省代码。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No state or province is provided.
                            zh: 未提供州 / 省代码时返回 `null`。
                      addressCityCode:
                        type:
                          - string
                          - "null"
                        description: 城市代码。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No city is provided.
                            zh: 未提供城市代码时返回 `null`。
                      addressDetailLine1:
                        type:
                          - string
                          - "null"
                        description: 地址行 1。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No address line is provided.
                            zh: 未提供地址行时返回 `null`。
                      addressDetailLine2:
                        type:
                          - string
                          - "null"
                        description: 地址行 2。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No address line 2 is provided.
                            zh: 未提供地址行 2 时返回 `null`。
                      addressPostalCode:
                        type:
                          - string
                          - "null"
                        description: 邮编。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No postal code is provided.
                            zh: 未提供邮编时返回 `null`。
                      remark:
                        type:
                          - string
                          - "null"
                        description: 备注。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: No remark is provided.
                            zh: 未提供备注时返回 `null`。
                    description: 持卡人信息。
                    x-onerway-value:
                      nullable: true
                      when:
                        en: Returned as `null` when cardholder creation fails.
                        zh: 创建持卡人失败时返回 `null`。
              examples:
                success:
                  summary: 成功
                  value:
                    respCode: "20000"
                    respMsg: success
                    data:
                      cardholderId: 300001
                      firstName: Alex
                      lastName: Chen
                      email: example_cardholder@example.com
                      mobile: "13800138000"
                      mobileAreaCode: "+86"
                      birthDay: 1990-01-01
                      nationality: CN
                      addressRegionCode: CN
                      addressStateCode: GD
                      addressCityCode: SZ
                      addressDetailLine1: Example address line 1
                      addressDetailLine2: null
                      addressPostalCode: "518000"
                      remark: null
```