新增虛擬卡地址

在呼叫者的帳戶上儲存用於虛擬卡發行的帳單地址。該地址會以 BILLING 使用者地址儲存，之後可作為 userAddressId 傳入 createVirtualCard。當提供 authUserId 時，地址會儲存至該授權使用者所對應的底層使用者，同時仍附加在呼叫者的帳戶上。authUserId 必須是呼叫者帳戶上處於 ACTIVE 狀態、且非 OWNER 的授權使用者指派。如果呼叫者帳戶上，目標持卡人的相同帳單地址已存在，將會回傳現有地址，而不是建立重複項。比對會依據地址欄位、帳戶、目標使用者，以及 BILLING 類型進行。

先決條件： 具備 CREATE_VIRTUALCARD 權限範圍的 Bearer 權杖。

帳單地址必須可驗證此 mutation 會儲存帳單地址。必須是實際可投遞的美國地址（US、USA 或 United States），且城市、州別與郵遞區號需正確，並且不接受郵政信箱（PO Box）。USPS/Smarty 檢查會在建立虛擬卡時進行——無法在該處驗證的地址，會導致卡片建立以 VC-0025 失敗。完整欄位規則與範例請參見地址格式要求。

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

參數

Parameter	Type	Required	Description
input	AddVirtualCardAddressInput!	Yes	用於帳單地址請求的包裝物件。
input.billingAddress	VirtualCardBillingAddressInput!	Yes	要儲存以供虛擬卡發行使用的帳單地址。
input.billingAddress.streetAddressLine1	String!	Yes	街道地址。發卡機構不接受郵政信箱。
input.billingAddress.streetAddressLine2	String	No	選填的公寓、套房或次要地址行。空值會儲存為 `null`；非空值會被去除前後空白。
input.billingAddress.country	String!	Yes	國家名稱。目前發卡機構僅支援美國地址。
input.billingAddress.city	String!	Yes	城市。會以大寫儲存。
input.billingAddress.state	String!	Yes	州名或兩碼美國州別代碼。會以大寫儲存。
input.billingAddress.postalCode	String!	Yes	5 碼美國 ZIP 郵遞區號。會以大寫儲存。
input.authUserId	UUID	No	授權使用者 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"
    }
  }
}

回應欄位

Field	Type	Description
`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);

錯誤代碼

Code	Message	Description
`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 碼

參數

回應

回應欄位

範例請求

錯誤代碼

後續步驟