Skip to content

DOC-597/enrich-the-suvc-section #525

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
max-koro wants to merge 2 commits into
base: main
Choose a base branch
from
Open

DOC-597/enrich-the-suvc-section #525

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6ee6240
DOC-597/enrich-the-suvc-section
max-koro Jan 6, 2026
117b3d2
Update index.mdx
max-koro Jan 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion docs/topics/cards/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ Use **settings to manage your card product** and all virtual, physical, and digi
| Name | You can name the card product for easy reference from your Dashboard. | Dashboard |
| Allow physical cards | Decide whether physical cards are allowed to be issued for this card product. | Dashboard |
| Suspend | Suspend this card product. Your users won't be able to add new cards with this card product. You'll need to contact Swan Support to reactivate the card product. | Dashboard |
| `cardContractExpiryDate` | Date you'd like the card to expire.<br /><br />Leave it empty if you don't want to set an expiration date, in which case, cards are renewed automatically every three years. | API |
| `cardContractExpiryDate` | Date you'd like the card to expire.<br /><br />Leave it empty if you don't want to set an expiration date, in which case, cards are renewed automatically every three years. The standard expiration period for all cards is 3 years from creation. | API |
| `international` | Allow or disable payments outside of the account holder's country. | API |
| `withdrawal` | Allow or disable cash withdrawals, such as at ATMs. | API |
| `nonMainCurrencyTransactions` | Allow or disable transactions outside of the card's currency. | API |
Expand All @@ -153,6 +153,20 @@ You can (1) manage existing card products that are already validated, or (2) cre

![Screenshot of the Dashboard cards page with callouts on an existing card and create new option](../../images/topics/cards/cards-dashboard-settings.png)

### Custom card expiry {#custom-expiry}

You can customize the expiration date for virtual cards using the `cardContractExpiryDate` field.
This setting is available in the following mutations:

- [`addCard`](https://api-reference.swan.io/mutations/add-card/): add a single virtual card.
- [`addCards`](https://api-reference.swan.io/mutations/add-cards/): add multiple virtual cards.
- [`updateCard`](https://api-reference.swan.io/mutations/update-card/): update an existing card.
- [`addSingleUseVirtualCard`](https://api-reference.swan.io/mutations/add-single-use-virtual-card/): add a single-use virtual card.

:::warning One-off SUV cards
For one-off single-use virtual cards with `SpendingLimitPeriod` set to `Always`, cards automatically expire 30 days after creation. This overrides any custom expiry date you set.
:::

## Spending limits {#limits}

A **spending limit** is the **maximum amount** a cardholder can spend within a certain **rolling period**.
Expand Down
42 changes: 40 additions & 2 deletions docs/topics/cards/virtual/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,17 @@ For one-off cards, the `AccountHolderSpendingLimit.period` is `Always`.
Swan automatically sets the `cardContractExpiryDate` to 30 days from creation when the spending limit period is `Always`.
:::

### Card status after spending limit {#suv-one-off-status}

When a one-off SUV card reaches its spending limit, the card becomes unusable.
The card status remains `Enabled`, but transactions are declined once the spending limit is reached.

You can track remaining spending using the `spending` field in the card query.

:::tip Best practice
Cancel one-off SUV cards after the expected debit has been used to prevent confusion about the card's usability.
:::

### Recurring {#suv-recurring}

You can think of recurring SUV cards as single *merchant* virtual cards.
Expand All @@ -81,12 +92,41 @@ When the cardholder uses a recurring SUV card for the first time, Swan restricts
If the card is used with the same merchant, the merchant ID matches and the transaction can go through.
However, if the cardholder tries to use the card elsewhere, the transaction is rejected because the merchant IDs don't match.

#### Spending limits for recurring cards {#suv-recurring-limits}

Recurring SUV cards have spending limits tied to the defined period (`Daily`, `Weekly`, or `Monthly`), not to individual transactions.
A recurring SUV card with a €500 weekly limit, for example, can be used multiple times with the same merchant until the €500 limit is reached within the rolling 7-day period.

There's no restriction on the number of times a recurring card can be used with the same merchant, as long as spending stays within the limit for the defined period.
The spending limit resets on a rolling basis. Refer to [hour-level aggregation](../index.mdx#hour-level-aggregation) for details on how rolling periods are calculated.

#### Disabling a recurring SUV cardholder's membership

When the cardholder of a recurring SUV card's account membership is disabled, the card is automatically reassigned to the account's legal representative and remains active, ensuring their expenses are not interrupted.

This automatic reassignment maintains business continuity while preserving proper account control.

## Renewal and expiry {#renewal}

Virtual cards have a standard expiration period of **3 years from creation**.

Standard virtual cards are renewed automatically unless a custom `cardContractExpiryDate` is set.
When renewed, the card number and CVC remain the same, the expiry date extends by 3 years, and all associated physical and digital cards continue to function.
No action is required from the cardholder.

To prevent automatic renewal, set a custom `cardContractExpiryDate` when creating or [updating](../overview/guide-update.mdx) the card.
If the card expires without renewal, the status changes to `Canceled` and can no longer be used.

### Single-use virtual card expiry {#renewal-suv}

Single-use virtual cards aren't automatically renewed.

**One-off SUV cards** expire 30 days after creation (see [warning above](#suv-one-off)).
**Recurring SUV cards** expire after 3 years unless a custom `cardContractExpiryDate` is set.

When a recurring SUV card expires, the cardholder must create a new card and make the first payment to lock it to the merchant ID.
The new card then works with the same merchant for future transactions.

## Cancellation of virtual cards {#cancel}

Canceling a virtual card is an **irreversible action** that immediately and permanently invalidates the card.
Expand All @@ -96,8 +136,6 @@ When cancellation is complete, you're no longer billed for the card.

If you don't want to cancel the entire card contract, you can cancel just a [physical](../physical/guide-cancel.mdx) or [digital](../digital/guide-cancel.mdx) card instead.



You can cancel virtual cards [with the API](./guide-cancel.mdx).
If you use Swan's Web Banking interface, cardholders can [cancel (permanently block) their cards](https://support.swan.io/hc/en-150/articles/18538920070045-Block-your-card) independently.

Expand Down