Skip to main content
@qonto/embed-sdk / cards

​
Variable: cards

const cards: object = cardsNamespace.cards
The cards namespace contains all the functions related to card operations. It can be accessed like this: 
import { cards } from '@qonto/embed-sdk/cards';
Then, the cards object contains the functions to perform card operations: 
await cards.displayCard(/* params here */);
await cards.getCards();
await cards.orderCard(/* params here */);
await cards.unlockCard(/* params here */);

​
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.

​
Parameters

cardConfig
CardParams<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 proxyRequestFunction (recommended for production to avoid exposing tokens), accessToken, stagingToken, and other properties. See OperationSettings for details.

​
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, if the cardId is not provided or not a string, or if any parameter validation fails.

​
Throws

AuthenticationError If both proxyRequestFunction 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.

​
Parameters

getCardParams
CardParams<{ cardId: string; }> An object containing:
  • cardSettings: An object with the cardId property (string).
  • operationSettings: An object with operation-level settings such as proxyRequestFunction (preferred over using the access token flow), accessToken, stagingToken, and other optional parameters. See CardParams.

​
Returns

Promise<Card> A promise that resolves to a card.

​
Throws

InvalidParametersError If the cardId is not provided, not a string, or if any parameter validation fails.

​
Throws

AuthenticationError If both the proxyRequestFunction and accessToken are invalid or missing within operationSettings.

​
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.

​
Parameters

getCardsParams?
CardParams<{ membershipId: string; }> An object with optional parameters:
  • cardSettings: An object that can contain the optional membershipId property.
  • operationSettings: An object with operation-level settings such as proxyRequestFunction (preferred over using the access token flow), accessToken, stagingToken, and other optional parameters. See OperationSettings for more details. If the membershipId parameter is passed, the function will return the cards that belong to the specified membership only. If the accessToken is not provided, the function will use the token previously passed to the initialize function. The stagingToken is optional, but it has to be passed to use the SDK in staging environments (it will be ignored in production).

​
Returns

Promise<Card[]> A promise that resolves to an array of cards.

​
Throws

AuthenticationError If both the proxyRequestFunction and accessToken are invalid or missing within operationSettings.

​
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. 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
CardParams<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. See OperationSettings for details.

​
Returns

Promise<Card> A promise that resolves to an object representing the ordered card.

​
Throws

InvalidParametersError If uiParentElementId is missing, if the card settings are invalid, or if any parameter validation fails.

​
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',
      'it_and_electronics',
      'utility',
      'tax',
      'legal_and_accounting',
      'atm', 'office_supply',
      'hardware_and_equipment',
      'finance'
    ],
    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',
      'it_and_electronics',
      'utility',
      'tax',
      'legal_and_accounting',
      'atm', 'office_supply',
      'hardware_and_equipment',
      'finance'
    ],
    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. 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
CardParams<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. See OperationSettings for details.

​
Returns

Promise<Card> A promise that resolves to an object representing the unlocked card.

​
Throws

InvalidParametersError If uiParentElementId is missing, if the cardId is not provided or not a string, or if any parameter validation fails.

​
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);