CardOnFileComponentConfig

View the reference for the CardOnFileComponentConfig file.

Reference

import CardOnFileComponentConfig from "@pxpio/web-components-sdk/components/cardOnFileComponents/cardOnFileComponent";

const cardOnFileConfig: CardOnFileComponentConfig = {
  limitTokens: number,
  filterBy: {
    excludeExpiredTokens: boolean,
    schemes: string[],
    fundingSource: string,
    issuerCountryCode: string,
    ownerType: string
  },
  orderBy: {
    expiryDate: string,
    scheme: string,
    fundingSource: string,
    ownerType: string,
    issuerCountryCode: string,
    lastUsageDate: {
      orderByField: string
    }
  },
  cardBrandImages: {
    visaSrc: string,
    mastercardSrc: string,
    amexSrc: string,
    cupSrc: string,
    dinersSrc: string,
    discoverSrc: string,
    jcbSrc: string
  },
  expiredText: string,
  validThruText: string,
  deleteModal: {
    dialogAriaLabel: string,
    bodyText: string,
    cancelButtonText: string,
    deleteButtonText: string,
    class: string
  },
  deleteErrorMessage: string,
  deleteSuccessMessage: string,
  updateErrorMessage: string,
  updateSuccessMessage: string,
  successMessageClass: string,
  errorMessageClass: string,
  isExpiryDateEditable: boolean,
  isCvcRequired: boolean,
  allowDeleteToken: boolean,
  cvcComponentConfig: CardCvcComponentConfig,
  expiryDateComponentConfig: CardExpiryDateComponentConfig,
  styles: CSSProperties,
  iconDeleteSrc: string,
  iconSaveSrc: string,
  iconCancelSrc: string,
  iconEditSrc: string,
  inputStyles: CSSProperties,
  tokenItemClass: string,
  useTransparentCardBrandImage: boolean,
  editCardInformationAriaLabel: string,
  saveCardInformationAriaLabel: string,
  cancelEditCardInformationAriaLabel: string,
  deleteCardButtonAriaLabel: string,
  cardNumberAriaLabel: string,
  cardExpiryDateAriaLabel: string,
  onPreRenderTokens: (data: RetrieveCardTokensReponseSuccess) => CardTokenMapping[],
  onRetrieveTokensFailed: (data: RetrieveCardTokensReponseFailed) => void,
  onDeleteTokenSuccess: (data: DeleteCardTokenResponseSuccess) => void,
  onDeleteTokenFailed: (data: DeleteCardTokenResponseFailed) => void,
  onPreDeleteToken: (token: BaseCardToken) => Promise<boolean>,
  onUpdateTokenFailed: (data: UpdateCardTokenResponseFailed) => void,
  onUpdateTokenSuccess: (data: UpdateCardTokenResponseSuccess) => void,
  tokenItemBuilder: (elementIds: TokenBuilderElementIds) => string
  tokenLabelBuilder: (token: BaseCardToken) => string
};

const cardOnFile = pxpCheckoutSdk.create("card-on-file");

Properties

ParameterDescription
limitTokens
number
The maximum number of tokens to display in the component. For example, if set to 5 then only the first five card tokens are displayed.
filterBy
object
Details about the filtering options.
filterBy.excludeExpiredTokens
boolean
Whether to exclude tokens associated with expired cards.
filterBy.schemes
string []
The list of card schemes to include. For example, [Visa, MasterCard].
filterBy.fundingSource
string
The funding source type to include. For example Credit or Debit.
filterBy.issuerCountryCode
string
The issuer country code to include.
filterBy.ownerType
string
The owner type to include.
orderBy
object
Details about the ordering options.
orderBy.expiryDate
object
Details for ordering by expiry date.
orderBy.expiryDate.direction
string
The direction to order by.

Possible values:
  • desc
  • asc
orderBy.expiryDate.priority
number
The priority of the ordering option.
orderBy.scheme
object
Details for ordering by card scheme.
orderBy.scheme.valuesOrder
string
The card scheme.
orderBy.scheme.priority
number
The priority of the ordering option.
orderBy.fundingSource
object
Details for ordering by funding source.
orderBy.fundingSource.valuesOrder
string
The funding source.

Possible values:
  • Credit
  • Debit
orderBy.fundingSource.priority
number
The priority of the ordering option.
orderBy.ownerType
object
Details for ordering by owner type.
orderBy.ownerType.valuesOrder
string
The owner type.

Possible values:
  • Consumer
  • Commercial
orderBy.ownerType.priority
number
The priority of the ordering option.
orderBy.issuerCountryCode
object
Details for ordering by issuer country code.
orderBy.issuerCountryCode.direction
string
The direction to order by.

Possible values:
  • desc
  • asc
orderBy.issuerCountryCode.priority
number
The priority of the ordering option.
orderBy.lastUsageDate
object
Details for ordering by last usage date.
orderBy.lastUsageDate.direction
string
The direction to order by.

