For most use cases, we recommend using [Composable Drops](https://docs.moov.io/moovjs/drops/composable-drops/) instead of the card link Drop.

The card link Drop enables Moov customers to register a user's credit card in the most secure and seamless way possible.

With the `moov-card-link` element, credit card information is entered by the user and processed directly by Moov. The card link Drop interacts directly with the link a card `POST` [endpoint](https://docs.moov.io/api/sources/cards/create/) using JWTs to securely send data between your end users browser and Moov. All information is captured by an iframe and hidden from the customer's website.

## Card Capture

```html
<form>
  <moov-card-link></moov-card-link>
</form>

<script>
// Store a reference to the Moov Drop
const cardInput = document.querySelector('moov-card-link');

// Append required data to the Moov Drop
cardInput.oauthToken = "SERVER_GENERATED_TOKEN";
cardInput.accountID = "MOOV_ACCOUNT_ID";
cardInput.onSuccess = (result) => {
  /*
    Result is an object that contains the cardID. To advance to
    creating a transfer, send the cardID to your server-side
    integration to locate the generated paymentMethod to use
    in the transfer.
  */
  console.log(result);
};

// For example, submit the card data to Moov on form element submit
document.querySelector('form').addEventListener('submit', () => {
  cardInput.submit();
});
</script>
```

Moov Drops require a secure HTTPS connection. If you don't have a test environment with HTTPS enabled, we suggest setting up a hosting environment with ngrok, Netlify, or Vercel.

## Properties

Properties can be accessed through JavaScript using a reference to the `moov-card-link` element.

| Property                 | Type          | Description                                                                                                                                                                                                                                           |
|-------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `oauthToken`            | String        | Auth Token used for hitting the API. Token must include the `accounts/{accountID}/cards.write` scope.                                                                                                                                              |
| `accountID`             | String        | ID for the account you want to add cards to.                                                                                                                                                                                                        |
| `allowedCardBrands`     | String[]      | An array of allowed card brands. If this field is not provided, all card brands will be accepted. Accepted values are `visa`, `mastercard`, `american-express`, `diners-club`, `discover`, `jcb`, `unionpay`, `maestro`, `mir`, `elo`, `hiper`, or `hipercard`. |
| `holderName`            | String        | Optional value specifying the full name of the cardholder.                                                                                                                                                                                          |
| `billingAddress`        | Object        | Optional value for the billing address of the card. Follows the format specified in the [link card schema](https://docs.moov.io/api/sources/cards/create/). `postalCode` is required, `addressLine1` is highly recommended.                          |
| `cardOnFile`            | Boolean       | Optional. Indicates cardholder has authorized card to be stored for future payments.                                                                                                                                                               |
| `merchantAccountID`     | String        | Optional. Moov account ID of the merchant or entity authorized to store the card. Defaults to your platform account ID if `cardOnFile` is set to true and no other account is provided.                                                              |
| `validationEvent`       | String        | Controls the frequency of validation. Possible values are `submit`, `change`, `keydown`, or `none`.                                                                                                                                               |
| `inputStyle`            | Object        | CSS object to override styles within the iframe. CSS rule names should be camelCased.                                                                                                                                                               |
| `onEnterKeyPress`       | Function      | Callback fired when the enter key is pressed inside the iframe.                                                                                                                                                                                   |
| `onError`               | Function      | Callback fired when the submit fails or input is invalid. Provides `clientError` and `apiError` as arguments.                                                                                                                                     |
| `onValidated`           | Function      | Callback fired when input passes validation.                                                                                                                                                                                                         |
| `onSuccess`             | Function      | Callback fired when a card is registered successfully. Responds with a card which can be accessed in the function. See the link card [endpoint](https://docs.moov.io/api/sources/cards/create/#response) response for more detail.                       |

### How to set a property

```js
const cardInput = document.querySelector('moov-card-link');
cardInput.validationEvent = 'keydown';
```

```js
const cardInput = document.querySelector('moov-card-link');

const styles = {
  fontSize: "18.4px",
  fontFamily: "-apple-system, system-ui, 'Avenir Next'",
  paddingTop: "1px",
  "--text-color-invalid": "#FFB300",
};

cardInput.inputStyle = styles;
```

```js
const cardInput = document.querySelector('moov-card-link');

const successCallback = (card) => {
  // The card was successfully added
}

cardInput.onSuccess = successCallback;
```

```js
const cardInput = document.querySelector('moov-card-link');

const errorCallback = (clientError, apiError) => {
  // If there was an error adding the card,
  // clientError will provide a user-friendly error message
  if (clientError) {
    console.error(clientError);
  }
  // If there was an API error when adding the card,
  // apiError will provide a detailed error response
  if (apiError) {
    if (apiError.error) {
      // The Moov API returned a detailed, dev-friendly error message
      console.error("API error: ", apiError.error);
    }
    if (apiError.existingCardID) {
      // If the error was caused by a duplicate card,
      // The Moov API will return the existing card ID
      console.error("Existing card ID: ", apiError.existingCardID);
    }
  }
}

cardInput.onError = errorCallback;
```

## Methods

You can call the methods of `moov-card-link` to perform various actions.

| Method               | Description                                                          | Parameters | Returns |
|---------------------|----------------------------------------------------------------------|------------|---------|
| `submit`            | Attempts to register a new card using the current values.           | None       | None    |
| `clear`             | Clears out all user input.                                          | None       | None    |
| `validate`          | Triggers validation on the current values.                         | None       | None    |
| `fetchValidity`     | Runs validation asynchronously and resolves to true or false.       | None       | Promise |

### How to call a method

```js
const cardInput = document.querySelector('moov-card-link');
cardInput.submit();
// Use onSuccess and onError for the result
```

```js
const cardInput = document.querySelector('moov-card-link');
cardInput.validate();
// Use onValidated and onError for the result
```

```js
const cardInput = document.querySelector('moov-card-link');
const validityPromise = cardInput.fetchValidity();
validityPromise.then(isValid => {
  // Do something based on isValid
});
```

## Attributes

String-type properties can be set via attributes on the HTML `<moov-card-link>` element.

| Attribute               | Description                                                              |
|------------------------|--------------------------------------------------------------------------|
| `oauth-token`          | Auth Token used for hitting the API. Token must include the `accounts/{accountID}/cards.write` scope. |
| `account-id`           | ID for the account you want to add cards to.                             |
| `validation-event`     | Controls the frequency of validation. Possible values are `submit`, `change`, `keydown`, or `none`. |
| `merchant-account-id`  | Moov account ID of the merchant or entity authorized to store the card. Defaults to your platform account ID if `cardOnFile` is set to true and no other account is provided. |

## Scopes

To link a card, your Moov API token must include the `accounts/{accountID}/cards.write` scope.

## Theming

Read our [themes](https://docs.moov.io/moovjs/drops/theming/) guide to learn how to re-style Moov Drops.

To re-style the inner contents of the card link, use the `inputStyle` property.