> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enroll Card in Network Protection

> <a href="/zh/card-issuance/v1.6/guide/card-products" style={{display:'inline-block',padding:'2px 10px',borderRadius:'9999px',fontSize:'12px',fontWeight:600,lineHeight:'18px',background:'#EEF2FF',color:'#4338CA',border:'1px solid #C7D2FE',textDecoration:'none'}}>仅 Business Visa</a>

将卡片注册到 ASAF（Account & Cardholder Fraud Solution）Network Protection。

使用此接口可将丢失、被盗、过期或已关闭的卡片注册到 Visa 网络，使其后续的授权尝试在全网范围内被拒绝。注册请求为异步——响应确认请求已受理，最终结果通过 `card.risk_control.network_protection.enrolled` webhook 送达。




## OpenAPI

````yaml /zh/card-issuance/v1.6/issuing.yaml post /v1/issuing/cards/{id}/risk
openapi: 3.0.2
info:
  title: Issuing API
  version: 0.0.1
  x-source-en-commit: fdf4a2b
  x-source-en-path: card-issuance/v1.6/issuing.yaml
  description: >
    UQPAY Issuing API 让你签发虚拟卡、管理持卡人，并监控卡交易。


    ## 功能概览

    - 创建并管理虚拟卡（签发、激活、冻结、注销）

    - 通过 KYC 完成持卡人入驻与验证

    - 设置消费限额与卡控制

    - 为卡余额充值与提现

    - 查询卡交易与账户余额

    - 在发卡账户之间转账

    - 生成并下载报表


    ## 身份认证

    所有请求都需要携带有效的鉴权 Token，Token 通过 [Access
    Token](/zh/account-center/v1.6/api-reference/access-token) 接口获取。请在
    `x-auth-token` 请求头中携带该 Token。


    ## 幂等性

    POST 请求支持 `x-idempotency-key` 请求头，可安全重试而不会创建重复资源。
  contact:
    name: UQPAY Support Team
    url: https://www.uqpay.com/support
    email: support@uqpay.com
  license:
    name: Proprietary
    url: https://www.uqpay.com/legal/api-terms
  termsOfService: https://www.uqpay.com/legal/terms
  x-api-id: uqpay-issuing-api-v1.6.0
  x-categories:
    - Card Issuing
    - Transaction Processing
  x-features:
    - Virtual Card Issuance
    - Real-time Processing
    - Webhook Notifications
    - Comprehensive Reporting
    - Transaction Monitoring
servers:
  - url: https://api-sandbox.uqpaytech.com/api
    description: 沙盒环境基础 URL。
  - url: https://api.uqpay.com/api
    description: 生产环境基础 URL。
security: []
tags:
  - name: Card Lifecycle
    description: 创建卡片并管理其完整生命周期——签发、查询、更新、激活、绑定与变更状态。
  - name: Card Secure Data
    description: 通过 PCI 合规接口或令牌化 iframe 访问敏感卡数据（PAN、CVV）。是否可用取决于你的 PCI 状态，而非卡产品。
  - name: Card Funding
    description: 为预付类卡片充值或提取其卡内储值余额。
  - name: Card PIN
    description: 设置并管理卡片 PIN 码。`reset-pin` 用于实体卡，`manage-card-pin` 用于虚拟卡。
  - name: Card Add-ons
    description: >-
      产品专属的卡功能。每个操作仅适用于特定卡产品——参见
      [卡产品](/zh/card-issuance/v1.6/guide/card-products)。
  - name: Card Arts
    description: >-
      管理发卡账户可用的视觉设计（卡面）。可设置账户级默认卡面，或在签发/更新卡片时传入 `card_art_id` 以按卡覆盖。仅 Personal
      Visa 支持。
  - name: Cardholders
    description: 你可以创建持卡人。持卡人是你企业的授权代表，可被签发卡片。
  - name: Transactions
    description: 这些接口用于查询在你用户卡片上发生的交易信息。
  - name: Products
    description: 通过这组接口，你可以为客户创建卡订单。
  - name: Balances
    description: 各币种的可用金额与待处理金额会进一步按资金来源类型细分。你可以查询它，查看发卡账户当前的余额。
  - name: Transfers
    description: 在发卡账户之间转账。
  - name: Reports
    description: 生成并下载发卡报表。
  - name: Simulator
    description: 在沙盒环境中模拟卡交易。
