Checkout Web SDK
One-CP Corporate Checkout Web SDK
The One-CP Web SDK is a lightweight yet powerful JavaScript library that seamlessly integrates the One-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 One-CP Web SDK?
Seamless Integration: Easily embed the One-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 One-CP Web SDK via npm:
npm install @one-cp/web-checkoutAlternatively, 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 One-CP checkout into your web application, follow these steps:
Import or include the One-CP Web SDK in your JavaScript file or HTML file.
Call the init function with the required parameters:
import { init } from '@one-cp/web-checkout';
// Initialize One-CP checkout
init({
transactionID: 'transaction_id',
widgetID: 'your_widget_id',
config: {
env: 'sandbox', // or 'production'
mode: 'lightbox', // or 'inline'
containerID: 'checkout-container', // required only for inline mode
expand: false,
viewOnly: false
},
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
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
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
Required for inline mode
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
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
logoURLparameter. If no logo is found in the widget configuration, thelogoURLfrom the configuration will be used. If neither is available, a default company logo will be displayed.Passing a widget ID will override the
hidePriceOverThumbnailandhideCo2Tagparameters.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.
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
}
}
Color Customization
You can customize the appearance of the checkout interface by providing a colors object in the configuration:
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 One-CP API:
Your backend needs to call the
/initializeendpoint of the One-CP API.To obtain
client-idandclient-secret, access the One-CP Dashboard:Navigate to Config → Widget
Create and configure your widget
You will receive the
client-idandclient-secretcredentials
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>One-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 One-CP checkout
OneCP.init({
transactionID,
widgetID: 'your_widget_id',
config: {
env: 'sandbox',
mode: 'inline',
containerID: 'checkout-container', // required only for inline mode
expand: false,
viewOnly: false,
lang: 'de' // Set checkout interface to German
},
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 init function returns a cleanup function that should be called to properly dispose of resources:
const cleanup = init({
transactionID: 'your-transaction-id',
// ... other parameters
});
// Call cleanup when component unmounts or page changes
cleanup();For cleaning up all active instances at once:
import { cleanupAllInstances } from '@one-cp/web-checkout';
// Cleanup all active checkout instances
cleanupAllInstances();This is particularly important in single-page applications (SPAs) to prevent memory leaks and ensure proper cleanup of event listeners and DOM elements.
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.
Last updated