Skip to main content

​
Overview

The Cheqpay Checkout SDK allows you to embed a payment form directly into your website, giving you control over the checkout experience while Cheqpay handles the secure payment processing.
The SDK provides a seamless, embedded checkout experience without redirecting customers away from your site.

​
Installation

Include the Cheqpay Checkout SDK in your HTML page by adding the script tag: 
<script src="https://cdn.cheqpay.mx/v1/cheqpay.js" async></script>
The SDK will be available globally as Cheqpay after the script loads.

​
Quick Start

Here’s a minimal example to get you started: 
<!DOCTYPE html>
<html>
<head>
    <title>Cheqpay Checkout</title>
</head>
<body>
    <div id="payment-form"></div>
    
    <script src="https://cdn.cheqpay.mx/v1/cheqpay.js" async></script>
    <script>
        async function initializeCheckout() {
            // Initialize the SDK
            await Cheqpay.Checkout.init({
                apiKey: 'pk_test_your_key',
                environment: 'sandbox'
            });
            
            // Load the payment form
            await Cheqpay.Checkout.load({
                container: '#payment-form'
            });
        }
        
        // Initialize when SDK is ready
        if (window.Cheqpay) {
            initializeCheckout();
        } else {
            window.addEventListener('cheqpay-loaded', initializeCheckout);
        }
    </script>
</body>
</html>

​
Integration Steps

​
Step 1: Initialize the SDK

Before using any SDK methods, you must initialize it with your API key and environment: 
await Cheqpay.Checkout.init({
    apiKey: 'pk_test_your_key',  // Your public API key
    environment: 'sandbox'        // 'sandbox' or 'live'
});
Always use your public API key (starts with pk_) in the SDK. Never expose your secret API key in client-side code.

​
Step 2: Load the Payment Form

Load the payment form into a container element on your page: 
await Cheqpay.Checkout.load({
    container: '#payment-form'  // CSS selector for the container
});
The SDK will render a fully functional payment form inside the specified container.

​
Step 3: Process the Payment

When the customer submits the form, call authorize to process the payment: 
Cheqpay.Checkout.authorize({
    amount: 100.00,
    currency: 'MXN',
    description: 'Order #12345',
    merchantReference: 'order_12345',
    customer: {
        firstName: 'John',
        lastName: 'Doe',
        email: '[email protected]',
        phone: '+5215551234567'
    },
    billingAddress: {
        addressLine1: '123 Main St',
        addressLine2: 'Apt 4B',
        city: 'Mexico City',
        state: 'CDMX',
        postalCode: '01000',
        country: 'MX'
    }
}, (error, orderData) => {
    if (error) {
        console.error('Payment failed:', error);
        // Handle error (e.g., show error message to user)
    } else {
        console.log('Payment successful:', orderData);
        // Handle success (e.g., redirect to success page)
    }
});

​
Step 4: Clean Up (Optional)

When you’re done with the checkout (e.g., after payment completion or page navigation), clean up the SDK: 
Cheqpay.Checkout.destroy();
This removes all event listeners and DOM elements created by the SDK.

​
Complete Example

Here’s a complete example with error handling and user feedback: 
<!DOCTYPE html>
<html>
<head>
    <title>Cheqpay Checkout Example</title>
    <style>
        #payment-form {
            max-width: 600px;
            margin: 0 auto;
            padding: 20px;
        }
        .error {
            color: red;
            margin-top: 10px;
        }
        .success {
            color: green;
            margin-top: 10px;
        }
    </style>
