Skip to main content

Physical cards

Plastic payment card that can be used for point-of-sale transactions using swipe, chip and PIN, and contactless (EMV) methods, as well as for online transactions.

You can order a physical card for each virtual card. Swan physical cards are typical plastic cards that can be used for swipe, chip and PIN, contactless, and online transactions. Your design will be printed on all physical cards.

Name printed on card​

The name printed on Swan cards corresponds to a cardholder's legal name, as recorded for their Swan account.

The length of the printed name (first name + last name) can't exceed 20 characters. If your cardholder's name is longer than 20 characters, the initial of their first name is used instead of their full first name. If the first initial + last name combination still exceeds 20 characters, their first name plus last initial is used instead.

Abbreviation example
  • The name Emilia Prommenschenkel would be abbreviated to E. Prommenschenkel.
  • The name Mikah Ottovordemgentschenfelde would be abbreviated to Mikah O..

Additional line​

You can print an additional line of text on your physical cards. For example, you might want to include the company name on your cards. To print an additional line, add the physicalCardCustomOptions > additionalPrintedLine field to any mutation used to print cards.

For standard cards, the additional line is printed above the card number. If you're designing a custom card, you can choose to print it below the card number.

Number plates​

You can use number plates instead of cardholder names if it's logical for your use case. For example, when cards stay with a vehicle and are used exclusively to purchase fuel, number plates make sense.

Please discuss this option with your Technical Account Manager. If your use case is approved, your Technical Account Manager can activate the feature for you. Then, to use number plates instead of names, add the physicalCardCustomOptions > customCardHolderName field to any mutation used to print cards.

Card number​

Each physical card has a unique card number, different even from the virtual card added before the physical card was printed.

Swan makes the physical card's number, CVC, expiry date, and the PIN available in Web Banking. The card number, CVC, and PIN are considered sensitive data and must be masked by default. The cardholder must complete a consent request before the numbers can be unmasked.

Virtual and physical card numbers

Why do virtual and physical cards have different card numbers and CVCs? The two card types function as independent entities. Each has its own transaction history, can be added to the same digital wallet, and more.

This also means that if a cardholder loses their physical card, they can suspend or cancel the physical card without losing access to their virtual card.

PIN (Personal Identification Number)​

Physical cards have a four-digit PIN, or Personal Identification Number. A card's PIN is chosen or assigned when the card is printed. After a PIN is chosen or assigned, it can't be changed.

The PIN for each physical card is available to the cardholder on Swan's Web Banking interface. PINs aren't available on your Dashboard because only the cardholder should have easy access to the PIN for their card.

If a cardholder forgets their PIN, they can view it on your interface. If needed, you can use the ViewPhysicalCardPin mutation to view the numbers yourself, which requires a user access token associated with the cardholder. Note that if three incorrect attempts are made to enter the PIN, the card is automatically Suspended.

caution

If a cardholder shares their PIN, Swan can't take responsibility for fraud associated with that card.

Choosing a card's PIN​

To allow your cardholders to choose their PIN, set the choosePin paramater to true when printing physical cards. You can set this paramater with the printPhysicalCard and addCards mutations.

If you don't add the choosePin paramater, or you set it to false, Swan assigns a PIN randomly. A card's PIN can't be changed.

You can print a physical card for another account member with the addCard mutation, allowing the member cardholder to choose their PIN by setting the choosePin paramater to true. Swan sends a text message to the member cardholder's mobile number used for Swan containing a link to choose their PIN.

Alternatively, you can use the addCard mutation to add only the virtual card. Then, the cardholder can request their own physical card and choose their PIN.

PIN availability​

You can view a card's PIN as soon as it's assigned during the printing process.

  • If you print a physical card before 17:00 CET/CEST (Central European [Summer] Time), the card's PIN is available by the end of the day.
  • If you print a physical card after 17:00 CET/CEST, the card's PIN is available by the end of the following day.
  • If you allow your cardholder to choose their PIN (choosePin is true), add an additional 24-hour delay.