Possible values:
  • desc
  • asc
orderBy.lastUsageDate.orderByField
string
The field to order by.

Possible values:
  • lastSuccessfulPurchaseDate
  • lastSuccessfulPayoutDate
orderBy.lastUsageDate.priority
number
The priority of the ordering option.
cardBrandImages
object
Details about the card brand images.
cardBrandImages.visaSrc
string
The URL for the Visa card brand image.
cardBrandImages.mastercardSrc
string
The URL for the Mastercard card brand image.
cardBrandImages.amexSrc
string
The URL for the Amex card brand image.
cardBrandImages.cupSrc
string
The URL for the CUP card brand image.
cardBrandImages.dinersSrc
string
The URL for the Diners card brand image.
cardBrandImages.discoverSrc
string
The URL for the Discover card brand image.
cardBrandImages.jcbSrc
string
The URL for the JCB card brand image.
expiredText
string
The text to display for expired cards.
validThruText
string
The text to display for the "valid thru" label.
deleteModal
object
Configuration for the deletion modal.
deleteModal.dialogAriaLabel
string
The aria label for the deletion modal.
deleteModal.bodyText
string
The body text for the deletion modal.
deleteModal.cancelButtonText
string
The cancel button text for the deletion modal.
deleteModal.deleteButtonText
string
The delete button text for the deletion modal.
deleteModal.class
string
The name of the class associated with the deletion modal.
deleteErrorMessage
string
The error message to display when a card deletion fails.
deleteSuccessMessage
string
The success message to display when a card deletion is successful.
updateErrorMessage
string
The error message to display when a card update fails.
updateSuccessMessage
string
The success message to display when a card update is successful.
successMessageClass
string
The name of the CSS class to apply to success messages.
errorMessageClass
string
The name of the CSS class to apply to error messages.
isExpiryDateEditable
boolean
Whether the expiry date field can be edited by the cardholder.
isCvcRequired
boolean
Whether CVC is required when selecting a token. This applies to all tokens.
allowDeleteToken
boolean
Whether to allow cardholders to delete a token (previously saved card).
cvcComponentConfig
CardCvcComponentConfig
Configuration for the standalone card CVC component. See See reference for more details.
expiryDateComponentConfig
CardExpiryDateComponentConfig
Configuration for the standalone card expiry date component. See See reference.
styles
CSSProperties
Custom styling.
iconDeleteSrc
string
The URL for your custom delete icon.
iconSaveSrc
string
The URL for your custom save icon.
iconCancelSrc
string
The URL for your custom cancel icon.
iconEditSrc
string
The URL for your custom edit icon.
inputStyles
CSSProperties
Custom input styles.
tokenItemClass
string
Custom class for the token item.
useTransparentCardBrandImage
boolean
Whether to use transparent card brand images. Defaults to true.
editCardInformationAriaLabel
string
The aria label for the edit card information button.
saveCardInformationAriaLabel
string
The aria label for the save card information button.
cancelEditCardInformationAriaLabel
string
The aria label for the cancel edit information button.
deleteCardButtonAriaLabel
string
The aria label for the delete card button.
cardNumberAriaLabel
string
The aria label for the card number.
cardExpiryDateAriaLabel
string
The aria label for the card expiry date.

Callbacks

CallbackDescription
onPreRenderTokens: (data: RetrieveCardTokensReponseSuccess) => CardTokenMapping[]Callback function to order/filter tokens before rending. Returns an array of transformed card token objects ready for display.
onRetrieveTokensFailed: (data: RetrieveCardTokensReponseFailed) => voidCallback function triggered when token retrieval fails. Returns the failed response from the token retrieval API.
onDeleteTokenSuccess: (data: DeleteCardTokenResponseSuccess) => voidCallback function triggered after a token is successfully deleted. Returns the successful response from the token deletion API.
onDeleteTokenFailed: (data: DeleteCardTokenResponseFailed) => voidCallback function triggered when a token deletion fails. Returns the failed response from the token deletion API.
onPreDeleteToken: (token: BaseCardToken) => Promise<boolean>Callback function triggered before a token deletion attempt. This can be used to add confirmation logic or additional checks. Returns a boolean indicating whether deletion should proceed.
onUpdateTokenFailed: (data: UpdateCardTokenResponseFailed) => voidCallback function triggered when a token update fails. Returns the failed response from the token update API.
onUpdateTokenSuccess: (data: UpdateCardTokenResponseSuccess) => voidCallback function triggered after a token is successfully updated. Returns the successful response from the token update API.
tokenItemBuilder: (elementIds: TokenBuilderElementIds) => stringCallback function for building the token item layout.
tokenLabelBuilder: (token: BaseCardToken) => stringCallback function for building the token labels.

Example

import CardOnFileComponentConfig from "@pxpio/web-components-sdk/components/cardOnFileComponents/cardOnFileComponent";

