Guide
API
PROCESS
Issue cards
Debit cards provided by Swan can be virtual, physical or digital, and they are all customizable to your needs.
Configure your card design
Before creating cards you need to personalize their design. You can use our card design studio to get a 3D preview of how your card will look. Once you are satisfied you can replicate that design on the dashboard in the Cards tab. This design will be used everywhere; not just for the physical card but also when you display sensitive card information or provide alternative payment methods such as Apple Pay, Google Pay, etc...
How to configure your card design
Once you click on Save the card is instantly available from the sandbox environment. If you want to make changes to your card design in the Live environment, you must click Start the review and we will manually review your design before publishing it.
Instantly create a virtual card
Once your card design is configured, you can start issuing in real-time. Virtual cards are usable instantly upon creation. With a simple API call, you can provide a card to the user that they can use online and via Apple Pay or Google Pay.
To add a card to their account via the web banking, a user must go to Members, select the member, and click on Add a card. After consenting, the virtual card is created and usable immediately. To do the same through the API, use the
addCard mutation. This mutation used the accountMembershipId as an identifier. To get it you need to use the following query.Request
Response
1
query MyQuery {
2
accountMemberships {
3
edges {
4
node {
5
id
6
}
7
}
8
}
9
}
Copied!
1
{
2
"data": {
3
"accountMemberships": {
4
"edges": [
5
{
6
"node": {
7
"id": "4a279443-7e3d-4103-9ce5-b2e6889aa68e"
8
}
9
}
10
]
11
}
12
}
13
}
Copied!
Once you have this ID, call the
addCard mutation. Replace {{YOUR_ACCOUNTMEMBERSHIP_ID}} with the last ID you obtained and {{YOUR_REDIRECT_URL}} with the URL you want to redirect the user to.Request
Response
1
mutation MyMutation {
2
addCard(
3
input: {
4
accountMembershipId: "{{YOUR_ACCOUNTMEMBERSHIP_ID}}"
5
withdrawal: true
6
international: true
7
nonMainCurrencyTransactions: true
8
eCommerce: true
9
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
10
name: "My First Swan Card"
11
}
12
) {
13
... on AddCardSuccessPayload {
14
__typename
15
card {
16
statusInfo {
17
... on CardConsentPendingStatusInfo {
18
__typename
19
consent {
20
consentUrl
21
}
22
}
23
}
24
id
25
}
26
}
27
}
28
}
29
Copied!
1
{
2
"data": {
3
"addCard": {
4
"__typename": "AddCardSuccessPayload",
5
"card": {
6
"statusInfo": {
7
"__typename": "CardConsentPendingStatusInfo",
8
"consent": {
9
"consentUrl": "https://identity.swan.io/consent?consentId=dc5baae6-3832-4025-83b5-aa65b70195ee&env=Sandbox"
10
}
11
},
12
"id": "07d11c66-9f1c-49a5-98c3-771a1d3d6920"
13
}
14
}
15
}
16
}
Copied!
As this is a sensitive operation we ask the user's consent before issuing the card. You have to redirect them to the
consentUrl so that they can give their approval. Once consent is given, the card is created.
Here's what a new card looks like on the Web Banking
Get card information
To make online payments you usually need to provide the card number, the expiration date, and the CVC. All of this data is considered sensitive and is not directly available through the web banking interface or the API. To display this info to the end-user, call the mutation
viewCardNumbers. The web banking uses this mutation when the Reveal card numbers button is clicked on.Replace
{{YOUR_CARD_ID}} with the last ID obtained and {{YOUR_REDIRECT_URL}} with the URL you want to redirect the user to.Request
Response
1
mutation MyMutation {
2
viewCardNumbers(input: { cardId: "{{YOUR_CARD_ID}}", consentRedirectUrl: "{{YOUR_REDIRECT_URL}}" }) {
3
... on ViewCardNumbersSuccessPayload {
4
__typename
5
consent {
6
consentUrl
7
id
8
}
9
}
10
}
11
}
Copied!
1
{
2
"data": {
3
"viewCardNumbers": {
4
"__typename": "ViewCardNumbersSuccessPayload",
5
"consent": {
6
"consentUrl": "CONSENT_URL",
7
"id": "CONSENT_ID"
8
}
9
}
10
}
11
}
Copied!
You need to open a native pop-up to display the
consentUrl .This URL will redirect the user to a page with the card numbers displayed with the card design.
Here's the pop-up that displays sensitive card info
Go digital: Apple Pay & Google Pay
Both physical and virtual cards can be added to a wallet and used instantly. There are multiple ways to add cards to a wallet (Apple or Google):
- 1.The end-user can do it themselves by entering the card number into the application
- 2.The end-user can use Swan App and follow the in-app provisioning process
- 3.You can initiate the in-app provisioning process through the addDigitalCard mutation
The end result is the same so you can choose whatever solution suits you best.
Replace
{{YOUR_CARD_ID}} and {{YOUR_REDIRECT_URL}} with the URL you want to redirect the user to.Request
Response
1
mutation MyMutation {
2
addDigitalCard(
3
input: {
4
cardId: "{{YOUR_CARD_ID}}"
5
walletProvider: ApplePay
6
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
7
}
8
) {
9
... on AddDigitalCardSuccessPayload {
10
__typename
11
digitalCard {
12
id
13
statusInfo {
14
... on DigitalCardConsentPendingStatusInfo {
15
__typename
16
consent {
17
consentUrl
18
}
19
}
20
}
21
}
22
}
23
}
24
}
Copied!
1
{
2
"data": {
3
"addDigitalCard": {
4
"__typename": "AddDigitalCardSuccessPayload",
5
"digitalCard": {
6
"id": "988aae40-710b-4258-9d7d-827a55c4efda",
7
"statusInfo": {
8
"__typename": "DigitalCardConsentPendingStatusInfo",
9
"consent": {
10
"consentUrl": "https://identity.swan.io/consent?consentId=25b225e3-35bf-4307-8984-5e867d107f3b&env=Sandbox"
11
}
12
}
13
}
14
}
15
}
16
}
Copied!
Beware that you should only use the walletProvider
alletproviderwalletProvider corresponding to the user Authenticator. Use GooglePay for Android and ApplePay for iOS.To simulate the end of the process in sandbox, use the Event Simulator > Finalize in-App provisioning using the
digitalCard.id you got with the addDigitalCard mutation. Use the other tab (Manual Provisioning) to simulate a user adding a card manually to Google Pay or Apple Pay.Order a physical card
To order a good old plastic card, use the API or the web banking interface. Just provide a delivery address and we'll take care of the rest. On the web banking interface, select the card and click on Order now. Then choose the address where you want to send the card.
Choose between a default address or add another one
The card will arrive 3-4 days after ordering. If you want to do the same thing via the API, use the
printPhysicalCard mutation. Replace {{YOUR_CARD_ID}} and {{YOUR_REDIRECT_URL}} with the URL you want to redirect the user to.Request
Response
1
mutation MyMutation {
2
printPhysicalCard(
3
input: {
4
cardId: "{{YOUR_CARD_ID}}"
5
address: { addressLine1: "10 Rue de la Paix ", city: "Paris", postalCode: "75000", country: "FRA" }
6
choosePINCode: false
7
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
8
}
9
) {
10
... on PrintPhysicalCardSuccessPayload {
11
__typename
12
physicalCard {
13
statusInfo {
14
... on PhysicalCardConsentPendingStatusInfo {
15
__typename
16
consent {
17
consentUrl
18
}
19
}
20
}
21
}
22
}
23
}
24
}
Copied!
1
{
2
"data": {
3
"printPhysicalCard": {
4
"__typename": "PrintPhysicalCardSuccessPayload",
5
"physicalCard": {
6
"statusInfo": {
7
"__typename": "PhysicalCardConsentPendingStatusInfo",
8
"consent": {
9
"consentUrl": "https://identity.swan.io/consent?consentId=a0986e45-78e7-424c-8151-3b85e29e1049&env=Sandbox"
10
}
11
}
12
}
13
}
14
}
15
}
Copied!
The
choosePINCode variable is planned for the future and should be set as false for the moment. Choosing a pin code is a sensitive operation, and we need the user to consent to it.To activate the physical card, you must make a payment using the pin code. This pin code is accessible both on the web banking interface or via the API through the
viewPhysicalCardPin mutation.Replace
{{YOUR_CARD_ID}} and {{YOUR_REDIRECT_URL}} with the URL you want to redirect the user to.Request
Response
1
mutation MyMutation {
2
viewPhysicalCardPin(input: { cardId: "{{YOUR_CARD_ID}}", consentRedirectUrl: "{{YOUR_REDIRECT_URL}}" }) {
3
... on ViewPhysicalCardPinSuccessPayload {
4
__typename
5
consent {
6
consentUrl
7
}
8
}
9
... on PINNotReadyRejection {
10
__typename
11
message
12
physicalCardIdentifier
13
}
14
}
15
}
16
Copied!
1
{
2
"data": {
3
"viewPhysicalCardPin": {
4
"__typename": "ViewPhysicalCardPinSuccessPayload",
5
"consent": {
6
"consentUrl": "https://identity.swan.io/consent?consentId=fc0f89bc-b94d-4e4d-bd7d-9f38ad0f3c31&env=Sandbox"
7
}
8
}
9
}
10
}
Copied!
A pin code is highly sensitive data, therefore we require the user to consent to the operation. After consenting, they are redirected to a white-labeled Swan page displaying the pin code.
To activate a physical Card a user must make a payment using their pin code. Only then can they use contactless, add the card to a wallet, pay online, etc. In the future, you will be able to activate a physical card using the
activatePhysicalCard mutation.Configure your card
There are multiple settings that you can configure on a card, you can find them all on the card documentation. Those settings can be changed by the web banking interface or the API.
The Card settings page lets you select which operations are allowed
As this is a sensitive operation we will ask for user consent.
To obtain the same result using the API use the
updateCard mutation. Replace {{YOUR_CARD_ID}} and {{YOUR_REDIRECT_URL}} with the URL you want to redirect the user to.Request
Response
1
mutation MyMutation {
2
updateCard(
3
input: {
4
cardId: "{{YOUR_CARD_ID}}"
5
withdrawal: false
6
international: false
7
nonMainCurrencyTransactions: false
8
eCommerce: false
9
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
10
}
11
) {
12
... on UpdateCardSuccessPayload {
13
__typename
14
consent {
15
consentUrl
16
id
17
}
18
}
19
}
20
}
21
Copied!
1
{
2
"data": {
3
"updateCard": {
4
"__typename": "UpdateCardSuccessPayload",
5
"consent": {
6
"consentUrl": "https://identity.swan.io/consent?consentId=eaeeca20-02cd-4b5f-8e7b-107d4cca7307&env=Sandbox",
7
"id": "eaeeca20-02cd-4b5f-8e7b-107d4cca7307"
8
}
9
}
10
}
11
}
Copied!
Next steps
Now that you know how to issue cards we highly recommend you read this in-depth article about cards.
Last modified 5mo ago