Cards

Definition
Swan lets you issue Mastercard debit cards to all Account members. (Remember: the account administrator with the canManageMembers right can give multiple users rights to that account and those rights translate to an account membership.)
No matter how many members are attached to an account, 1, or 50, or 500, you can issue a debit card to each member. Any payments made with a card will debit the account the member is linked to.
So basically, if you have an account with 50 members, and have issued a card to each member, all 50 cards would give access to the same pot of money.
Depending on the nature of an Account Holder, whether an individual or a company, the cards are considered Debit Consumer or Debit Business, respectively.
In this case, John & Kimberly are both members of the same account: MyLittleCompany's. They each have a card, and any money they spend with those cards will be withdrawn from MyLittleCompany's account.
In this case, Ursula has an individual account with just one member: herself.
Our cards can be used everywhere Mastercard is available.
Card language
Your card's language (the language that will appear on payment terminals, for example) is usually the same as the language chosen for the Swan account.
No-code and open source: By default, Swan takes your browser's default language.
API: Swan account language unless otherwise communicated. You can update the default language by calling the bindAccountMembership mutation and adding accept-language to the HTTP header. This allows the users to choose their card language.
Digital First
While Swan offers a digital-first user experience, it's ultimately up to you what type of cards you'll issue: virtual, digital (Apple Pay or Google Pay), or physical.
Whenever you issue a new card, a virtual card number is instantly created that the Account member can already start using for e-commerce transactions. This new card can immediately go digital as well, through Apple Pay or Google Pay, letting account members easily start spending at physical sales points.
As for physical cards, Swan gives Account members the option to order a physical card. These are the good old plastic cards we are all familiar with. They can be used at sales points with any of the usual methods: swipe, chip + PIN code, or contactless.
In this case, Kafka Tamura received his virtual card instantly after ordering it. On day 2, he puts it in his smartphone and begins using it to pay for coffee and make payments at local businesses. On day 4, he puts it into his new smartwatch, too. On day 7, Kafka feels nostalgic for plastic cards and decides to order one of those.
Card design
Card design comes up several times during the account member's user experience. When ordering a physical card, and when consulting the web page that displays card numbers. If they're using Google Pay or ApplePay, it'll show up in their applications as well.
Swan proposes 2 standard card designs that have already been validated by Mastercard. You can personalize them with your brand and logo on the front side of the card. Just use our dashboard to upload your logo in SVG format (Learn more here). Once a standard card is ordered, the delivery delay is typically less than 7 days.
Black card personalizable with your logo in white monochrome:
Silver card is more like a grey gradient with a matte finish, personalizable with your logo in black monochrome:
Custom designs are possible too. Just send us a description of what you'd like: [email protected]
First, Mastercard will have to approve your design. After that, the delivery delay is about 16 weeks.
Card product
Swan lets you manage different card designs all within the same project. We define each card design by a card product ID. Each project has a default card product, that you can modify directly in the dashboard by clicking on the card. 
When you create a new card product, it will generate a new card product ID. 
Pick your style (Black, Silver or Custom), upload your logo, and decide whether to let your users order physical cards. When you're done, click Send to review and a person will review your design before publishing it.
You can suspend a card product at anytime. This doesn't impact existing cards, they will still be able to create virtual cards. But a suspended card will become unavailable to new users. To enable a card product that has been suspended, contact Swan support.
#nocode
If you're not a developer, you can stop reading here. Our interfaces will be enough for you to manage your cards. But if you're using the API, go ahead and keep reading!
Manage cards
Virtual cards are the first cards that you can issue with related status. Here is a schema describing the lifecycle of the virtual card.
Virtual card lifecycle
Add a card
You need to add account memberships before creating cards.
You can add a new card to an existing Account member by calling the addCard mutation. This mutation can only be called on behalf of an Account Member with the canManageAccountMembership rights. 
When you do this, make sure you are authentified with an accessToken using the name of the account member. The new card is thus created with the ConsentPending status and a consentUrl is returned which invites the user to start Strong Customer Authentication with Swan. Learn More. Once the Strong Customer Authentication process is finished, the new card changes to Activated status.
In the mutation, you can use cardProductId field which is optional. If don't use this field, the card will automatically be assigned as "Default". 
The card is automatically renewed before its expiry date. The default expiry date is three years after the order. But you can also configure a cardContractExpiryDate and we will renew every three years until we hit this date.
Add multiple cards
You can add multiple cards to multiple existing account members by calling the addCards mutation. It works nearly the same way as addCard with two additional features: 
you can order the physical card at the same time you add the virtual card: just fill the physicalCard field with the  delivery address
you can configure the spending limit while adding the card: the spendingLimit field is available directly, no need to update after creating the card.
When you do this, make sure you are authentified with an accessToken using the name of this account member. The new cards are thus created with ConsentPending status and a consentUrl is returned which invites the user to start Strong Customer Authentication with Swan. Learn More. Once the Strong Customer Authentication process is finished, the new cards change to Processing status.
The cards will be created asynchronously and then change to the Enabled status. Be aware that depending on how many cards you're creating, it can take up to several minutes to complete the process.
For performance reasons, bulk creation is limited to 250 cards per API call
Add multiple cards with group delivery
To ship a group of cards altogether, to the same address, you can use the addCardsWithGroupDelivery mutation. It works just like addCards, except all the cards will be sent together in one package. It's more cost-effective, and better for the planet!
Update a card
You can modify all card settings by calling the updateCard mutation.
cardContractExpiryDate:  null if you don't want to set an expiration date
If you don't set an expiration date, the card will be renewed automatically in three years.
international:  allow payments outside of the account holder's country
withdrawal: allow or disable cash withdrawals
nonMainCurrencyTransactions: allow or disable transactions outside of the card's currency
eCommerce: allow or disable transactions at eCommerce sites
monthlySpendingLimit: fixed by the member within the limits set by Swan
The difference between international and nonMainCurrencyTransactions is important. 
With international disabled, payments can only be made in the account holder's country, but you can still pay using other currencies (e.g. you are French and can pay in France using USD, but you can't make any payments outside of France).
With nonMainCurrencyTransactions disabled, payments can be made in other countries but not using other currencies (e.g. you are Italian and can pay using Euros in other countries like Germany, but cannot use any currency other than the Euro).
When you do this, make sure you are authentified with an accessToken using the name of the user behind the modification with the right canManageAccountMembership=true on the linked account. Learn More.
The request from this mutation returns a newly created consent resource containing the consentUrl. The url allows you to redirect the user making the modification to Swan's strong authentication. Learn more.
Once the consent process is completed, the card is updated and its attribute version is increased by 1.
Card settings are valid for all payments linked to this card, whether they were made with a virtual, physical, or digital card.
At the slightest suspicion of fraud, eCommerce=false allows the account member to temporarily block all e-commerce payments. The end client must then write to [email protected], after which Swan can renew the card number.
View card numbers
A user access token for the cardholder is required to view card numbers.
If information fails to become visible despite having the appropriate token and permissions, it may remain hidden due to regulatory restrictions based on your location.
The cardUrl available in the cardquery is for a website that displays the card with its design and its sensitive hidden information. We suggest you integrate it into your product in an iframe or a webview. This url is available 1 hour after you query it, then renew the query to get another cardUrl.
When the Account member wants to display sensitive information such as the card number, the CVC or the expiration date to make an eCommerce payment, you must call theviewCardNumbers mutation which returns a consent. When you do this, make sure you are authentified with an accessToken using the name of the card's account member. Then a consentUrl is returned which invites the user to start the Strong Customer Authentication with Swan. Learn More.
Once the consent has been accepted, the card's sensitive information is displayed for 5 minutes. The client can then click the number to copy it to their clipboard. After they are done with the card info, they can click on the Ok button and be redirected to the redirectUrl set up during the viewCardNumbers mutation.

