Cards
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.
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.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 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.
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.
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!
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
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.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
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!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 countrywithdrawal
: allow or disable cash withdrawalsnonMainCurrencyTransactions
: allow or disable transactions outside of the card's currencyeCommerce
: allow or disable transactions at eCommerce sitesmonthlySpendingLimit
: 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.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 card
query 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 the
viewCardNumbers
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.
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 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 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 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.
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 itYou can order a physical card for each virtual card created. Here is a schema describing the lifecycle of the physical card.

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 estimatedDeliveryDate
field. 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]
.png?alt=media&token=898478ba-4058-42f5-8ecd-0e503b36d138)
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.
- 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, 805Colors 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.
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.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.You can display the physical card's PIN by calling the
viewPhysicalCardPIN
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 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.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.You can temporarily block a physical card with the
suspendPhysicalCard
mutation.To unblock a physical card you must use the
resumePhysicalCard
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.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.
When a card has been undelivered, lost, stolen or damaged, you must call the
cancelPhysicalCard
mutation 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.We support Apple Pay and Google Pay. Here is a schema describing the lifecycle of the digital card.

Digital card lifecycle
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 aconsent
. When you do this, make sure you are authentified with anaccessToken
using the name of the card's account member. Then aconsentUrl
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.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.
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