paths:
  /v1/issuing/cards/{id}/risk:
    post:
      tags:
        - Card Add-ons
      summary: Enroll Card in Network Protection
      description: >
        <a href="/zh/card-issuance/v1.6/guide/card-products"
        style={{display:'inline-block',padding:'2px
        10px',borderRadius:'9999px',fontSize:'12px',fontWeight:600,lineHeight:'18px',background:'#EEF2FF',color:'#4338CA',border:'1px
        solid #C7D2FE',textDecoration:'none'}}>仅 Business Visa</a>


        将卡片注册到 ASAF（Account & Cardholder Fraud Solution）Network Protection。


        使用此接口可将丢失、被盗、过期或已关闭的卡片注册到 Visa
        网络，使其后续的授权尝试在全网范围内被拒绝。注册请求为异步——响应确认请求已受理，最终结果通过
        `card.risk_control.network_protection.enrolled` webhook 送达。
      operationId: enroll-card-network-protection
      parameters:
        - $ref: '#/components/parameters/IdPath'
        - $ref: '#/components/parameters/XOnBehalfOf'
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollNetworkProtectionRequest'
      responses:
        '200':
          headers:
            x-response-id:
              $ref: '#/components/headers/XResponseId'
          description: 注册请求已受理。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ASAFNetworkProtectionResponse'
                title: EnrollNetworkProtectionResponse
      security:
        - XAuthToken: []
components:
  parameters:
    IdPath:
      name: id
      description: 资源的全局唯一标识符（UUID v4）。
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 71fdb0fe-9682-457a-9361-e8868694f12f
    XOnBehalfOf:
      in: header
      name: x-on-behalf-of
      schema:
        type: string
      required: false
      description: >
        指定代表哪个子账户发起请求。应设置为 `account_id`，该值可通过 [List Connected
        Accounts](/zh/account-center/v1.6/api-reference/list-connected-accounts)
        接口获取。若省略或为空，则请求以主账户身份执行。

        更多信息参见 [关联账户](/zh/account-center/v1.6/guide/connected-accounts)。
      example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be
    XIdempotencyKey:
      in: header
      name: x-idempotency-key
      schema:
        type: string
        format: uuid
      required: true
      description: 用于维持操作幂等性的唯一标识符（UUID），确保同一操作的重复执行不会产生意外影响或重复。它有助于在网络错误、重试或失败的情况下保持数据一致性。
      example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be
  schemas:
    EnrollNetworkProtectionRequest:
      type: object
      required:
        - risk_control
        - action_code
      properties:
        risk_control:
          type: string
          enum:
            - network_protection
          description: 风控类型。ASAF 注册时必须为 `network_protection`。
          example: network_protection
        action_code:
          $ref: '#/components/schemas/NetworkProtectionActionCode'
    ASAFNetworkProtectionResponse:
      type: object
      description: 针对 ASAF Network Protection 注册或移除请求返回的确认信息。
      properties:
        card_id:
          type: string
          format: uuid
          example: 7f6dbbd9-37b9-4f64-a021-cd4f71234567
          description: 卡片的唯一标识符。
        card_number:
          type: string
          example: '************1234'
          description: 脱敏卡号。
        cardholder_id:
          type: string
          format: uuid
          example: b6e6268b-7d95-4700-9b87-12e7c1234567
          description: 持卡人的唯一标识符。
        card_scheme:
          type: string
          example: VISA
          description: 卡组织。
        enabled:
          type: boolean
          example: false
          description: >-
            该卡片当前是否启用了 Network
            Protection。此字段反映请求被网络处理后的状态——由于注册和移除是异步的，它可能不会立即变化。
        status:
          $ref: '#/components/schemas/NetworkProtectionStatus'
        action_code:
          $ref: '#/components/schemas/NetworkProtectionActionCode'
        definition:
          type: string
          example: Lost card, pickup
          description: '`action_code` 的可读描述。'
        update_time:
          type: string
          format: date-time
          nullable: true
          example: '2026-05-14T09:00:00Z'
          description: 注册或移除请求最后一次更新的时间。
    NetworkProtectionActionCode:
      type: string
      description: |
        ASAF 操作码，表示卡片被注册到 Network Protection 的原因。

        - `04` —— 收卡
        - `41` —— 卡片挂失，收卡
        - `43` —— 卡片被盗，收卡
        - `46` —— 账户已关闭
        - `54` —— 卡片已过期
      enum:
        - '04'
        - '41'
        - '43'
        - '46'
        - '54'
      example: '41'
    NetworkProtectionStatus:
      type: string
      description: ASAF Network Protection 注册的生命周期状态。
      enum:
        - NOT_ENROLLED
        - ENROLL_PENDING
        - ENROLL_FAILED
        - ENROLLED
        - REMOVAL_PENDING
      example: ENROLL_PENDING
  headers:
    XResponseId:
      description: 响应的全局唯一标识符（UUID v4）。在联系 UQPAY 支持团队时有助于定位某次请求。
      schema:
        type: string
        format: uuid
        example: 2adba88e-9d63-44bc-b975-9b6ae3440dde
  securitySchemes:
    XAuthToken:
      type: apiKey
      in: header
      name: x-auth-token
      description: 由 UQPay 提供的登录 API Token。

````