# Card Management Web SDK

`Version 1.0`

For [Issuing](https://www.checkout.com/docs/card-issuing.md), you can integrate the `CheckoutCardManagement` Web SDK to display sensitive card details to your cardholders from your website or web application, and to let them activate, suspend, or revoke their cards.

---

## Before you start

- Make sure you have a [test account](https://www.checkout.com/get-test-account) with Checkout.com.
- You must have started [Issuing onboarding](https://www.checkout.com/docs/card-issuing/set-up-card-program.md) and received your client credentials.
- Contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes) and request your domain to be allowlisted so that you can use the SDK's functionality.
- Create a [public key](https://www.checkout.com/docs/resources/api-authentication/api-keys.md) in the [Dashboard](https://dashboard.checkout.com), with the default key scopes.

---

## How it works

1. Import the SDK.
2. Initialize the SDK.
3. Set up Strong Customer Authentication (SCA).
4. Retrieve the cardholder's cards, and display their credentials.
5. Optionally, activate, suspend, or revoke a card.
6. Optionally, customize the user interface.

> **Information**
>
> If you have integration questions or issues, contact your issuing representative or [issuing_operations@checkout.com](mailto:issuing_operations@checkout.com).

To authenticate your requests, use the client credentials you receive as part of your Issuing onboarding.
You must provide valid `tokens` in your requests, which our back-end services serve securely.

---

## Import the SDK

Import the SDK into your website or web application. Use the SDK that matches the environment you want to use.

**Production**

```html
<script src="https://issuing-web-sdk.checkout.com/v1/index.js"></script>
```

**Sandbox**

```html
<script src="https://issuing-web-sdk.cko-sbox.ckotech.co/v1/index.js"></script>
```

---

## Initialize the SDK

Initialize the SDK with your public API key.

```typescript
const sdk = new window.CheckoutCardManagement(<PUBLIC_API_KEY>);
```

---

## Display card credentials

Use the `mountCardCredentials()` method to display card credentials in your website or web application.

```javascript
await sdk.mountCardCredentials(
  'element_id',
  {
    cardId: 'cardId',
    expiryDate: {
      expiryMonth: '<MM>', // For example '01' for January
      expiryYear: '<YYYY>', // For example, '2026'
    },
  },
  'singleUseToken',
)
```

---

## Customize the user interface

Use the `appearance` object to customize the user interface that displays the card credentials. For example, you can override the default styles for the card number, card verification value (CVV), and expiry date.

To see a full list of appearance options, refer to the SDK's type definition.

```javascript
await sdk.mountCardCredentials(
  'element_id',
  {
    cardId: 'cardId',
    expiryDate: {
      expiryMonth: '<MM>', // For example '01' for January
      expiryYear: '<YYYY>', // For example, '2026'
    },
  },
  'singleUseToken',
  'appearance': {
    colorTextValue: '#000',
    colorTextLabel: '#FFF',
    colorIcon: "red"
  }
);
```

If your website or web application is built with Typescript, you can add the Issuing SDK types to the `global.d.ts` file.

```typescript
declare global {
 interface MountCardCredentialsResult {
   /** The mounted iframe element */
   iframe: HTMLIFrameElement;
   /** Programmatically unmount the iframe */
   unmount: () => void;
 }


 interface CardCredentialsAppearance {
   layout?: string;
   colorTextLabel?: string;
   colorTextValue?: string;
   colorLoading?: string;
   colorIcon?: string;
   colorFocus?: string;
   colorHover?: string;
   value?: {
     fontFamily?: string;
     fontSize?: string;
     fontWeight?: number;
     letterSpacing?: number;
     lineHeight?: string;
   };
   label?: {
     fontFamily?: string;
     fontSize?: string;
     fontWeight?: number;
     letterSpacing?: number;
     lineHeight?: string;
   };


   /**
    * Remove the copy button from all fields.
    * @default false
    */
   removeCopyButton?: boolean;
 }


 type CardStatus = 'active' | 'inactive' | 'suspended' | 'revoked';


 interface Card {
   id: string;
   last4: string;
   status: CardStatus;
   /** Two digits, for example '01' for January */
   expiryMonth: string;
   /** Four digits, for example '2029' */
   expiryYear: string;
 }


 interface Window {
   CheckoutCardManagement: {
     new (clientPublicKey: string): {
       mountCardCredentials(
         elementId: string,
         card: {
           cardId: string;
           expiryDate: { expiryMonth: string; expiryYear: string };
         },
         singleUseToken: string,
         appearance?: CardCredentialsAppearance,
       ): Promise<MountCardCredentialsResult>;

       getCards(
         cardholderId: string,
         token: string,
         options?: { statuses: CardStatus[] },
       ): Promise<{ cards: Card[] }>;

       getCardDetails(
         cardId: string,
         token: string,
       ): Promise<{ card: Card }>;

       activateCard(
         cardId: string,
         token: string,
       ): Promise<{ cardId: string; status: 'active'; activatedAt: string }>;

       suspendCard(
         cardId: string,
         token: string,
         options?: { reason: 'suspected_lost' | 'suspected_stolen' },
       ): Promise<{
         cardId: string;
         status: 'suspended';
         suspendedAt: string;
         reason: string;
       }>;

       revokeCard(
         cardId: string,
         token: string,
         options?: {
           reason: 'expired' | 'reported_lost' | 'reported_stolen';
         },
       ): Promise<{
         cardId: string;
         status: 'revoked';
         revokedAt: string;
         reason: string;
       }>;
     };
   };
 }
}
```

---

## SDK events

The SDK emits the following events:

| Function | Description |
| --- | --- |
| `checkout:cardCredentialsError` | Emitted when the SDK encounters an error due to any of the following scenarios:<br><br>- A browser setting or active extension blocked the iframe.<br>- The `elementId` specified during initialization could not be found in the DOM.<br>- Card credentials are already mounted and a second attempt to mount them is made.<br>- The card credentials fail to load due to an invalid or expired single-use token. |
| `checkout:cardCredentialsReady` | Emitted when the card credentials have been loaded to your website or web application and are ready to be displayed. |
| `checkout:cardCredentialsUnmounted` | Emitted when 30 seconds have passed since the credentials were mounted successfully and the SDK unmounts the iframe from the DOM. |
| `checkout:cardNumberCopied` | Emitted when the button to copy the card number is selected.<br><br>You can use this event to determine when to display a toast or success message on your website or web application. |
| `checkout:cvvCopied` | Emitted when the button to copy the card's CVV is selected.<br><br>You can use this event to determine when to display a toast or success message on your website or web application. |
| `checkout:expiryCopied` | Emitted when the button to copy the card's expiry date is selected.<br><br>You can use this event to determine when to display a toast or success message on your website or web application. |

---

## SDK functions

The SDK provides the following functions.

Every function except `mountCardCredentials()` returns a promise that rejects with an error object containing a `code` and a `message`. For the codes each function can return, see [Handle errors](#Handle_errors).

| Function | Description |
| --- | --- |
| `getCards(`<br>`  'cardholderId': string,`<br>`  'token': string,`<br>`  'options'?: {`<br>`    'statuses': Array<`<br>`      'active' \| 'inactive' \|`<br>`      'suspended' \| 'revoked'>;`<br>`  },`<br>`)` | Retrieves the cards belonging to the cardholder specified by `cardholderId`, which must be prefixed with `crh_`. Authorize the request with a cardholder access token.<br><br>The `options` object is optional. If you provide it, `statuses` must be a non-empty array. If no cards match, the function resolves with an empty `cards` array.<br><br>For an example, see [Display card details](https://www.checkout.com/docs/card-issuing/manage-cards/display-card-details.md#Display_card_details_on_your_website). |
| `getCardDetails(`<br>`  'cardId': string,`<br>`  'token': string,`<br>`)` | Retrieves the non-sensitive details of the card specified by `cardId`, which must be prefixed with `crd_`. Authorize the request with a cardholder access token.<br><br>The function resolves with the card's last four digits, status, and expiry date. It returns `expiryMonth` and `expiryYear` as strings, so you can pass the card straight to `mountCardCredentials()`. |
| `mountCardCredentials(`<br>`  'elementId': string,`<br>`    'card': {`<br>`      'cardId': string;`<br>`      'expiryDate': { `<br>`        'expiryMonth': string; `<br>`        'expiryYear': string };`<br>`    },`<br>`    'singleUseToken': string,`<br>`    'appearance'?: CardCredentialsAppearance,`<br>`)` | Mounts an iframe to the element specified by `elementId`. Authorize the request with a single-use token, not a cardholder access token.<br><br>If the iframe is mounted successfully, the SDK displays the card credentials for 30 seconds. After this period of time, the SDK sends a `cardCredentialsUnmounted` event and removes the iframe from the DOM.<br><br>If the iframe is not mounted successfully, the SDK sends a `cardCredentialsError` event. Handle the error gracefully to ensure a smooth user experience. |
| `activateCard(`<br>`  'cardId': string,`<br>`  'token': string,`<br>`)` | Activates the card specified by `cardId`. Authorize the request with a cardholder access token.<br><br>The function resolves with the card's ID, its `active` status, and an `activatedAt` timestamp. Use it to reactivate a suspended card as well as to activate a new one.<br><br>For an example, see [Activate a card](https://www.checkout.com/docs/card-issuing/activate-a-card.md#Activate_a_card_on_your_website). |
| `suspendCard(`<br>`  'cardId': string,`<br>`  'token': string,`<br>`  'options'?: {`<br>`    'reason':`<br>`      'suspected_lost' \|`<br>`      'suspected_stolen';`<br>`  },`<br>`)` | Suspends the card specified by `cardId`. Authorize the request with a cardholder access token.<br><br>The `options` object is optional. If you provide it, you must also provide a `reason`.<br><br>The function resolves with the card's ID, its `suspended` status, a `suspendedAt` timestamp, and the reason.<br><br>For an example, see [Suspend a card](https://www.checkout.com/docs/card-issuing/manage-cards/suspend-a-card.md#Suspend_a_card_on_your_website). |
| `revokeCard(`<br>`  'cardId': string,`<br>`  'token': string,`<br>`  'options'?: {`<br>`    'reason':`<br>`      'expired' \|`<br>`      'reported_lost' \|`<br>`      'reported_stolen';`<br>`  },`<br>`)` | Revokes the card specified by `cardId`. Authorize the request with a cardholder access token.<br><br>The `options` object is optional. If you provide it, you must also provide a `reason`. The revoke reasons differ from the suspend reasons.<br><br>The function resolves with the card's ID, its `revoked` status, a `revokedAt` timestamp, and the reason.<br><br>Revocation is permanent, and the SDK provides no function to reverse it.<br><br>For an example, see [Revoke a card](https://www.checkout.com/docs/card-issuing/manage-cards/revoke-a-card.md#Revoke_a_card_on_your_website). |

---

## Handle errors

The functions that call our API reject with an error object containing a `code` and a `message`. Focus on the `code` value, because the `message` value can change.

| Code | Description |
| --- | --- |
| `API_ERROR` | The API returned an error that no other code covers. |
| `AUTHENTICATION_FAILED` | The API rejected the token. Complete a new SCA flow and request a new token. |
| `CARDHOLDER_NOT_FOUND` | The token has no access to a cardholder with the `cardholderId` you provided. |
| `CARD_NOT_FOUND` | The token has no access to a card with the `cardId` you provided. |
| `INVALID_CARDHOLDER_ID` | The `cardholderId` is missing, or lacks the `crh_` prefix. |
| `INVALID_CARD_ID` | The `cardId` is missing, or lacks the `crd_` prefix. |
| `INVALID_CARD_STATE` | The card's current status prevents the change. For example, the card you want to activate is already active or revoked. |
| `INVALID_REASON` | The `reason` is missing, or belongs to a different function. `suspendCard()` and `revokeCard()` each accept their own set of reasons. |
| `INVALID_RESPONSE` | The SDK received a response it could not parse. |
| `INVALID_STATUSES` | The `statuses` array is missing, empty, or contains an unrecognized value. |
| `INVALID_TOKEN` | The token is missing or malformed. |
| `NETWORK_ERROR` | The request did not complete, so the outcome is unknown.<br><br>For `activateCard()`, `suspendCard()`, and `revokeCard()`, the change might still have been applied. Call `getCardDetails()` to confirm the card's status before you retry. |
| `RATE_LIMITED` | You have sent too many requests. Back off, then retry. |
| `SERVICE_UNAVAILABLE` | The API is temporarily unavailable. |

`mountCardCredentials()` reports failures differently. Instead of rejecting with one of these codes, it sends a `checkout:cardCredentialsError` event. For more information, see [SDK events](#SDK_events).

---

## Set up Strong Customer Authentication

While Checkout.com handles in-depth compliance, you are responsible for performing [Strong Customer Authentication (SCA)](https://www.checkout.com/docs/business-operations/ensure-regulatory-compliance/sca-compliance.md) on your cardholders for every session where they use functionality provided by the SDK.
This applies to both the sandbox and production environments.

Once the SCA flow is complete, request a token from your authentication back end and pass it to the SDK. The SDK uses two types of token:

- Cardholder access token – Authorizes every function except `mountCardCredentials()`. Pass it as the `token` parameter.
- Single-use token – Authorizes `mountCardCredentials()` only. You can generate one single-use token for each SCA flow you request.

You can generate multiple tokens for different systems during a single authentication session.
For example, to sign in, to get a single-use token, and to get an internal authentication token.