From 6ee62400ba510cdc7a27b7ee47b910e230e75855 Mon Sep 17 00:00:00 2001 From: Maxence Busson Date: Tue, 6 Jan 2026 12:14:32 +0100 Subject: [PATCH 1/2] DOC-597/enrich-the-suvc-section --- docs/topics/cards/index.mdx | 16 ++++++++++- docs/topics/cards/virtual/index.mdx | 42 +++++++++++++++++++++++++++-- 2 files changed, 55 insertions(+), 3 deletions(-) diff --git a/docs/topics/cards/index.mdx b/docs/topics/cards/index.mdx index 64ea948d2e5..234f9e1c400 100644 --- a/docs/topics/cards/index.mdx +++ b/docs/topics/cards/index.mdx @@ -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.

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.

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 | @@ -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**. diff --git a/docs/topics/cards/virtual/index.mdx b/docs/topics/cards/virtual/index.mdx index cc455199e20..b7a4c2cdaa9 100644 --- a/docs/topics/cards/virtual/index.mdx +++ b/docs/topics/cards/virtual/index.mdx @@ -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. @@ -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. @@ -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. From 117b3d2ce219d5c0415d7308d465e52c9ec3f525 Mon Sep 17 00:00:00 2001 From: Maxence Busson Date: Tue, 6 Jan 2026 12:21:37 +0100 Subject: [PATCH 2/2] Update index.mdx --- docs/topics/cards/virtual/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/cards/virtual/index.mdx b/docs/topics/cards/virtual/index.mdx index b7a4c2cdaa9..eec0fdc8b59 100644 --- a/docs/topics/cards/virtual/index.mdx +++ b/docs/topics/cards/virtual/index.mdx @@ -114,7 +114,7 @@ Standard virtual cards are renewed automatically unless a custom `cardContractEx 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. +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}