> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cards

[@qonto/embed-sdk](../README) / 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:

```ts theme={null}
import { cards } from '@qonto/embed-sdk/cards';
```

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

```ts theme={null}
// 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`](../-internal-/interfaces/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`](../-internal-/interfaces/CardClientParamsWithUI)\<[`DisplayCardSettings`](../-internal-/interfaces/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`](../-internal-/interfaces/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`](../interfaces/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`](../-internal-/interfaces/ClientOperationSettings)

#### Returns

`Promise`\<[`Card`](../interfaces/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`](../interfaces/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`](../-internal-/interfaces/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`](../interfaces/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`](../interfaces/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`](../-internal-/interfaces/CardClientParamsWithUI)\<[`CardOrderSettings`](../type-aliases/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`](../interfaces/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

```ts theme={null}
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);
```

```ts theme={null}
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`](../interfaces/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`](../-internal-/interfaces/CardClientParamsWithUI)\<[`UnlockCardSettings`](../-internal-/interfaces/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`](../interfaces/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

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