Cards

@qonto/embed-sdk / cards

Variable: cards

const cards: object

The cards namespace contains all the client-side functions related to card operations. It is designed for browser environments.

• getCards and getCard use proxy-based authentication and require proxyEndpointDescriptor.
• displayCard supports both proxyEndpointDescriptor (recommended) and accessToken.
• orderCard and unlockCard use access token-based authentication via an iframe.

For server-side operations using access tokens, import from '@qonto/embed-sdk/server/cards'.

It can be accessed like this:

import { cards } from '@qonto/embed-sdk/cards';

Then, the cards object contains the functions to perform card operations:

// Fetch cards (requires proxyEndpointDescriptor)
await cards.getCards({
  operationSettings: { proxyEndpointDescriptor }
});

// Get a specific card
await cards.getCard({
  cardSettings: { cardId: '...' },
  operationSettings: { proxyEndpointDescriptor }
});

// UI operations (client-only)
await cards.displayCard({
  cardSettings: { cardId: '...' },
  operationSettings: { proxyEndpointDescriptor, uiParentElementId: 'element-id' }
});

await cards.orderCard({
  cardSettings: { ... },
  operationSettings: { accessToken, uiParentElementId: 'element-id' }
});

await cards.unlockCard({
  cardSettings: { cardId: '...' },
  operationSettings: { accessToken, uiParentElementId: 'element-id' }
});

Type declaration

displayCard()

displayCard: (cardConfig) => Promise<DisplayCardReturnObject>

Displays a Cards UI in the calling page which allows the user to see card details and perform some operations (client-side only).

This function is only available in client-side environments as it requires UI rendering. It supports both proxy-based and access token-based authentication.

Parameters

cardConfig

CardClientParamsWithUI<DisplayCardSettings>

An object containing:

• cardSettings: An object with the cardId property (string).
• operationSettings: Required settings to configure this operation. Must include uiParentElementId to specify where the UI will be rendered. Also supports proxyEndpointDescriptor (recommended for production to avoid exposing tokens), accessToken, stagingToken, and other properties.

Returns

Promise<DisplayCardReturnObject>

A promise that resolves to an object with a destroyEmbedUI function. When calling this function, the UI will be removed from the DOM.

Throws

InvalidParametersError If uiParentElementId is missing or if the cardId is not provided or not a string.

Throws

AuthenticationError If both proxyEndpointDescriptor and accessToken are invalid or missing.

Throws

EmbedApiError If the API request fails or returns an error.

getCard()

getCard: (getCardParams) => Promise<Card>

Fetches a card by its id (client-side version).

This function uses proxy-based authentication and is designed for browser environments. It requires proxyEndpointDescriptor in operationSettings.

Parameters

getCardParams

An object containing:

• cardSettings: An object with the cardId property (string).
• operationSettings: An object with proxyEndpointDescriptor (required), stagingToken, and other optional parameters.

cardSettings

{ cardId: string; }

cardSettings.cardId

string

operationSettings?

ClientOperationSettings

Returns

Promise<Card>

A promise that resolves to a card.

Throws

InvalidParametersError If the cardId is not provided, not a string, or if proxyEndpointDescriptor is not provided.

Throws

EmbedApiError If the API request fails or returns an error.

getCards()

getCards: (getCardsParams?) => Promise<Card[]>

Fetches the list of cards for the current user (client-side version).

This function uses proxy-based authentication and is designed for browser environments. It requires proxyEndpointDescriptor in operationSettings.

Parameters

getCardsParams?

CardClientParams<{ membershipId: string; }>

An object with optional parameters:

• cardSettings: An object that can contain the optional membershipId property.
• operationSettings: An object with proxyEndpointDescriptor (required), stagingToken, and other optional parameters.

Returns

Promise<Card[]>

A promise that resolves to an array of cards.

Throws

InvalidParametersError If proxyEndpointDescriptor is not provided, or if membershipId is invalid.

Throws

EmbedApiError If the API request fails or returns an error.

orderCard()

orderCard: (cardConfig) => Promise<Card>

Requests the creation of a card by showing the user the UI to perform MFA in the calling page (client-side only).

This function is only available in client-side environments as it requires UI rendering. It will show an element on the screen where users will be able to go through the MFA authentication process and upon successful authentication, will perform the ordering operation.

Parameters

cardConfig

CardClientParamsWithUI<CardOrderSettings>

An object containing:

• cardSettings: An object with the card order parameters (see examples below).
• operationSettings: Required settings to configure this operation. Must include uiParentElementId to specify where the UI will be rendered. Also supports accessToken, stagingToken, mfaPreference, debugMode, and other properties.

Returns

Promise<Card>

A promise that resolves to an object representing the ordered card.

Throws

InvalidParametersError If uiParentElementId is missing or if the card settings are invalid.

Throws

AuthenticationError If the accessToken is invalid or missing.

Throws

EmbedApiError If the API request fails or returns an error.

Examples

const cardConfig = {
  cardSettings: {
    categories: ['transport', 'restaurant_and_bar', 'food_and_grocery'],
    membershipId: 'membership-id',
    cardLevel: 'standard', // Other options are 'plus' or 'metal'
    cardDesign: 'standard.recycled.plastic.2023',
    typeOfPrint: 'print',
    hasAtmOption: true,
    hasNfcOption: true,
    onlineOption: true,
    foreignOption: true,
    monthlyLimit: 1300,
    atmMonthlyLimit: 1000,
    hasAtmDailyLimit: true,
    atmDailyLimit: 100,
    hasDailyLimit: true,
    dailyLimit: 100,
    paymentTransactionLimit: 1000,
    hasTransactionLimit: true,
    activeDays: [1, 2, 3, 4, 5], // From Monday to Friday
    shipToBusiness: true,
  },
  operationSettings: {
    uiParentElementId: 'dom-element-id',
  },
};
orderCard(cardConfig);

const cardConfig = {
  cardSettings: {
    categories: ['transport', 'restaurant_and_bar', 'food_and_grocery'],
    membershipId: 'membership-id',
    cardLevel: 'virtual',
    monthlyLimit: 1300,
    dailyLimit: 100,
    paymentTransactionLimit: 1000,
    hasTransactionLimit: true,
    activeDays: [1, 2, 3, 4, 5], // From Monday to Friday
  },
  operationSettings: {
    uiParentElementId: 'dom-element-id',
  },
};
orderCard(cardConfig);

unlockCard()

unlockCard: (cardConfig) => Promise<Card>

Unlocks a locked card by showing the user the UI to perform MFA in the calling page (client-side only).

This function is only available in client-side environments as it requires UI rendering. It will show an element on the screen where users will be able to go through the MFA authentication process and upon successful authentication, will perform the unlock operation.

Parameters

cardConfig

CardClientParamsWithUI<UnlockCardSettings>

An object containing:

• cardSettings: An object with the cardId property (string).
• operationSettings: Required settings to configure this operation. Must include uiParentElementId to specify where the UI will be rendered. Also supports accessToken, stagingToken, mfaPreference, debugMode, and other properties.

Returns

Promise<Card>

A promise that resolves to an object representing the unlocked card.

Throws

InvalidParametersError If uiParentElementId is missing or if the cardId is not provided or not a string.

Throws

AuthenticationError If the accessToken is invalid or missing.

Throws

EmbedApiError If the API request fails or returns an error.

Example

const cardConfig = {
  cardSettings: {
    cardId: 'card-id',
  },
  operationSettings: {
    uiParentElementId: 'dom-element-id',
  },
};
const unlockedCard = await unlockCard(cardConfig);