Waffo Payment SDK for secure card tokenization and iframe rendering
npm install @waffo/payment-sdk

A comprehensive payment SDK for web applications, featuring:
- š Card Tokenization - Secure card data tokenization with 3DS verification support
- š¼ļø Iframe Embedding - Embed customizable payment checkout pages with real-time theme updates
- š Apple Pay Support - Seamless Apple Pay integration within iframe
- šØ Theme Customization - Dynamic theme switching with merchant logo support
``bash`
npm install @waffo/payment-sdkor
pnpm add @waffo/payment-sdk
`javascript
import WaffoSDK from '@waffo/payment-sdk';
// Initialize SDK
const sdk = new WaffoSDK('your-client-api-key', {
env: 'prod', // 'prod' | 'testing' | 'sandbox'
locale: 'en' // Optional, default 'en'
});
// Submit tokenization request
const result = await sdk.tokenizationSubmit('token-session-id', {
tokenDataVerification: false, // Optional, validate card data, default false
tokenData: {
pan: '4111111111111111', // Card number
name: 'John Doe', // Cardholder name
expiry: '12/2025', // Expiry date MM/YYYY
cvv: '123' // CVV (optional)
},
billingAddress: { // Optional
countryCode: 'USA',
region: 'CA',
city: 'San Francisco',
postalCode: '94102',
address: '123 Main St'
}
});
// Handle result
if (result.success) {
console.log('Token Request ID:', result.data.tokenRequestId);
if (result.data.validateUrl) {
// 3DS verification required
window.location.href = result.data.validateUrl;
}
} else {
console.error('Error:', result.error.code, result.error.message);
}
// Destroy SDK (cleanup resources)
sdk.destroy();
`
The renderIframe function allows you to embed the Waffo payment checkout page in your merchant page, similar to Stripe SDK's iframe embedding functionality.
#### Basic Usage
`javascript
import WaffoSDK from '@waffo/payment-sdk';
// Render payment iframe
const payment = WaffoSDK.renderIframe({
// Required parameters
url: 'https://cashier.waffo.com/orderKey', // Payment page URL
container: '#payment-container', // Container selector or DOM element
// Optional: Theme customization
appearance: {
// Merchant logo URL (optional)
logoUrl: 'https://example.com/logo.png',
// Theme variables (optional)
variables: {
colorPrimary: '#0570de', // Primary color
colorBackground: '#ffffff', // Background color
colorCard: '#f8f9fa', // Card background color
colorText: '#30313d', // Text color
colorTextSecondary: '#6b7280', // Secondary text color
colorTextTertiary: '#9ca3af', // Tertiary text color
colorDanger: '#d93025', // Error/danger color
colorInfo: '#e3f2fd', // Info background color
fontSizeBase: '16px', // Base font size
borderRadius: '8px', // Border radius
},
},
// Optional: iframe styles
style: {
width: '100%',
height: '600px',
border: 'none',
borderRadius: '8px',
},
});
// Unmount iframe
payment.unmount();
`
#### Dynamic Theme Update
You can dynamically update the theme and logo after the iframe is rendered, without reloading the iframe:
`javascript
import WaffoSDK from '@waffo/payment-sdk';
// Render iframe with initial theme
const payment = WaffoSDK.renderIframe({
url: 'https://cashier.waffo.com/orderKey',
container: '#payment-container',
appearance: {
logoUrl: 'https://example.com/logo.png',
variables: {
colorPrimary: '#0570de',
colorBackground: '#ffffff',
},
},
});
// Later, update theme dynamically (e.g., user switches to dark mode)
// Note: Always include logoUrl when updating theme to preserve the logo
await payment.updateAppearance({
logoUrl: 'https://example.com/logo.png', // Keep the logo
variables: {
colorPrimary: '#5b8ef3',
colorBackground: '#1a1a1a',
colorCard: '#2a2a2a',
colorText: '#ffffff',
colorTextSecondary: '#b0b0b0',
},
});
// The iframe theme will update in real-time without page refresh!
`
#### Real-time Theme Preview Example
`javascript
// Example: Color picker with real-time preview
const colorInput = document.getElementById('primary-color');
let updateTimeout;
colorInput.addEventListener('input', (e) => {
// Debounce updates
clearTimeout(updateTimeout);
updateTimeout = setTimeout(async () => {
await payment.updateAppearance({
variables: {
colorPrimary: e.target.value,
},
});
}, 300);
});
`
#### Key Features
ā
Theme Customization: Customize payment page styles via appearance parameter logoUrl
ā
Merchant Logo: Display custom merchant logo via
ā
Dynamic Updates: Update theme and logo in real-time without reloading iframe
ā
Apple Pay Support: Automatically handles Apple Pay communication in iframe
ā
On-Demand Loading: Apple Pay SDK loads only when needed, no performance impact
ā
Secure Sandbox: iframe uses secure sandbox and allow attributes
ā
Flexible Styling: Support custom iframe width, height, border, etc.
#### Complete Example
`html
š API Reference
$3
Create an SDK instance.
Parameters:
-
clientApiKey (string): Client API key
- options (object):
- env (string): Environment, values: 'prod' | 'testing' | 'sandbox'
- locale (string): Language code, e.g. 'en', 'ja', 'zh' (optional, default 'en')Returns:
WaffoSDK instance---
$3
Submit card tokenization request.
Parameters:
-
tokenSessionId (string): Token session ID
- request (object):
- tokenDataVerification (boolean): Validate card data (optional, default false)
- tokenData (object): Card data
- pan (string): Card number
- name (string): Cardholder name
- expiry (string): Expiry date, format MM/YYYY
- cvv (string): CVV security code (optional)
- billingAddress (object): Billing address (optional)
- countryCode (string): Country code (ISO 3166-1 alpha-3)
- region (string): State/Province/Region
- city (string): City
- postalCode (string): Postal code
- address (string): Street addressReturns:
PromiseSuccess Response:
`typescript
{
success: true,
data: {
tokenRequestId: string,
validateUrl?: string // If 3DS verification is required
}
}
`Error Response:
`typescript
{
success: false,
data: null,
error: {
code: string,
message: string
}
}
`Error Codes:
| Error Code | Description |
|------------|-------------|
|
011001P001 | Wrong parameters. |
| 011001P002 | Idempotent param mismatch error. |
| 011001B004 | Invalid expiry date format. |
| 011001B005 | The card has been expired. |
| 011001B006 | The card's BIN has been denied. |
| 011001B024 | The token session has expired. |
| 011001B025 | Card information is invalid. - pan, name, expiry are required |
| 011001B027 | The token session is invalid. |
| 011001B031 | The merchant contract not matched. |
| 011001S001 | System process failed. |---
$3
Destroy SDK instance and cleanup resources.
Parameters: None
Returns:
void---
$3
Render payment checkout page in an iframe.
Parameters:
-
options (object): RenderIframe configuration
- url (string, required): Payment page URL
- container (string | HTMLElement, required): Container selector or DOM element
- appearance (object, optional): Theme customization
- logoUrl (string, optional): Merchant logo URL
- variables (object, optional): Theme variables
- colorPrimary (string): Primary color
- colorBackground (string): Background color
- colorCard (string): Card background color
- colorText (string): Text color
- colorTextSecondary (string): Secondary text color
- colorTextTertiary (string): Tertiary text color
- colorDanger (string): Error/danger color
- colorInfo (string): Info background color
- fontSizeBase (string): Base font size
- borderRadius (string): Border radius
- style (object, optional): Iframe CSS styles
- width (string): Width, default '100%'
- height (string): Height, default '600px'
- border (string): Border, default 'none'
- borderRadius (string): Border radius, default '0px'
- [key: string] (string): Other CSS propertiesReturns:
PaymentInstancePaymentInstance Methods:
-
unmount(): Unmount and cleanup iframe
- getIframe(): Get iframe DOM element
- updateAppearance(appearance): Dynamically update theme and logo without reloading iframeExample:
`javascript
const payment = WaffoSDK.renderIframe({
url: 'https://cashier.waffo.com/order123',
container: '#payment-container',
appearance: {
logoUrl: 'https://example.com/logo.png',
variables: {
colorPrimary: '#0570de',
colorCard: '#ffffff',
},
},
});// Update theme and logo dynamically
await payment.updateAppearance({
logoUrl: 'https://example.com/logo.png',
variables: {
colorPrimary: '#00a86b',
},
});
// Clean up
payment.unmount();
`---
$3
Dynamically update the iframe theme and logo without reloading the page.
Parameters:
-
appearance (object): Theme configuration
- logoUrl (string, optional): Merchant logo URL
- variables (object, optional): Theme variables (same as renderIframe)Returns:
PromiseExample:
`javascript
// Initial render
const payment = WaffoSDK.renderIframe({
url: 'https://cashier.waffo.com/order123',
container: '#payment-container',
appearance: {
logoUrl: 'https://example.com/logo.png',
variables: {
colorPrimary: '#0570de',
},
},
});// Update to dark theme (include logoUrl to preserve the logo)
await payment.updateAppearance({
logoUrl: 'https://example.com/logo.png',
variables: {
colorPrimary: '#5b8ef3',
colorBackground: '#1a1a1a',
colorCard: '#2a2a2a',
colorText: '#ffffff',
},
});
// Update only the logo
await payment.updateAppearance({
logoUrl: 'https://example.com/new-logo.png',
});
// Update only colors (include logoUrl to preserve the logo)
await payment.updateAppearance({
logoUrl: 'https://example.com/logo.png',
variables: {
colorPrimary: '#00a86b',
},
});
`Important: When calling
updateAppearance, always include logoUrl if you want to preserve the merchant logo. If logoUrl` is omitted, the logo may be hidden after the theme update.Benefits:
- ā
Real-time theme and logo updates without page reload
- ā
Smooth user experience
- ā
Preserves user input data
- ā
Reduces network requests
- ā
Perfect for theme switchers and color pickers
---
MIT Ā© Waffo