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

# Vault – Web

## Introduction

The Mangopay Vault SDK allows you to securely tokenize an end user’s payment card for use in your application. A tokenized card is a virtual and secure version of the card that can be used for payment.

It is very highly recommended that you use the Mangopay Vault SDK, rather than integrating the API endpoints directly. By doing so, you:

* Avoid sensitive card details transiting your system
* Benefit from PCI-DSS compliance
* Receive ongoing support and updates

<Info>
  To use the Mangopay Vault SDK, you’ll need:

  * A Mangopay `ClientId` and API key (get a Sandbox API key for free)
  * A User to register the card for (see Testing - Payment methods for test cards)
</Info>

## Installation

You can install the Mangopay Vault SDK using npm or yarn.

```shell Install with npm theme={null}
npm install --save @mangopay/vault-sdk
```

```shell Install with Yarn theme={null}
yarn add @mangopay/vault-sdk
```

## Creating the Card Registration

In your backend, create the Card Registration via the Mangopay API, using the `Id` of the user as the `UserId` .

You must also define the currency and type of the card at this stage.

```json theme={null}
{
    "Tag": "Created with the Mangopay Vault SDK",
    "UserId": "193020185",
    "CardType": "CB_VISA_MASTERCARD",
    "Currency": "EUR"
}
```

```json API response theme={null}
{
    "Id": "193020188",
    "Tag": null,
    "CreationDate": 1686147148,
    "UserId": "193020185",
    "AccessKey": "1X0m87dmM2LiwFgxPLBJ",
    "PreregistrationData": "XBDYiG8w9PrylPS01KmupZunmK2QRHKIC-yUF6il3aIpAnKba1TGkR9VJe5lHjHt2ddFLVXdicolcUIkv_kKEA",
    "RegistrationData": null,
    "CardId": null,
    "CardType": "CB_VISA_MASTERCARD",
    "CardRegistrationURL": "https://pci.sandbox.mangopay.com/api/mangopay/vault/tokenize/eyJjbGllbnQiOiJjbGllbnRJZCIsInRva2VuIjoidW5xaXVlVG9rZW4ifQ==",
    "ResultCode": null,
    "ResultMessage": null,
    "Currency": "EUR",
    "Status": "CREATED"
}
```

The data obtained in the response will be used in the `preregistrationData` defined below.

## Initializing the SDK

Initialize the SDK with your `ClientId` and select your environment (Sandbox or Production).

```javascript Initialization theme={null}
import { MangopayVault } from '@mangopay/vault-sdk';

const options = {
  clientId: 'your-mangopay-client-id',
  environment: 'SANDBOX | PRODUCTION',
};

const vault = MangopayVault.initialize(options);
```

## Providing data for tokenization

The SDK requires the following information to tokenize the card:

* The end user’s card details (`cardInfoObject`) entered on the payment page (see Testing - Payment methods for test cards)
* The Card Registration data (`preregistrationData`) previously returned by the Mangopay API

### cardInfoObject

<table>
  <thead>
    <tr>
      <th class="header">Property</th>
      <th class="header">Type</th>
      <th class="header">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">`cardNumber `</td>
      <td class="table-content">string</td>
      <td class="table-content">The card number to be tokenized, without any separators.</td>
    </tr>

    <tr>
      <td class="table-content">`cardExpirationDate `</td>
      <td class="table-content">string (Format: “MMYY”)</td>
      <td class="table-content">The expiration date of the card.</td>
    </tr>

    <tr>
      <td class="table-content">`cardCvx `</td>
      <td class="table-content">string</td>
      <td class="table-content">The card verification code (on the back of the card, usually 3 digits).</td>
    </tr>
  </tbody>
</table>

### preregistrationData

