Custom Checkout

Integrate a seamless cryptocurrency checkout experience directly into your website or application.

Last updated: June 22, 2023
Next: Webhooks

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.

No redirects to external pages
Consistent brand experience
Higher conversion rates

Complete Customization

Tailor the checkout UI to match your website design.

Custom styling options
Configurable UI components
Flexible layout options

Developer-Friendly

Built with developers in mind for easy integration.

Comprehensive SDK
React, Vue, and Angular support
Detailed documentation

Secure By Design

Security built in at every layer.

PCI compliant infrastructure
No cryptocurrency data stored on your server
End-to-end encryption

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
Drop-in Checkout Example
// 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
React Custom UI Integration
// 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:

1

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
2

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
3

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
4

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.

Dynamic Pricing Example
// 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.

Custom Fields Example
// 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.

Multi-currency Example
// 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.

Subscription Setup Example
// 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 CredentialFormatExample
Test API KeyStarts with pk_test_pk_test_abcdef123456
Test Secret KeyStarts with sk_test_sk_test_abcdef123456
Test Bitcoin AddressTestnet addresstb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0g
Test Ethereum AddressTestnet address0xb794f5ea0ba39494ce839613fffba74279579268

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:

Webhooks

Set up real-time payment notifications for your backend

API Reference

Browse the complete API documentation

Was this helpful?