Day & time

Days are measured as business days. Time is expressed with the 24-hour clock.

Incorrect PIN attempts​

If the cardholder enters their PIN incorrectly three times, the physical card will be blocked (status: suspended) and no payments with the physical card can be made online or in person.

Note that a physical card blocked for three incorrect PIN attempts will have the reason IncorrectPinCodeAttemptsExceeded (on the PhysicalCardSuspendedStatusInfo). You'll have to wait 24 hours before being able to unblock the physical card.

You can continue to use both virtual and digital cards while the physical card is temporarily blocked.

Printing and shipping hubs​

Delivery time for physical cards depends on the type of card material you select and your cardholders' location. It typically takes 2-5 business days for cards to be delivered. Please note that the delivery times listed here are estimates and aren't contractual.

Swan has two printing hubs: one in France and the other in Spain. France is Swan's default hub. To choose the Spain hub, tell your Technical Account Manager and they'll configure it.

Two card products

The printing hub is defined in the card product ID. If you'd like to ship cards out of both hubs, you need two card products: one with France as the hub, and the other with Spain.

If your cardholder reports not receiving their physical card, please refer them to the Swan Support Center.

🇫🇷 France hub​

The France hub prints and ships out of Dijon, France, and ships using either La Poste (France's postal service) or DHL. The hub has several intended destinations:

  • France
  • Italy
  • Northern Europe
  • French overseas departments and territories (DROM-COM):
    • French Southern Territories (ATF), Saint Barthélemy (BLM), Faroe Islands (FRO), Guadeloupe (GLP), French Guiana (GUF), Saint Martin (Dutch part) (MAF), Martinique (MTQ), Mayotte (MYT), New Caledonia (NCL), French Polynesia (PYF), Réunion (REU), Saint Pierre and Miquelon (SPM), and Wallis and Futuna (WLF)

You have the option of group or non-group delivery.

Delivery typeDestinationShipping provider
Group deliveryAll locationsDHL
Tracked non-group deliveryFrance and DROM-COMLa Poste
Tracked non-group deliveryNorthern Europe and unlisted locationsDHL
Untracked non-group deliveryNorthern Europe and unlisted locationsLa Poste

🇪🇸 Spain hub​

The Spain hub prints and ships out of Madrid, Spain, and ships using either Correos (Spain's postal service) or Nacex. The hub has two intended destinations:

  • Spain
  • Portugal

You have the option of group or non-group delivery.

Delivery typeDestinationShipping provider
Group deliverySpain and PortugalNacex ∗
Tracked non-group deliverySpain and PortugalCorreos

∗ If you choose the Spain hub but ship using group delivery outside of Spain or Portugal, the shipping provider is DHL.

Physical card statuses​

renewal statuses

The statuses ToRenew and Renewed don't appear in the status diagram intentionally. Refer to the card renewal statuses to understand how they interact with the main physical card statuses.

Physical card statusExplanation
InitiatedPrinting a physical was launched with either the printPhysicalCard or addCards with physical card mutation.
ConsentPendingRequest to print a physical card was received and is waiting for the cardholder's consent.

Next steps:
  • If you used the addCards mutation and the cardholder consents, the status moves to Processing.
  • If you used the printPhysicalCard mutation and the cardholder consents, the status moves to Activated.
  • If you cancel the card with the API before consent, the status moves to Canceling.
  • If consent is refused or consent fails, the status moves directly to Canceled.
ProcessingThe card is in the process of being created with Swan's card issuing provider.

Next steps:
  • After the card is created successfully in the card issuing provider's system, the status moves to ToActivate.
  • If you cancel the card with the API before the card issuing provider creates the card, the status moves to Canceling.
ToActivateThe card is being printed by Swan's card issuing provider, then delivered to the cardholder.

After the cardholder receives the physical card, they need to activate it by performing a first transaction and entering the PIN. You can also activate the card with the activatePhysicalCard mutation.

Next steps:
  • If the cardholder performs the transaction successfully, or you activate the card with the API, the status moves to Activated.
  • If the cardholder makes three incorrect attempts to enter their PIN, the status moves to Suspended.
ActivatedPhysical card is available for use.

Next steps:
  • Cards can retain the status Activated until the renewal period.
  • Activated cards can also be Suspended and Canceled (example: if three incorrect attempts are made to enter the PIN, the card is automatically Suspended).
Suspended

Also referred to as Blocked		Physical card is suspended and not available for use. Cardholders can still view card information and use digital cards (not virtual cards) when a physical card is Suspended.

Cards can be suspended for various reasons, including a request from you or the cardholder, or a Swan action in the case of suspicious activity.

Next steps:
  • Restore the card's previous status with the API.
  • Cancel the card with the API.
CancelingCard is in the process of being canceled.

Next steps: Card is Canceled. After a card is assigned the Canceling status, the process can't be reversed.
CanceledCard is canceled, no longer available for use, and can't be reactivated.

Renewing physical cards​

Physical cards are renewed automatically before the expiry date. By default, cards expire three years after the card is printed, and are renewed for an additional three years.

When a physical card is renewed, the card numbers, CVV, identifier, and expiry date change. The four-digit PIN doesn't change for a continuous user experience. If your user prefers to choose their PIN, they need to cancel the expiring card and order a new one. It's not possible to choose a new PIN during renewal.

Subscriptions​

After the new card is enabled, Swan uses Mastercard's Account Billing Updater to update the details about the tokenized card. If a merchant adheres to Mastercard's Account Billing Updater, they receive the tokenized card's updated details automatically through this service.

Therefore, certain existing subscriptions can be transferred to the new card without any action from the cardholder.

Card delivery​

New physical cards are shipped between the eleventh and fifteenth of the month before the card expires. For example, if the card expires on the last day of March, the new card ships between February 11-15 of the same year.

Delivery details are available in the PhysicalCardRenewedStatus object. The estimated delivery date can be found in the estimatedDeliveryDate field. You'll find the carrier and tracking number in the fields shippingProvider and trackingNumber as soon as they're available.

Verify delivery address​

10 weeks before the original card expires, verify the delivery address with your cardholder.

No update provided

If Swan doesn't receive updated address information at least 8 weeks before the card renews, the renewed card is shipped to the same address as the original card.

InterfaceAddress update method
Swan's Web Banking appCardholders confirm or update their address in the app at least 8 weeks before renewal.
Custom integrationSend the updated address to Swan at least 8 weeks before the card renews.

  1. First, provide a way for your cardholders to verify their address. For example, this could be from your app, with a notification system, or through your own support team.
  2. Then, send Swan the updated address with the API by calling the confirmPhysicalCardRenewal mutation.

Card renewal statuses​

Two statuses exist that only apply to physical card renewal: ToRenew and Renewed.

This diagram illustrates how the two renewal statuses interact with the main physical card statuses. Note that renewal statuses are only accessed from the statuses ToActivate and Activated.

Card renewal statusExplanation
ToRenewStatus triggered automatically 10 weeks before the card's expiry date. After this status is triggered by the Swan API, you can't stop the renewal process.

If you or the cardholder doesn't want to renew a physical card, cancel the card at least 11 weeks before the expiry date.
RenewedStatus triggered automatically 8 weeks before the card's expiry date. No updates to the delivery address can be made after this status is triggered.

Activating the new card​

After the cardholder makes an in-person transaction with the new card using the Chip and PIN payment method, the new card's status changes from Renewed to Activated. You could also use the API.

The old card is then marked isExpired=true because only one card can be activated at a time. Details about expired physical cards are available in the card query (card > physicalCard > previousPhysicalCards).

Guides​