Skip to content

Card submit

Learn about customisation options for the card submit component.

Styling

const cardSubmitConfig: CardSubmitComponentConfig = {
  submitText: string,
  disableUntilValidated: boolean,
  hideSubmitButton: boolean,
  container: string,
  id: string,
  class: string,
  label: string,
  styles: CardSubmitComponentStyles,
  newCardComponent: NewCardComponent,
  cardNumberComponent: CardNumberComponent,
  cardExpiryDateComponent: CardExpiryDateComponent,
  cardCvcComponent: CardCvcComponent,
  cardHolderNameComponent: CardHolderNameComponent,
  cardConsentComponent: CardConsentComponent,
  cardOnFileComponent: CardOnFileComponent,
  clickOnceStandaloneComponent: ClickOnceStandaloneComponent,
  useCardOnFile: boolean,
  avsRequest: boolean,
  billingAddressComponents: {
    countrySelectionComponent: CountrySelectionComponent,
    postcodeComponent: PostcodeComponent,
    addressComponent: AddressComponent,
    billingAddressComponent: BillingAddressComponent
  },
  tabIndex: number,
  submitAriaLabel: string
};
PropertyDescription
submitTextThe text to display on the submit button.
disableUntilValidatedWhether to disable the submit button until all fields are validated.
hideSubmitButtonWhether to hide the submit button.
containerThe name of the HTML element to render the component into.
idThe unique identifier for the component.
classThe CSS class name for the component.
labelThe label text for the component.
stylesCustom styles for the component.
newCardComponentComponent for a new card. See New card.
cardNumberComponentComponent for the card number. See Card number.
cardExpiryDateComponentComponent for the card expiry date. See Card expiry date.
cardCvcComponentComponent for the CVC. See Card CVC.
cardHolderNameComponentComponent for the cardholder name. See Cardholder name.
cardConsentComponentConfiguration details for the card consent component.
cardOnFileComponentConfiguration details for the card-on-file component for saved payment methods.
clickOnceStandaloneComponentConfiguration for the click-once standalone component.
useCardOnFileWhether to select the card-on-file method to initiate the transaction. If true, uses COF data. If false, uses new card data. Defaults to false.
avsRequestWhether to enable AVS checks.
billingAddressComponentsConfiguration details for the billing address components. Allows you to integrate the pre-built billing address component with the card submit component.
If you pass billingAddressComponents and avsRequest is set to true, that will send billing address data to the transaction.
If you pass both the pre-built billingAddressComponent and the three standalone components, that will use pre-built billingAddressComponent's data.
billingAddressComponents.countrySelectionComponentComponent for country selection.
billingAddressComponents.postcodeComponentComponent for postcode input.
billingAddressComponents.addressComponentComponent for address input.
billingAddressComponents.billingAddressComponentConfiguration details for the billing address component. See Billing address.
tabIndexThe tab index of the component.
submitAriaLabelThe aria label for the submit button.

Callbacks

