# 生成卡 token

> 在 PCI DSS 合规接入中生成卡 token，并通过 notifyUrl 接收最终 tokenization 结果。

```yaml
openapi: 3.1.0
info:
  title: 生成卡 token
  version: 1.0.0
  description: 在 PCI DSS 合规接入中生成卡 token，并通过 notifyUrl 接收最终 tokenization 结果。
paths:
  /v1/txn/bindCard:
    post:
      summary: 生成卡 token
      description: 在 PCI DSS 合规接入中生成卡 token，并通过 notifyUrl 接收最终 tokenization 结果。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                appId:
                  type: string
                  description: 商户入驻 Onerway 后生成的店铺 ID。
                cardInfo:
                  type: string
                  description: 商户后端在 PCI DSS 合规环境下直接采集的卡支付信息；授权后不得存储敏感认证数据。
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      holderName:
                        type: string
                        description: 商户在 PCI DSS 合规环境中采集的持卡人姓名。
                      cardNumber:
                        type: string
                        description: 商户在 PCI DSS 合规环境中采集的完整卡号。
                        x-onerway-constraints:
                          - kind: rule
                            text: 仅提交数字，不包含空格；发送前应通过 Luhn 算法校验。
                      month:
                        type: string
                        description: 卡片有效期月份。
                        x-onerway-constraints:
                          - kind: values
                            text: 使用 `01` 到 `12` 的两位月份。
                      year:
                        type: string
                        description: 卡片有效期年份。
                        x-onerway-constraints:
                          - kind: rule
                            text: 使用四位年份，并提交未过期的有效期。
                      cvv:
                        type: string
                        description: 用于授权的卡片安全码。
                        x-onerway-constraints:
                          - kind: rule
                            text: Visa、Mastercard、Discover 通常为 3 位；American Express 为 4 位。授权后不得存储 CVV。
                    required:
                      - holderName
                      - cardNumber
                      - month
                      - year
                      - cvv
                  x-onerway-format: json_string
                country:
                  type: string
                  description: 客户国家或地区代码，使用 [ISO 3166-1
                    alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
                    两位字母格式。
                email:
                  type: string
                  description: 客户邮箱地址，用于交易确认和争议处理。
                merchantCustId:
                  type: string
                  description: 客户在商户系统中的唯一标识；保存的卡 token 会关联到该客户。
                merchantNo:
                  type: string
                  description: Onerway 分配的商户号；获取方式参见[接入准备](/zh/payments/get-started/setup#获取凭证)。
                notifyUrl:
                  type: string
                  description: 接收最终卡 token 生成结果回调的 HTTPS 地址；回调会包含卡 token、脱敏卡信息等结果字段，报文契约见[保存支付方式结果
                    Webhook](/zh/payments/api-reference/webhooks/payment-method-result)。
                returnUrl:
                  type: string
                  description: 浏览器回跳 HTTPS 地址；用于绑卡 3DS challenge 跳转场景。
                sign:
                  type: string
                  description: 请求签名字符串；生成方式详见[请求签名](/zh/payments/get-started/request-signing)。
                transactionIp:
                  type: string
                  description: 商户采集的持卡人交易 IP；应传终端用户 IP，而不是商户服务器 IP。
              required:
                - appId
                - cardInfo
                - country
                - email
                - merchantCustId
                - merchantNo
                - notifyUrl
                - returnUrl
                - sign
                - transactionIp
            examples:
              card-tokenization:
                summary: 生成卡 token
                value:
                  appId: replace_with_app_id
                  cardInfo: '{"holderName":"replace_with_cardholder_name","cardNumber":"{{CARD-NUMBER}}","month":"12","year":"2030","cvv":"{{CVV}}"}'
                  country: US
                  email: customer@example.com
                  merchantCustId: cust_demo_tokenization_202606150001
                  merchantNo: replace_with_merchant_no
                  notifyUrl: https://developers.onerway.com/example-card-token-notify
                  returnUrl: https://developers.onerway.com/example-card-token-return
                  sign: "{{SIGN}}"
                  transactionIp: 192.0.2.10
      responses:
        "200":
          description: 令牌化同步返回成功状态
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: 响应码；`20000`
                      表示请求处理成功，其余为错误码。完整码表见[响应码](/zh/payments/api-reference/response-codes)。
                  respMsg:
                    type: string
                    description: 响应码对应的可读说明。
                  data:
                    type: object
                    properties:
                      transactionId:
                        type: string
                        description: Onerway 为本次令牌化请求生成的交易号。
                      tokenId:
                        type:
                          - string
                          - "null"
                        description: 用于后续 token 支付的卡
                          token，可在[直连下单接口](/zh/payments/api-reference/endpoints/direct-create-transaction)中以
                          `subProductType=TOKEN` 使用；仅在 tokenization 成功后保存。
                        x-onerway-value:
                          nullable: true
                          empty: true
                          when:
                            en: Has a value when `data.status=S` and card tokenization has succeeded.
                            zh: 当 `data.status=S` 且卡 token 生成成功后才有值。
                      status:
                        type: string
                        description: "`respCode=20000` 仅表示请求处理成功；同步处理状态需读取本字段，最终令牌化结果通过 `notifyUrl`
                          回调接收。"
                        enum:
                          - S
                          - R
                          - F
                        x-enum-descriptions:
                          S: 令牌化成功；确认成功后再保存 `tokenId`。
                          R: 需要 3DS 验证；需将持卡人跳转至 `redirectUrl` 继续完成验证。
                          F: 令牌化失败；需按响应码与业务提示处理失败结果。
                      redirectUrl:
                        type:
                          - string
                          - "null"
                        description: 3DS 验证跳转地址；需将持卡人跳转至该地址继续完成验证。
                        x-onerway-value:
                          nullable: true
                          empty: true
                          when:
                            en: Has a value when `data.status=R` and 3DS verification is required.
                            zh: 当 `data.status=R` 且需要 3DS 验证时才有值。
                      sign:
                        type: string
                        description: 响应签名字符串；当前不建议商户对响应验签。
                    description: 业务数据对象，承载本次令牌化请求的同步处理状态与后续动作字段。
              examples:
                tokenized:
                  summary: 令牌化同步返回成功状态
                  value:
                    respCode: "20000"
                    respMsg: Success
                    data:
                      transactionId: txn_demo_tokenization_202606150001
                      tokenId: example_token_id
                      status: S
                      redirectUrl: null
                      sign: "{{SIGN}}"
                redirect-required:
                  summary: 需要 3DS 跳转
                  value:
                    respCode: "20000"
                    respMsg: Success
                    data:
                      transactionId: txn_demo_tokenization_202606150002
                      tokenId: null
                      status: R
                      redirectUrl: https://developers.onerway.com/example-card-token-3ds
                      sign: "{{SIGN}}"
```