# Configuration ODUS Checkout SDK is deeply customizable to fit your application's needs. ## Root Options | Option | Type | Required | Description | | ---------------------- | ------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------- | | `apiKey` | string | ✅ | Required, but not used since version 0.14.0 of the SDK. Pass `'pk_retired'`. | | `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](#localization) | | Language code for checkout localization | | `appearance` | [Appearance](https://docs.odus.com/docs/guides/checkout/drop-in/appearance.md) | | Customize the checkout UI appearance | | `initialValues` | [InitialValues](#initial-values) | | 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](#callbacks-and-event-handling) | | 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. Updating Callbacks After Initialization In reactive frameworks (React, Vue, Svelte), callbacks defined at mount time capture state via closure and can become stale when dependencies change. Use `setCallbacks()` to update callbacks without remounting: ``` // React example useEffect(() => { checkoutRef.current?.setCallbacks({ onPaymentSucceeded: () => trackPurchase(priceId, quantity), onPaymentFailed: (result) => logError(priceId, result), }); }, [priceId, quantity]); ``` Only the callbacks you pass are replaced — omitted callbacks remain unchanged. ### 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\ | Pre-fill billing address fields (all fields are optional) | | shippingAddress | Partial\ | 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 11 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 | | `cs` | Czech | | `nl` | Dutch | | `sk` | Slovak |