The SDK requires configuration during initialization:
import LiquidCommerce from '@liquidcommerce/cloud-sdk';
// Your Account token provided to you through your account representative
const client = await LiquidCommerce('YOUR_LIQUIDCOMMERCE_API_KEY', {
googlePlacesApiKey: 'YOUR_GOOGLE_PLACES_API_KEY',
env: 'stage' // or 'prod'
});
// Initialize the client
await client.init();
// Create/update user session
const userSession = await client.user.session({
email: "user@example.com",
firstName: "John",
lastName: "Smith",
phone: "2125551234",
company: "Company Inc",
profileImage: "https://...",
birthDate: "1990-01-01",
id:'user_id', // Existing user identifier (for updates only), email becomes optional
});
// Fetch user by ID or email
const userData = await client.user.fetch('user_id_or_email');
// Address management
const newAddress = await client.user.addAddress({
customerId: 'customer_id',
placesId: 'google_places_id', // Optional if providing address details
one: '100 Madison St',
two: 'Apt 4B',
city: 'New York',
state: 'NY',
zip: '10004',
country: 'US',
lat: 40.7128, // Optional
long: -74.0060, // Optional
type: ENUM_ADDRESS_TYPE.SHIPPING,
isDefault: true
});
const updatedAddress = await client.user.updateAddress({
// Same parameters as addAddress
});
// Payment methods
// 1. First create/retrieve a user session
const userSession = await client.user.session({
email: "user@example.com",
// ... other user details
});
// 2. Initialize payment form with session data
// The session response includes payment configuration in the auth object
await client.payment.mount({
clientSecret: userSession.data.session.setupIntent, // From user session response
key: userSession.data.session.publicKey, // From user session response
elementId: 'payment-element-container',
appearance: {
theme: 'night' // 'default' | 'night' | 'flat'
},
elementOptions: {
layout: 'tabs' // 'tabs' | 'accordion' | 'auto'
}
});
// 3. Listen for payment element events
client.payment.subscribe('ready', () => {
console.log('Payment element is ready');
});
client.payment.subscribe('change', (event) => {
// Handle validation and form state changes
console.log('Payment element changed:', event);
});
// 4. When user submits, generate payment token
const tokenResult = await client.payment.generateToken();
if ('error' in tokenResult) {
console.error('Token generation failed:', tokenResult.error);
// Handle error cases:
// - validation_error: Invalid payment details
// - api_error: Server/API issues
// - client_error: SDK/setup issues
// - confirm_error: Payment confirmation failed
} else {
// Payment method successfully created
console.log('Payment token:', tokenResult.id);
// 5. Add payment method to user profile
await client.user.addPayment({
userId: userSession.data.id,
paymentMethodId: tokenResult.id,
isDefault: true
});
}
// 6. Clean up
client.payment.unmount();
client.payment.destroy();
// Data removal
await client.user.purge('user_id_or_email');
await client.user.purgeAddress('address_id');
await client.user.purgePayment('user_id', 'payment_id');
Payment
The payment system uses secure elements for handling sensitive payment data. Before using payment features, you must first create a user session.
Prerequisites
User Session Creation:
// First create or get a user session
const userSession = await client.user.session({
email: "user@example.com",
// ... other user details
});
// The session response includes necessary payment credentials
const { secret, key } = userSession.data.session;
Payment Element Integration
// Initialize payment form using session credentials
await client.payment.mount({
clientSecret: secret, // Required: From user session response
key, // Required: From user session response
elementId: 'payment-element-container', // Your DOM element ID
appearance: {
theme: 'night' // 'default' | 'night' | 'flat'
},
elementOptions: {
layout: 'tabs' // 'tabs' | 'accordion' | 'auto'
}
});
// Monitor payment element state
client.payment.subscribe('ready', () => {
// Element is ready to accept input
});
client.payment.subscribe('change', (event) => {
const { complete, empty, value } = event;
// Handle validation state changes
});
// Process payment when ready
const tokenResult = await client.payment.generateToken();
// Handle the result
if ('error' in tokenResult) {
const { type, message, code } = tokenResult.error;
// type can be: 'validation_error' | 'api_error' | 'client_error' | 'confirm_error'
} else {
// Use tokenResult.id for checkout completion or saving payment method
const { id, card } = tokenResult;
}
// Always clean up when done
client.payment.unmount();
client.payment.destroy();
Security Considerations
PCI Compliance: The payment element handles card data securely within an iframe, ensuring your application never directly touches sensitive payment information.
Token-Based: All payment data is tokenized - you only receive secure tokens that can't be used to retrieve the original card details.
Single Use: Payment tokens are single-use and expire after a short time period.
Domain Validation: Payment elements will only work on domains that have been pre-registered with your account.
try {
const token = await client.payment.generateToken();
if ('error' in token) {
switch(token.error.type) {
case 'validation_error':
// Handle invalid card data
break;
case 'api_error':
// Handle API/network issues
break;
case 'client_error':
// Handle setup/configuration issues
break;
case 'confirm_error':
// Handle payment confirmation failures
break;
}
}
} catch (error) {
// Handle unexpected errors
}
Cleanup: Always clean up payment elements when done:
When navigation away from payment page
After successful payment
After failed payment attempt
Before unmounting payment component
Event Handling: Monitor element state for better user experience:
client.payment.subscribe('change', (event) => {
// Update UI based on validation state
const { complete, empty } = event;
submitButton.disabled = !complete || empty;
});
client.payment.subscribe('loaderror', (event) => {
// Handle element loading failures
console.error('Payment element failed:', event.error);
});
Responsive Design
The payment element automatically adapts to:
Mobile and desktop viewports
Right-to-left languages
Dark/light themes
Different container sizes
Testing Cards
When testing payments in staging environment, use these test cards:
// Test Visa Card
Card Number: 4242 4242 4242 4242
Expiry: Any future date
CVC: Any 3 digits
ZIP: Any 5 digits
// Test Mastercard
Card Number: 5555 5555 5555 4444
Expiry: Any future date
CVC: Any 3 digits
ZIP: Any 5 digits
// Example test card usage:
/*
Card: 4242 4242 4242 4242
Expiry: 12/29
CVC: 123
ZIP: 10001
*/
These cards will be accepted in test mode and will simulate successful payments. They should only be used in the staging environment, never in production.
