Ask Moov Beta
Generative AI is experimental and can make mistakes.
Guides Use cases API Changelog
  1. Moov.js
  2. Moov Drops

Card link Moov Drop

For most use cases, we recommend using 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 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.

<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>
Drops 101

Learn the basics of properties, attributes, & initializing Drops.
Composable Moov Drops

For more control over the design and layout, check out how to compose Moov Drops.
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. postalCode is required, addressLine1 is highly recommended. Supplying a postalCode will update the zip input field accordingly.
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 response for more detail.

How to set a property 

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

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;

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

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

cardInput.onSuccess = successCallback;

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 

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

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

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 guide to learn how to re-style Moov Drops.

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