const cardOnFileConfig: CardOnFileComponentConfig = {
  limitTokens: 5,
  filterBy: {
    excludeExpiredTokens: true,
    schemes: ["Visa', 'MasterCard"],
    fundingSource: "Credit",
    issuerCountryCode: "USA",
    ownerType: "Consumer"
  },
  orderBy: {
    expiryDate: { 
      direction: "asc",
      priority: 1
    },
    scheme: { 
      valuesOrder: ["Visa", "MasterCard", "Amex"],
      priority: 2
    },
    fundingSource: { 
      valuesOrder: ["Credit", "Debit"],
      priority: 3
    },
    ownerType: { 
      valuesOrder: ["Consumer", "Commercial"],
      priority: 4
    },
    issuerCountryCode: { 
      direction: "desc",
      priority: 5
    },
    lastUsageDate: { 
      direction: "desc",
      orderByField: "lastSuccessfulPurchaseDate",
      priority: 6
    }
  },
  cardBrandImages: {
    visaSrc: "https://example.com/visa-logo.png",
    mastercardSrc: "https://example.com/mastercard-logo.png",
    amexSrc: "https://example.com/amex-logo.png"
  },
  expiredText: "Card expired",
  validThruText: "Valid until",
  deleteModal: {
    dialogAriaLabel: "Delete card dialog",
    bodyText: "Are you sure you want to delete this payment method?",
    cancelButtonText: "No, keep it",
    deleteButtonText: 'Yes, delete it',
    class: "custom-modal-class"
  },
  deleteErrorMessage: "Unable to delete card. Please try again.",
  deleteSuccessMessage: "Card has been removed successfully.",
  updateErrorMessage: "Unable to update card information. Please try again.",
  updateSuccessMessage: "Card information updated successfully.",
  successMessageClass: "alert alert-success",
  errorMessageClass: "alert alert-danger",
  isExpiryDateEditable: true,
  isCvcRequired: true,
  allowDeleteToken: true,
  cvcComponentConfig: {
    required: true,
    label: "Security code",
    applyMask: true,
    showMaskToggle: true,
    labelPosition: "left",
    errorMessage: "Please enter a valid security code",
    inputStyles: {
      base: {
        color: "#333",
        fontSize: "16px"
      }
    }
  },
  expiryDateComponentConfig: {
    label: "Expiry date",
    labelPosition: "left",
    formatOptions: "MM/YY",
    inputStyles: {
      base: {
        color: "#333",
        fontSize: "16px"
      }
    }
  },
  styles: {
    backgroundColor: "#f8f9fa",
    border: "1px solid #dee2e6",
    borderRadius: "8px",
    padding: "20px"
  },
  iconDeleteSrc: "http://example.com/delete.jpg",
  iconSaveSrc: "http://example.com/save.jpg",
  iconCancelSrc: "http://example.com/cancel.jpg",
  iconEditSrc: "http://example.com/edit.jpg",
  inputStyles: {
    borderRadius: "5px",
    backgroundColor: "grey"
  },
  tokenItemClass: "custom-token-item-class",
  useTransparentCardBrandImage: true,
  editCardInformationAriaLabel: "Edit card information button",
  saveCardInformationAriaLabel: "Save card information button",
  cancelEditCardInformationAriaLabel: "Cancel edit card information button",
  deleteCardButtonAriaLabel: "Delete card button",
  cardNumberAriaLabel: "Card number",
  cardExpiryDateAriaLabel: "Card expiry date",
  onPreRenderTokens: (data: any) => {
    return data.gatewayTokens
      .filter((token: any) => token.issuerCountryCode === "USA")
      .map((token: any) => ({id: token.gatewayTokenId, isCvcRequired: true}));
  },
  onRetrieveTokensFailed: (data: any) => {
    alert("Retrieve tokens failed");
  },
  onDeleteTokenSuccess: (data: any) => {
    alert("Delete successful");
  },
  onDeleteTokenFailed: (data: any) => {
    alert("Delete failed");
  },
  onPreDeleteToken: (token: any) => {
    return new Promise((resolve) => {
      if (confirm("Are you sure to delete this token?")) resolve(true);
      resolve(false);
    });
  },
  onUpdateTokenFailed: (data: any) => {
    alert("Update failed");
  },
  onUpdateTokenSuccess: (data: any) => {
    alert("Update successful");
  },
  tokenItemBuilder: (config: any) => {
    return `<div>
      <div id="${config.tokenImageId}"></div>
      <div id="${config.tokenLabelId}"></div> 
      <div id="${config.editButtonId}"></div> 
      <div id="${config.deleteButtonId}"></div> 
      </div>`;
  },
  tokenLabelBuilder: (token: any) => 
    `${token.maskedPrimaryAccountNumber} - ${token.issuerName}`
};

const cardOnFile = pxpCheckoutSdk.create("card-on-file");