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.
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
physicalCardfield with the delivery address - you can configure the spending limit while adding the card: the
spendingLimitfield 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:nullif you don't want to set an expiration dateinternational: 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.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 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.You can add a new Single Use virtual card to an existing Account member by calling the
addSingleUseVirtualCard mutation.This type of card lets 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.
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 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]
.png?alt=media&token=898478ba-4058-42f5-8ecd-0e503b36d138)
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.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
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.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
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.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
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.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
addDigitalCardmutation which returns aconsent. When you do this, make sure you are authentified with anaccessTokenusing the name of the card's account member. Then aconsentUrlis 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 1mo ago