> ## 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 应用或网页门户中添加。
* **PayPal 账户** - 像 PayPal 这样的数字钱包通常费用最高，且需要通过 Fluz 应用或网页门户添加。

您必须添加一张银行卡作为备用支付方式才能进行购买。

<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` 输入类型。架构中带有感叹号（`!`）的字段为必填，必须包含在请求中。

要将地址与您的银行卡关联，必须使用 `billingAddress` 或 `userAddressId` 输入字段之一。请确保仅提供其中一个字段以满足校验要求。

* **新地址**：若要添加新地址，请使用 `billingAddress` 输入字段定义与此卡关联的地址详情。
* **已有地址**：若要关联已有地址，请使用 `userAddressId` 输入字段，指定系统中已存储地址的标识符。您可以使用 `getUserAddresses` 查询查找现有的 `userAddressId`。

<Note>
  **账单地址格式**

  请完全按照发卡机构记录提供账单地址，并使用结构化字段（`streetAddressLine1`、`streetAddressLine2`、`city`、`state`、`postalCode`、`country`）。不匹配或格式错误的账单地址可能导致地址校验（AVS）失败。银行卡支持国际账单地址。有关格式规则和示例，请参阅 [地址格式要求](/concepts/address-formatting-requirements)。
</Note>

| 字段名                           | 类型               | 描述                             |
| ----------------------------- | ---------------- | ------------------------------ |
| cardNumber                    | String!          | 卡号。此字段需要完整卡号，通常为 16 位数字。       |
| expirationMonth               | String!          | 卡的到期月份，格式为 MM（例如，"07" 表示 7 月）。 |
| 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 />