To avoid repeating the Strong Customer Authentication each time the client wants to reveal the card number, the same consentUrl can be called anytime for 5 minutes after the consent. We advise you to store the consentId on your side and run a consent query to check the consent status is Accepted and the updateAt is less than 5 min, before reusing the consentUrl. The consentUrl will only work on the client's browser where the consent has already been done.
Cancel a card
To immediately and permanently cease usage of a card and no longer be billed for it you must call the cancelCard mutation. Each card associated to the virtual card will no longer be usable. The card's status will be Canceling  during the process and will change to Canceled once it is done.
To cancel only the physical card you must use cancelPhysicalCard .Learn more.
To cancel only a digital card you must use cancelDigitalCard   .Learn more.
Single use virtual cards
Single use virtual cards let you avoid 3DS consent during e-commerce payments as well as payments limited to a single merchant. Recurring payments (music/video streaming, AdWords, car payments...) are possible if the card's spending limits allow them.
Single use virtual cards can be either one-off or recurring.
One-off
One-off single use virtual cards, in theory, work one time for one transaction. It's not that simple, however, because some merchants send multiple authorizations for a single debit. Pre-authorization is a good example, as the merchant pre-authorizes an amount, and then a separate transaction is created for the actual debit.
Ideally, the card issuer (Swan Partners and sometimes your clients) should cancel one-off single use virtual cards after the expected debit has been used. Note that setting a spending limit is mandatory. Consider setting the expected debit amount as the spending limit, rendering the card unusable after that limit is reached.
For one-off cards, the AccountHolderSpendingLimit.period is Always.
Recurring
Recurring single use virtual cards could also be called single merchant virtual cards. The AccountHolderSpendingLimit.period is not Always.
When the card is used for the first time, Swan restricts the card to the merchant ID that triggered the authorization. If the card is used with the same merchant, the ID matches and the transaction can go through.
However, if the card holder tries to use the card elsewhere, the transaction will be rejected because the merchant IDs don't match.
Add a single use virtual card
You can add a new Single Use virtual card to an existing Account member by calling the addSingleUseVirtualCard mutation.
This mutation can be called on behalf of any Account Member with the canManageAccountMembership rights.
When you do this, make sure you are authentified with an accessToken using the name of this account member. The new card is thus created with the ConsentPending status and a consentUrl is returned which invites the user to start the Strong Customer Authentication with Swan. Learn More. Once the Strong Customer Authentication process is finished, the new card changes to Enabled status.
The Single Use Virtual Card is never renewed. It cannot be physically printed, nor used with Apple Pay and Google Pay.
If you wish to issue single-use virtual cards without having human interaction to consent and reveal card numbers, this is only possible for an account of which you are the holder (not available for your end customer for security and compliance reason) using server-to-server consent. Learn more. In this case, addSingleUseVirtualCard and addSingleUseVirtualCards, the AddSingleUseVirtualCardSuccessForProjectOwnerPayload will return a card in ConsentPending status. The card will be enabled after the consent is validated. We would still recommend that you verify the card status before using it
Physical cards
You can order a physical card for each virtual card created. Here is a schema describing the lifecycle of the physical card.
Physical card
Print a physical card
When an account member orders a card for the first time, you can get it printed for them by calling the printPhysicalCard mutation which returns a consent. When you do this, make sure you are authentified with an accessToken belonging to a member with the canManageAccountMembership access right on the account . Then a consentUrl is returned which invites the user to start Strong Customer Authentication with Swan. Learn More.
The card will be delivered to the account member within 72 hours. The delivery details are available in the PhysicalCardToActivateStatus object, with the estimated date of delivery in the estimatedDeliveryDatefield. The carrier and tracking number are available in the shippingProvider and trackingNumber. The card's status will be ToActivate until the card is activated.
By design, cards will be delivered in the letter below. If you prefer to use your own packaging please get in touch: [email protected]
Print a custom physical card
At Swan, we provide two ready-to-use designs: black and silver. If you want a custom design, your cards take about 16 weeks to be delivered instead of 10 days.
If you want custom text, such as your company name, on physical cards, follow the custom card process. There is a 26-character maximum for the additional line.
1.Contact us at [email protected]​
2.We will send you a tutorial and an Adobe Illustrator file that's ready to use.
3.Please respect the design provided as you customize the card.
1.The following elements cannot be changed: Mastercard logo, cardholder name, card number, identifier, expiry date, CVC, label debit/business, hologram, logo contactless, [email protected], "this card is issued by Swan..." and font "Maison Neue").
2.You are allowed to customize:
Chip color: gold or palladium
Card material: plastic, more or less recycled (we don't offer metal)
Note: You can choose PVC recycled at 86% or 100%. These options are shipped by boat to reduce the shipping carbon footprint, adding 12 weeks to delivery.
Apply one color to the whole card.
White or Black
Colors: 1795, 200, 1807, 208, 1665, 299, 285, 389, 369, 3405, 349, 113, 320, 805
Colors available for custom cards
Side color (adds 3 weeks to the wait; not compatible with gloss finish)
Quadri face printed front and back (avoid using the Mastercard logo colors; otherwise, the Mastercard logo will be outlined in white)
Matte or glossy finish
"Durable" ink embossed in white, black, silver, or gold.
Applied to the holder name, card number, expiry date, CVC, label debit/business, and identifier number.
4.You can also customize the mail design, packaging, and insert for the delivery. There are additional costs for this.
5.You'll have to decide how many cards to order for your first batch (a minimum applies). This is important because the factory can't start printing your design until they receive your stock of cards.
Send your design and order details to your Technical Account Manager. After we validate it with Mastercard, we can send it off for printing. The whole process from the time we receive your design to the time we receive samples and validate them takes about 16 weeks.
Activate a physical card
You can activate our physical cards either by making a first payment with the PIN code or by calling the activatePhysicalCard mutation which returns a consent. When you do this, make sure you are authentified with an accessToken using the name of the card's account member. Then a consentUrl is returned which invites the user to start the Strong Customer Authentication with Swan. Learn More.
View physical card number
If information fails to become visible despite having the appropriate permissions, it may remain hidden due to regulatory restrictions based on your location.
You can view the physical card number, which is different from the virtual card number, by calling the viewPhysicalCardNumbers mutation — in return, you'll get consent. When you do this, make sure you are authenticated with an accessToken using the name of the card's account member. Then a consentUrl is returned, inviting the user to start the Strong Customer Authentication with Swan. Learn More.
View PIN code
You can display the physical card's PIN by calling the viewPhysicalCardPINmutation which returns a consent. When you do this, make sure you are authentified with an accessToken using the name of the card's account member. Then a consentUrl is returned which invites the user to start the Strong Customer Authentication with Swan. Learn More.
Once the consent has been accepted, the PIN code is displayed for 5 minutes. After getting the PIN code, the user can click on the Ok button and he is redirected to the redirectUrl chosen during the PhysicalCardPIN mutation.
If your card was created before 5:00 p.m (Paris Time Zone). you can call the mutation starting from 5:30 p.m. that same day. Otherwise, you'll have to wait until the next day 5:30 p.m. to start calling the mutation. To help you out we have added the isPINReady boolean to the physical card'sstatusInfo, with ToActivate status. This is true when the PIN is available.
3 incorrect PIN attempts
If the account Member makes 3 incorrect PIN attempts, the physical card is suspended and no further payments can be made, neither online (e-commerce) nor at a physical sales point. Only payments through Apple Pay or Google Pay will continue to work. You can also continue using your virtual card for online payments.
Note that a physical card blocked for 3 incorrect PIN attempts will have the reason ‘IncorrectPinCodeAttemptsExceeded’ (on the PhysicalCardSuspendedStatusInfo)

You’ll have to wait 24 hours before being able to unlock the physical card.

After that delay, to unblock a physical card you must use the resumePhysicalCard mutation which returns a consent. When you do this, make sure you are authenticated with an accessToken using the name of the card’s account member. Then a consentUrl is returned which invites the user to start the Strong Customer Authentication with Swan. Learn More.

At that point, the physical card can be used again for online payments. To reactivate payments at a physical sales point, the user must also update the status of the card’s chip by using it at an ATM.
Temporarily lock a physical card
You can temporarily block a physical card with the suspendPhysicalCardmutation.
To unblock a physical card you must use the resumePhysicalCardmutation which returns a consent. When you do this, make sure you are authentified with an accessToken using the name of the card's account member. Then a consentUrl is returned which invites the user to start the Strong Customer Authentication with Swan. Learn More.
Renew a physical card
Cards are renewed automatically. About 1.5 months before the expiration date, the status of the physical card changes to Renewed with the delivery details available in the PhysicalCardRenewedStatus object, and its estimated date of delivery in the estimatedDeliveryDate field. You'll find the carrier and tracking number in the fields shippingProvider and trackingNumber as soon as they're available.
When a physical card is renewed, the card numbers change but the 4 digit PIN code remains the same to simplify the UX.
Cancel a physical card
When a card has been undelivered, lost, stolen or damaged, you must call the cancelPhysicalCardmutation by selecting the reason for cancellation.
Be careful, if the physical card has been lost or stolen, and if the client has already added the card to Apple Pay or Google Pay, don't forget to ask your client if their smartphone has been lost or stolen so that you can also delete these digital cards. Otherwise, the digital cards will continue to work. For some clients, this could be useful, if they still have their smartphone and wish to make payments while waiting for their new card to be delivered.
If you wish to send a new card to your client, just call the printPhysicalCard mutation again.
Apple Pay & Google Pay
We support Apple Pay and Google Pay. Here is a schema describing the lifecycle of the digital card.
Digital card lifecycle
Add a digital card to Apple Pay or Google Pay
There are 2 ways to provision digital cards in Apple Pay or Google Pay:
Push from Swan App: by calling the addDigitalCard mutation which returns a consent. When you do this, make sure you are authentified with an accessToken using the name of the card's account member. Then a consentUrl is returned which invites the user to start the Strong Customer Authentication with Swan app. Learn More.
Then the Swan app proposes adding the card to Apple Pay or Google Pay depending on the brand of the account member's smartphone.
Enter card numbers directly into Apple Pay or Google Pay: a client can go digital by entering their card number directly into Apple Pay or Google Pay.
The list of digital cards is available in the cards query.
Renew a digital card
Swan takes care of updating digital cards with Apple Pay and Google Pay. It's a clear advantage, as this requires no action from you nor your client.
Cancel a digital card
When you wish to instantly and permanently delete an Apple Pay or Google Pay digital card, you must use the cancelDigitalCard mutation.
Last modified 21h ago