> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cheqpay.mx/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrate via SDK
> Integrate Cheqpay Checkout directly into your website using our JavaScript 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:
```html theme={null}
```
The SDK will be available globally as `Cheqpay` after the script loads.
## Quick Start
Here's a minimal example to get you started:
```html theme={null}
Cheqpay Checkout
```
## Integration Steps
### Step 1: Initialize the SDK
Before using any SDK methods, you must initialize it with your API key and environment:
```javascript theme={null}
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:
```javascript theme={null}
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:
```javascript theme={null}
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:
```javascript theme={null}
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:
```html theme={null}
Cheqpay Checkout Example
```
## 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:**
```javascript theme={null}
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:**
```javascript theme={null}
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:**
```javascript theme={null}
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:**
```javascript theme={null}
Cheqpay.Checkout.destroy();
```
## Error Handling
Always handle errors in the `authorize` callback:
```javascript theme={null}
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](/guides/testing).
## Next Steps
* Learn about the [Hosted Payment Page](/features/hosted-payment-page) integration
* Review [Error Handling](/guides/error-handling) best practices
* Check the [API Reference](/api-reference/introduction) for complete API documentation