添加虚拟卡地址

在调用方账户上保存用于虚拟卡签发的账单地址。该地址将作为 BILLING 用户地址保存，后续可在 createVirtualCard 中作为 userAddressId 传入。当提供 authUserId 时，地址会为该授权用户所对应的底层用户保存，同时仍附加在调用方的账户上。authUserId 必须是调用方账户上处于 ACTIVE 状态的非所有者授权用户指派。如果在调用方账户上，目标持卡人已存在完全相同的账单地址，则返回已存在的地址而不是创建副本。匹配基于地址字段、账户、目标用户以及 BILLING 类型进行。

先决条件： 具有 CREATE_VIRTUALCARD 范围的 Bearer 令牌。

账单地址必须可验证此变更会存储账单地址。它必须是真实且可投递的美国地址（US、USA 或 United States），且城市、州与邮编必须正确，且不接受邮政信箱（PO Box）。在创建虚拟卡时会运行 USPS/Smarty 校验——无法在该处通过验证的地址会导致卡片创建以 VC-0025 失败。完整字段规则与示例见地址格式要求。

mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) {
  addVirtualCardAddress(input: $input) {
    userAddressId
    streetAddressLine1
    streetAddressLine2
    country
    city
    state
    postalCode
  }
}

参数

参数	类型	必填	说明
input	AddVirtualCardAddressInput!	是	账单地址请求的包装对象。
input.billingAddress	VirtualCardBillingAddressInput!	是	要为虚拟卡签发保存的账单地址。
input.billingAddress.streetAddressLine1	String!	是	街道地址。发行方不接受邮政信箱（PO Box）。
input.billingAddress.streetAddressLine2	String	否	可选的公寓、套房或第二行地址。空值将保存为 `null`；非空值会被去除首尾空格。
input.billingAddress.country	String!	是	国家名称。目前发行方仅支持美国地址。
input.billingAddress.city	String!	是	城市。以大写形式保存。
input.billingAddress.state	String!	是	州名或美国两字母州代码。以大写形式保存。
input.billingAddress.postalCode	String!	是	5 位美国 ZIP 邮编。以大写形式保存。
input.authUserId	UUID	否	授权用户 ID（UAC 角色指派 ID）。提供时，为该授权持卡人保存地址。

响应

{
  "data": {
    "addVirtualCardAddress": {
      "userAddressId": "1f6b2c3d-4e5f-4a67-9a10-2b3c4d5e6f70",
      "streetAddressLine1": "123 Main St",
      "streetAddressLine2": "Apt 5",
      "country": "United States",
      "city": "NEW YORK",
      "state": "NY",
      "postalCode": "10001"
    }
  }
}

响应字段

字段	类型	说明
`userAddressId`	UUID	已保存的账单地址 ID。将此值作为 `userAddressId` 传入 `createVirtualCard`。
`streetAddressLine1`	String	街道地址第一行。
`streetAddressLine2`	String	街道地址第二行，未提供时为 `null`。
`country`	String	国家名称。
`city`	String	保存到地址的城市。
`state`	String	保存到地址的州。
`postalCode`	String	保存到地址的邮编。

示例请求

为调用方保存账单地址：

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "query": "mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) { addVirtualCardAddress(input: $input) { userAddressId streetAddressLine1 streetAddressLine2 country city state postalCode } }",
  "variables": {
    "input": {
      "billingAddress": {
        "streetAddressLine1": "123 Main St",
        "streetAddressLine2": "Apt 5",
        "country": "United States",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001"
      }
    }
  }
}'

为授权用户保存账单地址：

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "query": "mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) { addVirtualCardAddress(input: $input) { userAddressId streetAddressLine1 streetAddressLine2 country city state postalCode } }",
  "variables": {
    "input": {
      "authUserId": "8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d",
      "billingAddress": {
        "streetAddressLine1": "456 Market St",
        "streetAddressLine2": "Suite 200",
        "country": "United States",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105"
      }
    }
  }
}'

const response = await fetch('https://transactional-graph.staging.fluzapp.com/api/v1/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    query: `
      mutation AddVirtualCardAddress(
        $input: AddVirtualCardAddressInput!
      ) {
        addVirtualCardAddress(input: $input) {
          userAddressId
          streetAddressLine1
          streetAddressLine2
          country
          city
          state
          postalCode
        }
      }
    `,
    variables: {
      input: {
        authUserId: '8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d',
        billingAddress: {
          streetAddressLine1: '456 Market St',
          streetAddressLine2: 'Suite 200',
          country: 'United States',
          city: 'San Francisco',
          state: 'CA',
          postalCode: '94105',
        },
      },
    },
  }),
});

const data = await response.json();
console.log('Virtual card address saved:', data.data.addVirtualCardAddress);

错误代码

代码	消息	说明
`ARG-0001`	Invalid arguments received	缺少必填的地址字段、存在空值，或 `authUserId` 不是有效的 UUID。
`AUTH-0008`	Invalid user access	Bearer 令牌无法解析到调用方。请确认令牌有效。
`AUTH-0031`	The requested scopes must be granted by the user first.	令牌缺少保存虚拟卡地址所需的 `CREATE_VIRTUALCARD` 范围。
`AUTH-0034`	No authorized user found with this id on the caller’s account.	调用方账户上不存在该 `authUserId`，或其状态不是 ACTIVE，或指向的是 OWNER 指派。
`VC-0001`	Please try another payment method. If you continue experiencing issues, please contact our support team.	保存账单地址时发生一般性故障。请重试或联系支持。

后续步骤

创建虚拟卡

将返回的 userAddressId 传入 createVirtualCard。

设置虚拟卡 PIN

在可用于线下或需输入 PIN 的交易之前必须完成此步骤。

​参数

​响应

​响应字段

​示例请求

​错误代码

​后续步骤

创建虚拟卡

设置虚拟卡 PIN

参数

响应

响应字段

示例请求

错误代码

后续步骤