Learn about customisation options for the card submit component.
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
};| Property | Description |
|---|---|
submitText | The text to display on the submit button. |
disableUntilValidated | Whether to disable the submit button until all fields are validated. |
hideSubmitButton | Whether to hide the submit button. |
container | The name of the HTML element to render the component into. |
id | The unique identifier for the component. |
class | The CSS class name for the component. |
label | The label text for the component. |
styles | Custom styles for the component. |
newCardComponent | Component for a new card. See New card. |
cardNumberComponent | Component for the card number. See Card number. |
cardExpiryDateComponent | Component for the card expiry date. See Card expiry date. |
cardCvcComponent | Component for the CVC. See Card CVC. |
cardHolderNameComponent | Component for the cardholder name. See Cardholder name. |
cardConsentComponent | Configuration details for the card consent component. |
cardOnFileComponent | Configuration details for the card-on-file component for saved payment methods. |
clickOnceStandaloneComponent | Configuration for the click-once standalone component. |
useCardOnFile | Whether 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. |
avsRequest | Whether to enable AVS checks. |
billingAddressComponents | Configuration 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.countrySelectionComponent | Component for country selection. |
billingAddressComponents.postcodeComponent | Component for postcode input. |
billingAddressComponents.addressComponent | Component for address input. |
billingAddressComponents.billingAddressComponent | Configuration details for the billing address component. See Billing address. |
tabIndex | The tab index of the component. |
submitAriaLabel | The aria label for the submit button. |
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
};| Callback | Description |
|---|---|
onClick: (event: Event) => void | Event handler for when the submit button is clicked. |
onChange: (state: ComponentState) => void | Event handler for when the component state changes. |
onValidation: (data: ValidationResult[]) => void | Event 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: () => boolean | Event handler for before tokenisation. |
onPostTokenisation: (data: { gatewayTokenId: string }) => void | Event 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: () => PreInitiateIntegratedAuthenticationData | null |
onPostInitiateAuthentication: (data: { authenticationId: string }) => void | Event 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<InitiateIntegratedAuthenticationData | null>` |
onPostAuthentication: (data: { authenticationId: string }) => void | Event 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<TransactionInitiationData | null>` |
onPostAuthorisation: (data: { merchantTransactionId: string, systemTransactionId: string }) => void | Event 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) => void | Event handler for when an error occurs during submission. |
onCollectStart: (data: any) => void | Event handler for when data collection begins. |
onCollectEnd: (data: any) => void | Event handler for when data collection ends. |
For more information about callbacks, see Events.
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();
}
}
};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);
}
};