</head>
<body>
    <div id="payment-form"></div>
    <div id="message"></div>
    
    <script src="https://cdn.cheqpay.mx/v1/cheqpay.js" async></script>
    <script>
        let checkoutInitialized = false;
        
        async function initializeCheckout() {
            if (checkoutInitialized) return;
            
            try {
                // Initialize SDK
                await Cheqpay.Checkout.init({
                    apiKey: 'pk_test_your_key',
                    environment: 'sandbox'
                });
                
                // Load payment form
                await Cheqpay.Checkout.load({
                    container: '#payment-form'
                });
                
                checkoutInitialized = true;
            } catch (error) {
                showMessage('Failed to initialize checkout: ' + error.message, 'error');
            }
        }
        
        function processPayment() {
            Cheqpay.Checkout.authorize({
                amount: 100.00,
                currency: 'MXN',
                description: 'Test Purchase',
                merchantReference: 'test_' + Date.now(),
                customer: {
                    firstName: 'John',
                    lastName: 'Doe',
                    email: '[email protected]',
                    phone: '+5215551234567'
                },
                billingAddress: {
                    addressLine1: '123 Main St',
                    city: 'Mexico City',
                    state: 'CDMX',
                    postalCode: '01000',
                    country: 'MX'
                }
            }, (error, orderData) => {
                if (error) {
                    showMessage('Payment failed: ' + error.message, 'error');
                } else {
                    showMessage('Payment successful! Order ID: ' + orderData.id, 'success');
                    // Redirect to success page or update UI
                }
            });
        }
        
        function showMessage(text, type) {
            const messageDiv = document.getElementById('message');
            messageDiv.textContent = text;
            messageDiv.className = type;
        }
        
        // Initialize when SDK is ready
        if (window.Cheqpay) {
            initializeCheckout();
        } else {
            window.addEventListener('cheqpay-loaded', initializeCheckout);
        }
        
        // Clean up on page unload
        window.addEventListener('beforeunload', () => {
            if (checkoutInitialized) {
                Cheqpay.Checkout.destroy();
            }
        });
    </script>
</body>
</html>

​
API Reference

​
Cheqpay.Checkout.init(config)

Initializes the SDK with your API key and environment. Parameters:
  • config.apiKey (string, required): Your public API key
  • config.environment (string, required): 'sandbox' or 'live'
Returns: Promise Example: 
await Cheqpay.Checkout.init({
    apiKey: 'pk_test_your_key',
    environment: 'sandbox'
});

​
Cheqpay.Checkout.load(options)

Loads the payment form into the specified container. Parameters:
  • options.container (string, required): CSS selector for the container element
Returns: Promise Example: 
await Cheqpay.Checkout.load({
    container: '#payment-form'
});

​
Cheqpay.Checkout.authorize(paymentDetails, callback)

Processes the payment with the provided payment details. Parameters:
  • paymentDetails (object, required):
    • amount (number): Payment amount
    • currency (string): Currency code (e.g., ‘MXN’, ‘USD’)
    • description (string, optional): Payment description
    • merchantReference (string, optional): Your order reference
    • customer (object, required):
      • firstName (string, required)
      • lastName (string, optional)
      • email (string, required)
      • phone (string, optional)
    • billingAddress (object, required):
      • addressLine1 (string, required)
      • addressLine2 (string, optional)
      • city (string, required)
      • state (string, optional)
      • postalCode (string, optional)
      • country (string, required)
  • callback (function, required): Callback function (error, orderData) => void
Example: 
Cheqpay.Checkout.authorize({
    amount: 100.00,
    currency: 'MXN',
    customer: {
        firstName: 'John',
        email: '[email protected]'
    },
    billingAddress: {
        addressLine1: '123 Main St',
        city: 'Mexico City',
        country: 'MX'
    }
}, (error, orderData) => {
    if (error) {
        console.error(error);
    } else {
        console.log('Success:', orderData);
    }
});

​
Cheqpay.Checkout.destroy()

Cleans up the SDK and removes all event listeners and DOM elements. Example: 
Cheqpay.Checkout.destroy();

​
Error Handling

Always handle errors in the authorize callback: 
Cheqpay.Checkout.authorize(paymentDetails, (error, orderData) => {
    if (error) {
        // Handle other errors
    } else {
        // Payment successful
    }
});

​
Best Practices

  • Always use your public API key (starts with pk_) in client-side code
  • Never expose your secret API key
  • Use HTTPS in production
  • Show loading states during initialization and payment processing
  • Handle network errors gracefully
  • Test the integration thoroughly in sandbox before going live
  • Load the SDK asynchronously to avoid blocking page render
  • Clean up the SDK when navigating away from the checkout page
  • Consider lazy loading the SDK only when needed
Test cards and scenarios are available in the Testing Guide.

​
Next Steps