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

# 新增銀行卡

# 背景

在 Fluz 中，資金來源（亦稱付款方式）用於購買禮品卡、為虛擬卡交易提供資金、將資金存入你的 Fluz 餘額等。你首先需要確保至少新增一個資金來源，才能在 Fluz 完成交易。使用者帳戶可擁有以下類型：

* **銀行卡** - 借記卡、信用卡或預付卡。請注意，信用卡的手續費通常較高且現金回饋可能低於借記卡。
* **銀行帳戶** - 銀行帳戶沒有手續費。然而，只能在 Fluz App 或網頁入口新增。
* **PayPal 帳戶** - 如 PayPal 等數位錢包通常具最高手續費，且需從 Fluz App 或網頁入口新增。

你必須新增一張銀行卡作為備用付款方式，才能完成購買。

<Note>
  **目前，使用者只能透過 API 新增銀行卡作為資金來源。**
</Note>

# 新增銀行卡

## 範例請求

你可以使用 `addBankCard` [mutation](https://storage.googleapis.com/fluz-public-docs/api-reference.html#group-Reference-Mutations) 新增一張銀行卡。此 mutation 允許你提供必要資訊，將銀行卡新增至使用者帳戶。該查詢接受 `AddBankCardInput` 輸入物件。

```json theme={null}
{
  "query": "mutation addBankCard($input: AddBankCardInput!) { addBankCard(input: $input) { bankCardId ownerAccountId addedUserId cardType cardProcessor cardholderName lastFourDigits expirationMonth expirationYear cardStatus billingAddressId nickname }}",
  "variables": {
    "input": {
      "cardNumber": "4111111111111111",
      "expirationMonth": "01",
      "expirationYear": "2029",
      "cvv": "111",
      "cardholderName": "John Doe",
      "nickname": "My travel card",
      "preferredMerchantCategoryCode": "5411",
      "billingAddress": {
        "streetAddressLine1": "123 Example St",
        "streetAddressLine2": "Unit 1",
        "country": "United States",
        "city": "New York City",
        "state": "New York",
        "postalCode": "12345"
      }
    }
  }
}
```

此 mutation 需要 `AddBankCardInput` 輸入型別。任何在 schema 中以驚嘆號（`!`）標示的欄位皆為必填，必須包含於請求中。

若要將地址與你的銀行卡關聯，必須使用 `billingAddress` 或 `userAddressId` 輸入欄位其中之一。請確保只提供其中一個欄位，以符合驗證要求。

* **新增地址**：若要新增地址，請使用 `billingAddress` 輸入欄位定義此卡所對應的地址資訊。
* **既有地址**：若要連結既有地址，請使用 `userAddressId` 輸入欄位，指定系統中已儲存地址的識別碼。你可以使用 `getUserAddresses` 查詢以尋找既有的 `userAddressId`。

<Note>
  **帳單地址格式**

  請以發卡機構紀錄中的格式，使用結構化欄位（`streetAddressLine1`、`streetAddressLine2`、`city`、`state`、`postalCode`、`country`）完整提供帳單地址。帳單地址若不相符或格式不正確，可能導致地址驗證（AVS）失敗。銀行卡支援國際帳單地址。請參閱 [地址格式要求](/concepts/address-formatting-requirements) 以取得格式規則與範例。
</Note>

| Field name                    | Type             | Description                  |
| ----------------------------- | ---------------- | ---------------------------- |
| cardNumber                    | String!          | 卡號。此欄位需要完整卡號，通常為 16 位數。      |
| expirationMonth               | String!          | 卡片到期月份，格式為 MM（例如："07" 代表七月）。 |
| expirationYear                | String!          | 三或四位數的安全碼，位於卡片背面或正面。         |
| cvv                           | String!          | 三或四位數的安全碼，位於卡片背面或正面。         |
| cardholderName                | String!          | 卡片上顯示的持卡人姓名。                 |
| billingAddress                | UserAddressInput | 選填。使用此欄位以新帳單地址建立卡片。          |
| userAddressId                 | UUID             | 選填。使用此欄位將卡片關聯至既有的使用者地址。      |
| nickname                      | String           | 選填。使用此欄位為卡片建立暱稱。             |
| preferredMerchantCategoryCode | String           | 選填。使用此欄位將卡片關聯至商家分類代碼。        |

## AddBankCardInput

```json theme={null}
{
  "cardNumber": "xyz789",
  "expirationMonth": "xyz789",
  "expirationYear": "abc123",
  "cvv": "abc123",
  "cardholderName": "abc123",
  "billingAddress": UserAddressInput,
  "userAddressId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "nickname": "My travel card",
  "preferredMerchantCategoryCode": "5411"
}
```

## 範例回應

`addBankCard` mutation 的回應會包含你在請求中指定的欄位，以及相關的 ID 值與卡片處理方。

```json theme={null}
{
  "data": {
    "addBankCard": {
      "bankCardId": "4111111111111111",
      "ownerAccountId": "a578fe07-7165-47b8-b147-2251c99b7fc1",
      "addedUserId": "8d197a56-53df-439b-85cd-bb88dfca9a5f",
      "cardType": "Visa",
      "cardProcessor": "Stripe",
      "cardholderName": "John Doe",
      "lastFourDigits": "1234",
      "expirationMonth": "12",
      "expirationYear": "2025",
      "cardStatus": "active",
      "billingAddressId": "e7979eb7-1727-48ed-8c5a-c56532908c1e",
      "nickname": "My travel card"
    }
  }
}
```

<Note>
  **僅供個人應用程式使用**

  目前僅授權個人應用程式具備將銀行卡新增至帳戶的範圍。公開發佈的應用程式若要將銀行卡新增至帳戶，需完成 PCI 認證並提交 PCI 相容性聲明。
</Note>

若你想將特定資金來源設為帳戶中的主要、偏好或備用，需至 Fluz 控制台進行管理。

想了解更多嗎？請透過你的支援電子郵件與我們聯絡。與我們的專家洽談以取得更多資訊或申請示範。

<br />