Custom Checkout
Integrate a seamless cryptocurrency checkout experience directly into your website or application.
Overview
ZenPay Custom Checkout provides a complete, customizable checkout solution that integrates directly into your website. Unlike payment buttons or checkout links, Custom Checkout gives you full control over the payment experience while maintaining security and ease of use.
Seamless Experience
Keep customers on your website throughout the payment process.
Complete Customization
Tailor the checkout UI to match your website design.
Developer-Friendly
Built with developers in mind for easy integration.
Secure By Design
Security built in at every layer.
Integration Options
ZenPay Custom Checkout offers two main integration approaches to suit different development needs:
1. Drop-in Checkout
The fastest way to integrate ZenPay's Custom Checkout. This option provides a pre-built checkout UI that you can customize with your colors and branding.
Use When:
- You need a quick integration with minimal development effort
- Customizing colors and text is sufficient for your needs
- You prefer a solution that works out of the box
// 1. Include ZenPay.js on your page
<script src="https://js.zenpay.io/v1/zenpay.js"></script>
// 2. Configure your checkout
<script>
document.addEventListener('DOMContentLoaded', function() {
const zenpay = new ZenPay('pk_test_YourPublicKey');
document.getElementById('pay-button').addEventListener('click', async () => {
try {
// Create a checkout session
const session = await zenpay.createCheckoutSession({
amount: 99.99,
currency: 'USD',
product_name: 'Premium Membership',
customer_email: 'customer@example.com',
success_url: window.location.origin + '/thank-you',
cancel_url: window.location.origin + '/cart'
});
// Launch the checkout modal
zenpay.showCheckout(session.id, {
theme: {
colorPrimary: '#4F46E5',
colorBackground: '#FFFFFF',
colorText: '#1F2937',
borderRadius: '8px',
fontFamily: 'Inter, sans-serif'
}
});
} catch (error) {
console.error('Error creating checkout session:', error);
}
});
});
</script>
// 3. Add a button to trigger checkout
<button id="pay-button" class="payment-button">Pay with Crypto</button>
2. Custom UI Integration
For developers who want complete control over the checkout experience. This approach lets you build your own UI using ZenPay's SDK components.
Use When:
- You need complete control over the checkout UI
- Your checkout flow requires custom steps or validation
- You want to build a native-feeling experience within your application
// First, install the ZenPay React SDK
// npm install @zenpay/react
import React, { useState } from 'react';
import {
ZenPayProvider,
useZenPay,
CryptoPaymentForm,
CryptoMethodSelector,
CheckoutSummary,
PaymentStatus
} from '@zenpay/react';
// Your checkout component
function CustomCheckout({ amount, currency, productName }) {
const [paymentStatus, setPaymentStatus] = useState('idle');
const [selectedMethod, setSelectedMethod] = useState(null);
const { createPayment, getPaymentStatus } = useZenPay();
const handleSubmit = async () => {
try {
setPaymentStatus('processing');
// Create a payment with ZenPay
const payment = await createPayment({
amount,
currency,
product_name: productName,
payment_method: selectedMethod,
metadata: {
customer_id: 'cust_123456', // Your internal customer ID
order_id: 'ord_789012' // Your internal order ID
}
});
// Poll for payment status
const statusInterval = setInterval(async () => {
const status = await getPaymentStatus(payment.id);
if (status === 'completed') {
setPaymentStatus('success');
clearInterval(statusInterval);
} else if (status === 'failed') {
setPaymentStatus('error');
clearInterval(statusInterval);
}
}, 5000);
} catch (error) {
console.error('Payment error:', error);
setPaymentStatus('error');
}
};
return (
<div className="checkout-container">
<CheckoutSummary
amount={amount}
currency={currency}
productName={productName}
/>
<CryptoMethodSelector
onChange={method => setSelectedMethod(method)}
selectedMethod={selectedMethod}
/>
{selectedMethod && (
<CryptoPaymentForm
method={selectedMethod}
onSubmit={handleSubmit}
/>
)}
{paymentStatus !== 'idle' && (
<PaymentStatus status={paymentStatus} />
)}
</div>
);
}
// Wrap your app with the provider
function App() {
return (
<ZenPayProvider apiKey="pk_test_YourPublicKey">
<CustomCheckout
amount={99.99}
currency="USD"
productName="Premium Membership"
/>
</ZenPayProvider>
);
}
Customization Options
The Drop-in Checkout can be customized in several ways to match your website's design:
Theme Customization
Adjust the visual appearance of the checkout:
- Colors: primary, background, text, success, error
- Typography: font family, font sizes, weights
- Shapes: border radius, input styles, button styles
- Spacing: paddings, margins, layout
- Light and dark mode support
Content Customization
Modify the text, images, and information displayed:
- Headings and descriptive text
- Button labels and call-to-actions
- Error and success messages
- Product information and order details display
- Company logo and branding elements
Layout Options
Control how the checkout appears on your page:
- Modal dialog or inline embed
- Responsive behavior for different screen sizes
- Single-page or multi-step checkout flow
- Sidebar or full-width layout
Functional Customization
Configure behavior and available options:
- Supported cryptocurrencies
- Required customer information fields
- Shipping address collection (optional)
- Custom fields for additional information
- Payment method ordering and display
Advanced Features
ZenPay Custom Checkout includes several advanced features to enhance your payment processing:
Dynamic Pricing
Update prices in real-time based on current cryptocurrency exchange rates, ensuring accurate pricing regardless of market fluctuations.
// Example using the ZenPay JavaScript SDK
const zenpay = new ZenPay('pk_test_YourPublicKey');
// Get real-time exchange rates
async function updatePrice() {
const basePrice = 99.99; // Your product price in USD
const customerCurrency = 'BTC'; // Customer's chosen crypto
try {
// Get the current exchange rate
const exchangeRate = await zenpay.getExchangeRate({
base_currency: 'USD',
quote_currency: customerCurrency
});
// Calculate the crypto amount
const cryptoAmount = basePrice / exchangeRate.rate;
// Update the UI
document.getElementById('crypto-price').textContent =
cryptoAmount.toFixed(8) + ' ' + customerCurrency;
// If price changes significantly during checkout, you can prompt the user
if (Math.abs(previousRate - exchangeRate.rate) / previousRate > 0.05) {
showRateChangeAlert(previousRate, exchangeRate.rate);
}
return cryptoAmount;
} catch (error) {
console.error('Error fetching exchange rate:', error);
}
}
Custom Fields
Collect additional information during checkout, such as shipping preferences, account details, or other customer-specific data.
// When creating a checkout session, define custom fields
const session = await zenpay.createCheckoutSession({
amount: 99.99,
currency: 'USD',
product_name: 'Premium Membership',
custom_fields: [
{
key: 'shipping_preference',
label: 'Shipping Method',
type: 'select',
options: [
{ value: 'standard', label: 'Standard (3-5 days)' },
{ value: 'express', label: 'Express (1-2 days)', price_adjustment: 10.00 }
],
required: true
},
{
key: 'gift_wrap',
label: 'Gift Wrap',
type: 'boolean',
price_adjustment: 5.00
},
{
key: 'gift_message',
label: 'Gift Message',
type: 'textarea',
max_length: 200,
required: false,
conditional: {
field: 'gift_wrap',
value: true
}
}
]
});
Multi-currency Support
Allow customers to pay in their preferred cryptocurrency while you receive settlement in your chosen currency.
// Support multiple cryptocurrencies in your checkout
const session = await zenpay.createCheckoutSession({
amount: 99.99,
currency: 'USD',
product_name: 'Premium Membership',
supported_payment_methods: [
'BTC', // Bitcoin
'ETH', // Ethereum
'USDC', // USD Coin
'SOL', // Solana
'DOGE' // Dogecoin
],
// Optionally specify your settlement preference
settlement_currency: 'USDC', // Or 'USD' for fiat settlement
display_prices: true, // Show equivalent prices in all currencies
});
Subscription Billing
Set up recurring payments for subscription-based products or services.
// Creating a subscription using the ZenPay API
const subscription = await zenpay.subscriptions.create({
customer_email: 'customer@example.com',
amount: 19.99,
currency: 'USD',
product_name: 'Monthly Premium Plan',
billing_cycle: {
interval: 'month',
count: 1
},
payment_methods: ['BTC', 'ETH', 'USDC'],
trial_period_days: 14, // Optional free trial
metadata: {
plan_id: 'premium_monthly',
user_id: 'user_123456'
}
});
// Then show the checkout for the first payment
zenpay.showCheckout(subscription.id);
Testing Your Integration
Before going live, thoroughly test your Custom Checkout integration using ZenPay's test environment:
Test Mode
All ZenPay accounts have access to a test environment that mimics production without processing real payments.
Test Credential | Format | Example |
---|---|---|
Test API Key | Starts with pk_test_ | pk_test_abcdef123456 |
Test Secret Key | Starts with sk_test_ | sk_test_abcdef123456 |
Test Bitcoin Address | Testnet address | tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0g |
Test Ethereum Address | Testnet address | 0xb794f5ea0ba39494ce839613fffba74279579268 |
Testing Scenarios
- Successful payments using test cryptocurrency addresses
- Failed payments by using invalid wallet addresses
- Timeout scenarios by leaving payments incomplete
- Webhook notifications for payment status changes
- Subscription creation and recurring billing
Best Practices
Follow these recommendations to ensure a successful Custom Checkout implementation:
Implementation Recommendations
- 1
Implement webhooks - Always use webhooks to track payment status, even if you're also using client-side events. This ensures you don't miss payment confirmations if a customer closes their browser.
- 2
Keep checkout simple - Minimize the number of steps and required fields to reduce friction and improve conversion rates.
- 3
Optimize for mobile - Ensure your checkout experience works well on mobile devices, as many crypto users prefer mobile wallets.
- 4
Versioning strategy - When customizing the checkout, maintain a consistent versioning strategy to make updates easier in the future.
- 5
Error handling - Implement comprehensive error handling for both client-side and server-side errors, with clear user-friendly messages.
Next Steps
After implementing Custom Checkout, explore these related features: