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

📦 Installation

``bash
npm install @waffo/payment-sdk


or


pnpm add @waffo/payment-sdk
`

🚀 Usage

$3

`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();
`

$3

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
✅ Merchant Logo: Display custom merchant logo via logoUrl
✅ 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 address

Returns: Promise

Success 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 properties

Returns: PaymentInstance

PaymentInstance Methods:

- unmount(): Unmount and cleanup iframe
- getIframe(): Get iframe DOM element
- updateAppearance(appearance): Dynamically update theme and logo without reloading iframe

Example:
`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: Promise

Example:
`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

---

📄 License

MIT © Waffo