Web SDK Integration

1-CP Corporate Checkout Web SDK

The 1-CP Web SDK is a lightweight yet powerful JavaScript library that seamlessly integrates the 1-CP Corporate Checkout experience directly into your web applications. It's designed to streamline corporate purchasing, making it as effortless and intuitive as your favorite online shopping experience.

Why choose the 1-CP Web SDK?

• Seamless Integration: Easily embed the 1-CP Corporate Checkout technology into your existing web applications, regardless of your tech stack.

• Enhanced User Experience: Provide your employees with a familiar, user-friendly checkout process that boosts adoption and satisfaction, leading to higher compliance.

Usage

Installation

You can install the 1-CP Web SDK via npm:

npm install @one-cp/web-checkout

Alternatively, you can include it directly in your HTML file using a script tag:

<script src="https://one-cp-public.s3.eu-central-1.amazonaws.com/init.min.js"></script>

Initialization

To integrate the 1-CP checkout into your web application, follow these steps:

1. Import or include the 1-CP Web SDK in your JavaScript file or HTML file.

2. Call the init function with the required parameters:

import { init } from '@one-cp/web-checkout'

// Initialize 1-CP checkout
init({
    transactionID: 'transaction_id',
    widgetID: 'your_widget_id',
    config: {
        env: 'sandbox', // or 'production'
        mode: 'lightbox', // or 'inline'
        containerID: 'checkout-container', // optional, defaults to 'checkout-container'
        expand: false,
        viewOnly: false,
        redirectURL: 'https://yoursite.com/success' // optional redirect after success
    },
    onSuccess: (data) => {
        // Callback function on successful transaction
        console.log('Transaction completed successfully', data)
    },
    onError: (message) => {
        // Callback function on transaction error
        console.error('Transaction failed:', message)
    },
    onClose: () => {
        // Callback function on iframe close
        console.log('Checkout iframe closed')
    }
})

Parameters

Parameter	Description	Type	Required
transactionID	Unique ID for the transaction.	string	Yes
widgetID	ID of the widget associated with the transaction.	string	No
config	Configuration object for customizing the checkout.	OneCPCheckoutConfig	No
onSuccess	Callback function called on successful transaction.	(data: CheckoutInfo) => void	No
onError	Callback function called on transaction error.	(message: string) => void	No
onClose	Callback function called when checkout is closed.	() => void	No

Configuration Object

Parameter	Description	Type	Default Value
env	Environment for the checkout.	'sandbox' | 'production'	'sandbox'
mode	Mode of checkout display.	'lightbox' | 'inline'	'lightbox'
containerID	ID of the container element for inline mode.	string	'checkout-container'
expand	Whether to expand the checkout component.	boolean	false
viewOnly	Hide action buttons (view-only mode).	boolean	false
useTemplateData	Use template data when in view-only mode.	boolean	false
lang	ISO 639 language code for the checkout interface.	'en' | 'de'	'en'
redirectURL	URL to redirect to after successful transaction completion.	string	-
colors	Custom colors for the checkout interface.	object	See Colors section
logoURL	Custom logo URL for the provider.	string	-
hidePriceOverThumbnail	Hide/show price over thumbnail.	boolean	false
hideCo2Tag	Hide/show CO2 tag.	boolean	false

Important Notes:

• Passing a widget ID will override the logoURL parameter. If no logo is found in the widget configuration, the logoURL from the configuration will be used. If neither is available, a default company logo will be displayed.

• Passing a widget ID will override the hidePriceOverThumbnail and hideCo2Tag parameters.

• Setting a language will override the browser's default language. The language selector in the footer will not be shown. This ensures a consistent language experience for users, regardless of their browser settings.

• If containerID is not provided for inline mode, it defaults to 'checkout-container'. Ensure a DOM element with this ID exists.

onSuccess Response Data

When a transaction is completed successfully, the onSuccess callback receives a CheckoutInfo object with the following structure:

interface CheckoutInfo {
    reference: string
    payment: {
        reference: string
        provider: string
    }
    customer: {
        firstName: string
        lastName: string
        email?: string
        phone?: string
        address?: Address
    }
    beneficiary?: {
        firstName: string
        lastName: string
        email: string
    }
    billing: {
        name?: string
        email: string
        address: Address
        externalIds: {
            [key: string]: string
        }
        identifiers: CompanyIdentifiers
    }
    /**
     * Payment card data will be present if the payment method used is a card and the card details are available.
     * This property will be undefined if the payment was made using a non-card method, or if card data is not returned for security or compliance reasons.
     */
    card?: PaymentCardData
    reporting?: Record<string, string | number>
}

interface CompanyIdentifiers {
    VATIN: string
    BIC?: string
    DID?: string
    GLN?: string
    DUNS?: string
    TIN?: string
    LEI?: string
    IATA?: string
}

interface Address {
    street: string
    house: string
    city: string
    country: string
    zipCode: string
}

