Link External Bank Cards

A bank card — debit, credit, or prepaid — is the most flexible funding source on Fluz and the only one that can be added programmatically. Bank cards are used to pay for gift card purchases, fund virtual card transactions, deposit to your Fluz balance, and serve as the required backup for other payment methods.

Bank cards can be added and managed through the API or through the Fluz app and web portal.

❗️
A bank card must be added as a backup payment method before any transaction can complete.
When a user pays via ACH, a temporary hold may be placed on the backup card for the transaction amount. If the ACH payment clears, the hold releases within 1–7 business days. If it does not clear, the backup card is charged instead.

What You Can Do

Action	Mutation	Description
Add Bank Card	`addBankCard`	Add a debit, credit, or prepaid card to a user's account with a billing address.
Update Bank Card	`updateBankCardNickname` · `updateBankCardPreferredMerchantCategoryCode`	Rename a card or set its preferred merchant category code (MCC).
Delete Bank Card	`deleteBankCard`	Remove a card by setting its status to `INACTIVE`.

All bank card mutations require the MANAGE_PAYMENT scope.

Fees & CashbackCard type affects the effective cashback rate a user earns on a purchase:

Card Type	Processing Fee	Relative Cashback
Debit	–1%	Higher
Credit	–3%	Lower
Prepaid	Varies by card	Varies

💡
Debit cards earn more cashback than credit cards.
Bank accounts (ACH) carry no processing fees and earn the full merchant cashback rate. Where a user has the choice, ACH earns the most, debit is next, and credit carries the highest fee. See Bank Accounts for the fee-free option.

Requirementsope. Every bank card mutation requires the `MANAGE_PAYMENT` scope on the user access token.

Billing address. Each card must be associated with an address. Provide either a new billingAddress object or an existing userAddressId — not both. Use the getUserAddresses query to look up a stored userAddressId.

❗️
Only personal applications can add bank cards via the API.
Publicly available applications that want to add bank cards will need to complete PCI certification and an attestation of PCI compliance. If your application is not PCI-certified, direct users to add bank cards through the Fluz app or web portal.

Setting a Primary, Preferred, or Backup Cardng, updating, and deleting cards is available via the API. Choosing which funding source is primary, preferred, or backup is managed in the Fluz dashboard, not through the API.

Reading Bank Cardse `getWallet` query to return all bank cards on a user's account, along with their type, last four digits, and current status.

query getWallet {
  getWallet {
    bankCards {
      bankCardId
      cardType
      lastFourDigits
      cardStatus
    }
  }
}

See View Funding Sources for the full field reference.

Want to learn more? Speak with our experts for more info or to request a demo.

A bank card must be added as a backup payment method before any transaction can complete.

What You Can Do

Fees & CashbackCard type affects the effective cashback rate a user earns on a purchase:

Debit cards earn more cashback than credit cards.

Requirementsope. Every bank card mutation requires the MANAGE_PAYMENT scope on the user access token.

Only personal applications can add bank cards via the API.

Setting a Primary, Preferred, or Backup Cardng, updating, and deleting cards is available via the API. Choosing which funding source is primary, preferred, or backup is managed in the Fluz dashboard, not through the API.

Reading Bank Cardse getWallet query to return all bank cards on a user's account, along with their type, last four digits, and current status.

Requirementsope. Every bank card mutation requires the `MANAGE_PAYMENT` scope on the user access token.

Reading Bank Cardse `getWallet` query to return all bank cards on a user's account, along with their type, last four digits, and current status.