Configuration

Odus Checkout SDK is deeply customizable to fit your application's needs.

Root Options

Option	Type	Required	Description
apiKey	string	✅	Your Odus Publishable key obtained from the dashboard's API Keys page
environment	string	✅	API environment to use - either 'test' or 'live'
returnUrl	string	✅	The URL where the customer will be redirected after 3DS authentication or other redirect flows
locale	Locale		Language code for checkout localization
appearance	Appearance		Customize the checkout UI appearance
initialValues	InitialValues		Pre-fill form fields with initial values
disableErrorMessages	boolean		Set to true to disable built-in error messages (defaults to false)
manualActionHandling	boolean		Set to true to manually handle 3DS redirects via the onActionRequired callback (defaults to false)
callbacks	Callbacks		Event callback functions

Callbacks and Event Handling

It is important to handle various events during the payment process. You can provide callback functions in the callbacks configuration option to respond to these events.

onPaymentSucceeded

Called when a payment is successfully authorized. This doesn't include redirect-based flows such as PayPal or 3DS authentication.

onPaymentSucceeded: (result) => {
  // result is the payment status: 'authorized'
  console.log('Payment successful!', result);
  // Update UI, redirect to thank you page, etc.
};

onPaymentFailed

Called when a payment fails. This doesn't include redirect-based flows such as PayPal or 3DS authentication.

onPaymentFailed: (result) => {
  // result is the payment status: 'failed'
  console.log('Payment failed!', result);
  // Show error message, allow retry, etc.
};

onActionRequired

Called when a payment requires additional action (such as 3DS authentication) and manualActionHandling is set to true. This allows you to customize how the redirect is handled, such as opening it in a modal or a new window.

onActionRequired: (redirectUrl) => {
  // redirectUrl is the URL where the customer needs to be redirected for 3DS authentication
  console.log('Action required!', redirectUrl);
  // Handle the redirect manually, e.g., open in a modal, new window, or custom redirect
  window.location.href = redirectUrl;
};

onLoadingStateChange

Called when the loading state of the checkout changes. You can use this to show or hide additional loading indicators in your application.

onLoadingStateChange: (isLoading) => {
  if (isLoading) {
    console.log('Checkout is loading...');
    // Show loading spinner
  } else {
    console.log('Checkout finished loading.');
    // Hide loading spinner
  }
};

Initial Values

In some cases, you may want to pre-fill certain fields in the checkout form, for example if you capture customer's email address earlier in the flow. You can do this by providing the initialValues option in the configuration:

const checkout = new OdusCheckout({
  // other configuration options
  initialValues: {
    email: 'user@example.com',
    name: 'John Doe',
    phoneNumber: '+1234567890',
    billingAddress: {
      firstName: 'John',
      lastName: 'Doe',
      street: '123 Main St',
      city: 'New York',
      state: 'NY',
      zipCode: '10001',
      country: 'US',
    },
    shippingAddress: {
      firstName: 'John',
      lastName: 'Doe',
      street: '456 Oak Ave',
      city: 'Los Angeles',
      state: 'CA',
      zipCode: '90001',
      country: 'US',
    },
  },
});

Supported values for initialValues include:

Field	Type	Description
email	string	Pre-fill the customer's email
name	string	Pre-fill the cardholder name
phoneNumber	string	Pre-fill the customer's phone number
billingAddress	Partial<AddressData>	Pre-fill billing address fields (all fields are optional)
shippingAddress	Partial<AddressData>	Pre-fill shipping address fields (all fields are optional)

The AddressData type includes the following fields: firstName, lastName, street, city, state, zipCode, and country. You can provide any subset of these fields.

note

Card-related fields (cardNumber, cardExpiry, cardCvv) cannot be pre-filled for PCI DSS compliance reasons.

Localization

By default, Odus Checkout will automatically detect and set the language based on the customer's browser settings. However, you can override this behavior by specifying a locale in the configuration options:

const checkout = new OdusCheckout({
  // ... other configuration options
  locale: 'fr', // Set language to French
});

Odus Checkout supports 8 languages with the following locale codes:

Locale Code	Language
en	English
fr	French
de	German
es	Spanish
it	Italian
pl	Polish
pt	Portuguese
tr	Turkish