interface PaymentCardData {
    fingerprint?: string
    masked?: string
    expiryMonth: string
    expiryYear: string
    cardHolder: {
        prefix?: string
        title?: string
        salutation?: string
        first?: string
        last?: string
    }
    useType: 'SINGLE' | 'MULTIPLE'
    cardInfo?: {
        type: string
        brand: string
        usage: string
        country: string
        issuer: string
    }
}

Handling the Success State

Understanding the flow after a successful transaction is crucial for creating a seamless user experience. The SDK simplifies this process by handling the post-success redirection for you via the redirectURL parameter.

The onSuccess Callback

This callback is fired immediately after the payment is successfully processed. It is the ideal place to update your application's state (e.g., clear a shopping cart, update internal order status ) without worrying about UI changes.

The redirectURL Parameter

This optional parameter gives you control over the post-checkout experience.

1. If redirectURL is Provided (Recommended):

After a successful transaction, the checkout UI will display a confirmation message with a 3-second countdown. Once the countdown finishes, the SDK will automatically redirect the user to the URL you provided. The onClose callback will be fired just before the redirection occurs.

2. If redirectURL is NOT Provided:

The behavior depends on the mode.

Lightbox Mode: The checkout modal will close automatically after the 3-second countdown. The user will remain on your page.

Inline Mode: The success message will remain visible within its container. The user will not be redirected.

Color Customization

You can customize the appearance of the checkout interface by providing a colors object in the configuration:

Color Parameter	Description	Default Value
lightbox-color	Lightbox overlay color.	#2e2f4690
primary-color	Main color for header text and buttons.	#0866b6
light-primary-text	Text color on primary color buttons and components.	#ffffff
primary-color-white	Main background color.	#ffffff
primary-color-light	Light gray background color.	#f9f9fb
dark-primary-text	Main text color.	#000000de
medium-color-shade	Color for disabled buttons and other disabled elements.	#b2b8cd
accent-color	Hover effects color for buttons and other elements.	#88c7fd
tertiary-color-shade-tint	Color for borders and checkboxes.	#d8e4e3
danger-color	Background color for alerts and validation form errors.	#eb445a
danger-color-text	Text color for error messages and alerts.	#eb445a
medium-color-gray	Border color for input fields.	#8d8d8d

Note: Passing a widget ID will override the color configuration.

How to Obtain a Transaction ID

To initialize a checkout session, you need to obtain a transaction ID from the 1-CP API:

1. Your backend needs to call the /initialize endpoint of the 1-CP API.

2. To obtain client-id and client-secret, access the 1-CP Dashboard:

   • Navigate to Config → Widget

   • Create and configure your widget

   • You will receive the client-id and client-secret credentials

Example Implementation

HTML Example

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>1-CP Checkout Example</title>
    </head>
    <body>
        <div id="checkout-container"></div>
        <script src="https://one-cp-public.s3.eu-central-1.amazonaws.com/init.min.js"></script>

        <script>
            const transactionID = await request('your-api-to-create-transaction');

            // Initialize 1-CP checkout
            OneCP.init({
              transactionID,
              widgetID: 'your_widget_id',
              config: {
                env: 'sandbox',
                mode: 'inline',
                containerID: 'checkout-container', // optional, defaults to 'checkout-container'
                expand: false,
                viewOnly: false,
                lang: 'de', // Set checkout interface to German
                redirectURL: 'https://yoursite.com/success' // optional redirect after success
              },
              onSuccess: (data) => {
                console.log('Transaction completed successfully', data);
              },
              onError: (message) => {
                console.error('Transaction failed:', message);
              },
              onClose: () => {
                console.log('Checkout iframe closed');
              }
            });
        </script>
    </body>
</html>

Cleanup and Memory Management

The SDK handles cleanup automatically when the checkout process completes normally. This includes:

• Event Listener Cleanup: Message event listeners are automatically removed when the checkout closes

• DOM Cleanup: Iframe elements and containers (in lightbox mode) are automatically removed

• Style Restoration: Original body overflow styles are restored in lightbox mode

Cleanup Triggers:

• When the user completes or cancels the checkout

• When a redirectURL is provided and the user is redirected after success

• When the iframe sends a 'close' message

For Single-Page Applications (SPAs): The automatic cleanup should prevent memory leaks in most scenarios. However, if you need to handle edge cases or force cleanup:

Edge Case Considerations:

1. Unexpected Page Navigation: If the user navigates away during checkout, cleanup may not trigger

2. Manual iframe Removal: If you remove iframe elements manually, ensure proper cleanup

3. Multiple Rapid Initializations: Allow previous checkout to complete before initializing a new one

Best Practices for SPAs:

• Let the normal checkout flow complete (don't manually interrupt)

• Wait for onClose callback before reinitializing

• Test your specific use cases to ensure proper cleanup

TypeScript Support

The SDK now includes comprehensive TypeScript definitions. All configuration options, callback parameters, and return types are fully typed for better development experience and type safety.