Card - Swan

Search…
Card
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.
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. 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 8 weeks.
#nocode
If you're not a developer, you can stop reading here. You'll be able to manage your cards with the web interfaces we provide you. If you're using the API, go ahead and keep reading.
Manage cards
Virtual cards are the first cards that you can issue. Here is a schema describing the lifecycle of the virtual card.
Virtual card lifecycle
Add a card
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.
The card is automatically renewed before its expiry date. The default expiry date is three years after the order. If you configured a cardContractExpiryDate 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 200 cards per API call
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
international :  permit payments outside of the 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
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
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.
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.
Add Single Use Virtual Cards
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.
To add Single Use Virtual Cards with a project access token, please contact us: [email protected]​
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 lifecycle
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.
At that point, the Account member chooses their physical card's 4 digit PIN code. If a PIN code has not been chosen, we will automatically generate one after 24 hours.
Once the PIN code is known in our system, 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 as sos on as they're available. 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]
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 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. 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.
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.
You'll then have to wait 24 hours before the physical card can be used again.
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 1d ago