<table>
  <thead>
    <tr>
      <th class="header">Property</th>
      <th class="header">Type</th>
      <th class="header">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">`Id `</td>
      <td class="table-content">string</td>
      <td class="table-content">The unique identifier of the Card Registration object.</td>
    </tr>

    <tr>
      <td class="table-content">`CardRegistrationURL`</td>
      <td class="table-content">string</td>
      <td class="table-content">The URL to which the card details are sent to be tokenized.</td>
    </tr>

    <tr>
      <td class="table-content">`AccessKey `</td>
      <td class="table-content">string</td>
      <td class="table-content">The secure value used when tokenizing the card.</td>
    </tr>

    <tr>
      <td class="table-content">`PreregistrationData`</td>
      <td class="table-content">string</td>
      <td class="table-content">A specific value passed to the `CardRegistrationURL`.</td>
    </tr>

    <tr>
      <td class="table-content">`errors`</td>
      <td class="table-content">MgpTypedError</td>
      <td class="table-content">A generic type describing the [error report](https://mangopay.com/docs/errors/error-report) that is returned in case of an error.</td>
    </tr>
  </tbody>
</table>

```javascript Data for tokenization theme={null}
const cardInfoObject = {
  cardNumber: '4970107111111119',
  cardExpirationDate: '1127',
  cardCvx: '123',
};

const preregistrationData = {
  id: createCardRegistrationResult.Id,
  cardRegistrationURL: createCardRegistrationResult.CardRegistrationURL,
  accessKeyRef: createCardRegistrationResult.AccessKey,
  data: createCardRegistrationResult.PreregistrationData,
};
```

## Tokenizing the card

You can now tokenize the card with the card data obtained previously using the frontend SDK.

The SDK automatically updates the Card Registration object to provide you with a `CardId` that can be used for payments.

```javascript tokenizePaymentMethod theme={null}
const tokenizePaymentMethodResult = await vault.tokenizePaymentMethod(cardInfoObject, preregistrationData);
```

```json tokenizePaymentMethodResult theme={null}
{
  "AccessKey": "1X0m87dmM2LiwFgxPLBJ",
  "CardId": "193441306",
  "CardRegistrationURL": "https://pci.sandbox.mangopay.com/api/mangopay/vault/tokenize/eyJjbGllbnQiOiJjbGllbnRJZCIsInRva2VuIjoidW5xaXVlVG9rZW4ifQ==",
  "CardType": "CB_VISA_MASTERCARD",
  "CreationDate": 1686643376,
  "Currency": "EUR",
  "Id": "193440893",
  "PreregistrationData": "_nfGWK2M2AY-H3lgOikqrLj8AggrYxTmIT6E0-gC3pi_kanrlI9ECtUTFz9bpEPj2ddFLVXdicolcUIkv_kKEA",
  "RegistrationData": "data=acIcnwwLleiAvlZUea5VxRdiKSkTpQi9C_4mwMDZj2dVqeVp2t5Ale0bTDDR67xRZV7S6MnMEyJzhjosylCjNfKlVqHrO6v9_p3mEzQNSjd6qFPuWUQSA1IhgrZj4v4eNx0xgKTVnyDj15oG8jR88g",
  "ResultCode": "000000",
  "ResultMessage": "Success",
  "Status": "VALIDATED",
  "Tag": null,
  "UserId": "193020185"
}
```

<table>
  <thead>
    <tr>
      <th class="header">Property</th>
      <th class="header">Type</th>
      <th class="header">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">`AccessKey `</td>
      <td class="table-content">string</td>
      <td class="table-content">The secure value used when tokenizing the card.</td>
    </tr>

    <tr>
      <td class="table-content">`CardId `</td>
      <td class="table-content">string</td>
      <td class="table-content">The unique identifier of the Card object.</td>
    </tr>

    <tr>
      <td class="table-content">`CardRegistrationURL`</td>
      <td class="table-content">string</td>
      <td class="table-content">The URL to which the card details are sent to be tokenized.</td>
    </tr>

    <tr>
      <td class="table-content">`CardType`</td>
      <td class="table-content">string</td>
      <td class="table-content">The type of the card.</td>
    </tr>

    <tr>
      <td class="table-content">`CreationDate`</td>
      <td class="table-content">timestamp</td>
      <td class="table-content">The date and time at which the object was created.</td>
    </tr>

    <tr>
      <td class="table-content">`Currency`</td>
      <td class="table-content">string</td>
      <td class="table-content">The currency of the card.</td>
    </tr>

    <tr>
      <td class="table-content">`Id`</td>
      <td class="table-content">string</td>
      <td class="table-content">The unique identifier of the Card Registration object.</td>
    </tr>

    <tr>
      <td class="table-content">`PreregistrationData`</td>
      <td class="table-content">string</td>
      <td class="table-content">A specific value passed to the `CardRegistrationURL`.</td>
    </tr>

    <tr>
      <td class="table-content">`RegistrationData`</td>
      <td class="table-content">string</td>
      <td class="table-content">The string returned by the tokenization server after tokenizing the card.</td>
    </tr>

    <tr>
      <td class="table-content">`ResultCode`</td>
      <td class="table-content">string</td>
      <td class="table-content">The code indicating the result of the operation. This information is mostly used to [handle errors](https://mangopay.com/docs/errors/error-codes) or for filtering purposes.</td>
    </tr>

    <tr>
      <td class="table-content">`ResultMessage`</td>
      <td class="table-content">string</td>
      <td class="table-content">The explanation of the result code.</td>
    </tr>

    <tr>
      <td class="table-content">`Status`</td>
      <td class="table-content">string</td>

      <td class="table-content">
        The status of the card registration:

        * **CREATED** – The card registration has been created, but no `RegistrationData` has been entered yet and the `CardId` value is `null`.
        * **VALIDATED** – The card registration has been successfully updated with the `RegistrationData` from the tokenization server.
        * **ERROR** – The card registration couldn’t be updated with the `RegistrationData` and no `CardId` was generated. For more information, refer to the `ResultCode` (<a href="/errors/codes/105206">105206</a>, <a href="/errors/codes/105299">105299</a>) and `ResultMessage`.
      </td>
    </tr>

    <tr>
      <td class="table-content">`Tag`</td>
      <td class="table-content">string</td>

      <td class="table-content">
        Custom data that can be added to this object.

        In the case of the Card Registration, this parameter can be used to facilitate the link between the User object and its equivalent on your platform for instance. This value will be inherited by the Card object `Tag` parameter and will not be editable.
      </td>
    </tr>

    <tr>
      <td class="table-content">`UserId`</td>
      <td class="table-content">string</td>
      <td class="table-content">The unique identifier of the user the card belongs to.</td>
    </tr>

    <tr>
      <td class="table-content">errors\`</td>
      <td class="table-content">MgpTypedError</td>
      <td class="table-content">A generic type describing the [error report](https://mangopay.com/docs/errors/error-report) that is returned in case of an error.</td>
    </tr>
  </tbody>
</table>

## Managing cards

You can use the following endpoints to manage cards:

* View a Card provides key information about the card, including its Fingerprint which can be used as an anti-fraud tool
* Deactivate a Card allows you to irreversibly set the card as inactive

<Warning>
  **Warning – End user's approval needed to save card details**

  Under no circumstances should card information be kept without the end user's approval. \
  If you don’t have the end user’s approval, you need to deactivate the card systematically after use in your implementation.
</Warning>

## Making card payments

You can use a registered card (`CardId`) for pay-ins with the following objects:

* The Direct Card PayIn object, for one-shot card payments
* The Recurring PayIn Registration object, for recurring card payments
* The Preauthorization object, for 7-day preauthorized card payments
* The Deposit Preauthorization object, for 30-day preauthorized card payments

<Warning>
  **Caution – Card validation within 24 hours**

  A successful transaction (preauthorization, pay-in, or recurring) within 24 hours of the card registration is required to validate a card. Otherwise, the card remains invalid and a new card registration will be necessary to make a payment.
</Warning>

## Related resources

<CardGroup col={2}>
  <Card title="Guide" href="/guides/payment-methods">Learn about all supported payment methods</Card>

  <Card title="Testing" href="/testing/payment-methods">Learn more about testing all payment methods</Card>
</CardGroup>