Integrate via SDK

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: 'john@example.com',
        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: 'john@example.com',
                    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: 'john@example.com'
    },
    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

Security

Always use your public API key (starts with pk_) in client-side code
Never expose your secret API key
Use HTTPS in production

User Experience

Show loading states during initialization and payment processing
Handle network errors gracefully
Test the integration thoroughly in sandbox before going live

Performance

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

Learn about the Hosted Payment Page integration
Review Error Handling best practices
Check the API Reference for complete API documentation

Getting Started

Essentials

Features

Testing

Guides

API Reference

Payment Orchestrator API

Link Product API

Integrate via SDK

Overview

Installation

Quick Start

Integration Steps

Step 1: Initialize the SDK

Step 2: Load the Payment Form

Step 3: Process the Payment

Step 4: Clean Up (Optional)

Complete Example

API Reference

`Cheqpay.Checkout.init(config)`

`Cheqpay.Checkout.load(options)`

`Cheqpay.Checkout.authorize(paymentDetails, callback)`

`Cheqpay.Checkout.destroy()`

Error Handling

Best Practices

Next Steps

​Overview

​Installation

​Quick Start

​Integration Steps

​Step 1: Initialize the SDK

​Step 2: Load the Payment Form

​Step 3: Process the Payment

​Step 4: Clean Up (Optional)

​Complete Example

​API Reference

​Cheqpay.Checkout.init(config)

​Cheqpay.Checkout.load(options)

​Cheqpay.Checkout.authorize(paymentDetails, callback)

​Cheqpay.Checkout.destroy()

​Error Handling

​Best Practices

​Next Steps

Overview

Installation

Quick Start

Integration Steps

Step 1: Initialize the SDK

Step 2: Load the Payment Form

Step 3: Process the Payment

Step 4: Clean Up (Optional)

Complete Example

API Reference

`Cheqpay.Checkout.init(config)`

`Cheqpay.Checkout.load(options)`

`Cheqpay.Checkout.authorize(paymentDetails, callback)`

`Cheqpay.Checkout.destroy()`

Error Handling

Best Practices

Next Steps