{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","br","details","admonition"]},"type":"markdown"},"seo":{"title":"New card","description":"Transform your commerce with PXP's unified platform—seamless payments, real-time insights, and global growth in one powerful integration.","lang":"en-UK","siteUrl":"https://developer.pxp.io","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"new-card","__idx":0},"children":["New card"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn about customisation options for the new card component."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"styling","__idx":1},"children":["Styling"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const newCardConfig: NewCardComponentConfig = {\n  componentStyles: {\n    base: CSSProperties,\n    valid: CSSProperties,\n    invalid: CSSProperties,\n    input: CSSProperties\n  },\n  fields: {\n    cardNumber: {\n      containerId: string,\n      CardNumberComponentConfig\n    },\n    expiryDate: {\n      containerId: string,\n      CardExpiryDateComponentConfig\n    },\n    cvc: {\n     containerId: string,\n     isShow: boolean,\n     CardCvcComponentConfig\n    },\n    holderName: {\n      containerId: string,\n      isShow: boolean,\n      CardHolderNameComponentConfig\n    },\n    cardBrandSelector: {\n      containerId: string,\n      CardBrandSelectorComponentConfig\n      },\n    cardConsent: {\n      containerId: string,\n      isShow: boolean,\n      CardConsentComponentConfig\n     }\n  },\n  showLoadingState: boolean,\n  loadingStateTimeout: number,\n  submit: CardSubmitComponentConfig,\n  dynamicCardImageComponent: DynamicCardImageComponentConfig,\n  displayRequiredIcon: boolean\n};\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Property"},"children":["Property"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["componentStyles"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["ComponentStyles"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Custom styling for the component."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["componentStyles.base"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["CSSProperties"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Base styling for the component."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["componentStyles.valid"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["CSSProperties"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Styling for the component when it's valid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["componentStyles.invalid"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["CSSProperties"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Styling for the component when it's not valid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["componentStyles.input"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["CSSProperties"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Styling for the input element."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["showLoadingState"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Whether to display a loading state."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loadingStateTimeout"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The loading state timeout, in milliseconds."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submit"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["CardSubmitComponentConfig"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Configuration for the card submit component. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/web/card/card-submit"},"children":["Card submit"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dynamicCardImageComponent"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["DynamicCardImageComponent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Configuration for the dynamic card image component. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/web/card/dynamic-card-image"},"children":["Dynamic card image"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["displayRequiredIcon"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["boolean"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Whether to display an icon for all required fields."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submit"]}," property accepts all card submit component configurations, including the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCustomValidation"]}," callback for validating merchant-owned fields alongside SDK component validation. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/web/card/card-submit"},"children":["Card submit"]}," for all available submit configuration options."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"callbacks","__idx":2},"children":["Callbacks"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const newCardConfig: NewCardComponentConfig = {\n onChange: (state: ComponentState) => void,\n onBlur: (event: any) => void,\n onFocus: (event: any) => void,\n onValidation: (data: ValidationResult[]) => void,\n onPostTokenisation?: (data: { gatewayTokenId: string }) => void\n};\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Callback"},"children":["Callback"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onChange: (state: ComponentState) => void"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Event handler for when component state changes."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onBlur: (event: any) => void"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Event handler for when component loses focus."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onFocus: (event: any) => void"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Event handler for when component gains focus."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onValidation: (data: ValidationResult[]) => void"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Event handler for when validation is performed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onPostTokenisation: (data: { gatewayTokenId: string }) => void"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Event handler for after card tokenisation completes. Receives a data object with the gateway token ID. Use this to retrieve full token details from your backend."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information about callbacks, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/components/web/card/events"},"children":["Events"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example","__idx":3},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const newCardConfig: NewCardComponentConfig = {\n  displayRequiredIcon: true,\n  showLoadingState: true,\n  loadingStateTimeout: 3000,\n  styles: {\n    base: {\n      padding: \"16px\",\n      border: \"1px solid #e0e0e0\",\n      borderRadius: \"8px\"\n    },\n    valid: {\n      borderColor: \"#00cc66\"\n    },\n    invalid: {\n      borderColor: \"#ff3333\"\n    },\n    input: {\n      fontSize: \"16px\",\n      color: \"#333333\"\n    }\n  },\n  fields: {\n    cardNumber: {\n      containerId: \"card-number-container\",\n      required: true\n    },\n    expiryDate: {\n      containerId: \"expiry-container\",\n      required: true\n    },\n    cvc: {\n      containerId: \"cvc-container\",\n      isShow: true,\n      required: true\n    },\n    holderName: {\n      containerId: \"holder-name-container\",\n      isShow: true,\n      required: false\n    }\n  },\n  onChange: (state) => {\n    console.log(\"State changed:\", state.isValid);\n  },\n  onFocus: (event) => {\n    console.log(\"Field focused\");\n  },\n  onBlur: (event) => {\n    console.log(\"Field blurred\");\n  },\n  onValidation: (data) => {\n    console.log(\"Validation results:\", data);\n  },\n  onPostTokenisation: async (data) => {\n    console.log(\"Tokenisation complete. Gateway Token ID:\", data.gatewayTokenId);\n    \n    // Get full token details from backend if needed\n    const tokenDetails = await getTokenDetailsFromBackend(data.gatewayTokenId);\n    console.log(\"Token details retrieved:\", tokenDetails);\n  },\n  submit: {\n    submitText: \"Complete payment\",\n    avsRequest: true,\n    billingAddressComponents: {\n      billingAddressComponent: billingAddress\n    },\n    // Validate merchant fields alongside SDK billing address\n    onCustomValidation: async () => {\n      let isValid = true;\n      \n      // Validate shipping address\n      const shippingAddress = document.getElementById('shipping-address').value;\n      if (!shippingAddress || shippingAddress.trim().length < 5) {\n        showFieldError('shipping-address', 'Please enter a valid shipping address');\n        isValid = false;\n      }\n      \n      // Validate terms acceptance\n      const termsAccepted = document.getElementById('terms-checkbox').checked;\n      if (!termsAccepted) {\n        showFieldError('terms', 'You must accept the terms and conditions');\n        isValid = false;\n      }\n      \n      return isValid;\n    },\n    onPreAuthorisation: async (data) => {\n      return { psd2Data: {} };\n    },\n    onPostAuthorisation: (result) => {\n      console.log('Payment completed:', result.merchantTransactionId);\n      window.location.href = '/success';\n    }\n  }\n};\n","lang":"typescript"},"children":[]}]},"headings":[{"value":"New card","id":"new-card","depth":1},{"value":"Styling","id":"styling","depth":2},{"value":"Callbacks","id":"callbacks","depth":2},{"value":"Example","id":"example","depth":2}],"frontmatter":{"seo":{"title":"New card"}},"lastModified":"2026-02-26T12:14:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/components/web/card/new-card","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}