const cardSubmitConfig: CardSubmitComponentConfig = {
  onClick: (event: Event) => void,
  onChange: (state: ComponentState) => void,
  onValidation: (data: ValidationResult[]) => void,
  onCustomValidation: () => Promise<boolean>,
  onPreTokenisation: () => boolean,
  onPostTokenisation: (data: { gatewayTokenId: string }) => void,
  onPreInitiateAuthentication: () => PreInitiateIntegratedAuthenticationData | null | undefined,
  onPostInitiateAuthentication: (data: { authenticationId: string }) => void,
  onPreAuthentication: () => Promise<InitiateIntegratedAuthenticationData | null>,
  onPostAuthentication: (data: { authenticationId: string }) => void,
  onPreAuthorisation: (data: { gatewayTokenId: string }) => Promise<TransactionInitiationData | null>,
  onPostAuthorisation: (data: { merchantTransactionId: string, systemTransactionId: string }) => void,
  onGetFingerprintResult: () => Promise<string>,
  onSubmitError: (baseSdkException: BaseSdkException) => void,
  onCollectStart: (data: any) => void,
  onCollectEnd: (data: any) => void
};
CallbackDescription
onClick: (event: Event) => voidEvent handler for when the submit button is clicked.
onChange: (state: ComponentState) => voidEvent handler for when the component state changes.
onValidation: (data: ValidationResult[]) => voidEvent handler for when validation occurs with validation results.
onCustomValidation: () => Promise<boolean>Callback executed before submission for custom validation. Use this callback when you need to validate other fields (such as shipping address or terms acceptance) alongside the card submit component validation. Return true to proceed with submission, false to prevent submission. This enables simultaneous validation of merchant-owned fields and SDK components (billing address), eliminating the two-phase validation flow.
onPreTokenisation: () => booleanEvent handler for before tokenisation.
onPostTokenisation: (data: { gatewayTokenId: string }) => voidEvent handler for after tokenisation completes. Receives a data object with the gateway token ID. Use this to retrieve full token details from your backend.
`onPreInitiateAuthentication: () => PreInitiateIntegratedAuthenticationDatanull
onPostInitiateAuthentication: (data: { authenticationId: string }) => voidEvent handler for after authentication initiation. Receives a data object with the authentication ID. Use this to retrieve full authentication details from your backend.
`onPreAuthentication: () => Promise<InitiateIntegratedAuthenticationDatanull>`
onPostAuthentication: (data: { authenticationId: string }) => voidEvent handler for after authentication. Receives a data object with the authentication ID. Use this to retrieve full authentication details from your backend.
`onPreAuthorisation: (data: { gatewayTokenId: string }) => Promise<TransactionInitiationDatanull>`
onPostAuthorisation: (data: { merchantTransactionId: string, systemTransactionId: string }) => voidEvent handler for after authorisation completes. Receives a data object with the transaction identifiers. Use these to retrieve full transaction details from your backend.
onGetFingerprintResult: () => Promise<string>Retrieve fingerprint data for authentication.
onSubmitError: (baseSdkException: BaseSdkException) => voidEvent handler for when an error occurs during submission.
onCollectStart: (data: any) => voidEvent handler for when data collection begins.
onCollectEnd: (data: any) => voidEvent handler for when data collection ends.

For more information about callbacks, see Events.

Example

Basic configuration

const cardSubmitConfig: CardSubmitComponentConfig = {
  submitText: "Pay now",
  disableUntilValidated: true,
  avsRequest: true,
  cardNumberComponent: cardNumber,
  cardExpiryDateComponent: cardExpiry,
  cardCvcComponent: cardCvc,
  cardHolderNameComponent: cardHolderName,
  onClick: (event: Event) => {
    console.log('Submit button clicked', event);
    // Add custom logic before submission
    if (!userConsent) {
     event.preventDefault();
      showConsentDialog();
    }
  }
};

Using onCustomValidation for simultaneous validation

Use the onCustomValidation callback to validate your merchant-owned fields alongside SDK component validation. This enables all validation errors to be displayed on the first submit attempt, improving the customer experience.

const cardSubmitConfig: CardSubmitComponentConfig = {
  submitText: "Pay now",
  disableUntilValidated: true,
  avsRequest: true,
  cardNumberComponent: cardNumber,
  cardExpiryDateComponent: cardExpiry,
  cardCvcComponent: cardCvc,
  cardHolderNameComponent: cardHolderName,
  billingAddressComponents: {
    billingAddressComponent: billingAddress
  },
  // Validate merchant fields alongside SDK billing address validation
  onCustomValidation: async () => {
    let isValid = true;

    // Validate shipping address
    const shippingAddress = document.getElementById('shipping-address').value;
    if (!shippingAddress || shippingAddress.trim().length < 5) {
      showError('shipping-address', 'Please enter a valid shipping address');
      isValid = false;
    }

    // Validate email
    const email = document.getElementById('email').value;
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!email || !emailRegex.test(email)) {
      showError('email', 'Please enter a valid email address');
      isValid = false;
    }

    // Validate terms acceptance
    const termsAccepted = document.getElementById('terms-checkbox').checked;
    if (!termsAccepted) {
      showError('terms', 'You must accept the terms and conditions');
      isValid = false;
    }

    // Return true to proceed with submission, false to prevent it
    return isValid;
  },
  onPreAuthorisation: (data) => {
    // Transaction data logic
    return Promise.resolve({
      psd2Data: {}
    });
  },
  onPostAuthorisation: (result) => {
    console.log('Payment completed:', result.merchantTransactionId);
  },
  onSubmitError: (error) => {
    console.error('Payment error:', error.message);
  }
};