SDK JS - Es Module
The EcartPay SDK v2 provides a complete interface for integrating payments into your web application. This documentation will guide you through installation, configuration, and usage of all available features.
📦 EcartPay JavaScript SDK – Integration Guide
A simple and powerful JavaScript SDK to integrate payment functionality into your website or application using EcartPay. This guide will help you quickly set up the SDK, configure payment options, and process transactions securely.
🚀 Installation
1. Include the SDK
To begin, add the following <script> tag to your HTML page. This includes the EcartPay SDK from either the production or sandbox environment:
<!-- Production Environment -->
<script src="https://ecartpay.com/sdk/pay.js"></script>
<!-- Sandbox Environment (For testing purposes) -->
<script src="https://sandbox.ecartpay.com/sdk/pay.js"></script>
Use the sandbox version for development and testing. Switch to the production script only when you're ready to go live.
⚡ Quick Start
2. Initialize a Basic Checkout
Use Pay.Checkout.create() to trigger the checkout process and open the payment interface:
const result = await Pay.Checkout.create({
publicID: 'your_public_id_here',
order: {
// Customer information
email: '[email protected]',
first_name: 'John',
last_name: 'Doe',
phone: '5551234567',
// Order details
currency: 'USD',
items: [
{
name: 'Product 1',
price: 100.00,
quantity: 2
},
{
name: 'Shipping',
price: 50.00,
quantity: 1
}
]
}
});📋 Required Parameters
These fields are mandatory for initializing a transaction:
| Parameter | Type | Description |
|---|---|---|
publicID | string | Your unique EcartPay public identifier. Used to authenticate the merchant. |
order.email | string | Customer's email address. Used for sending receipts and notifications. |
order.first_name | string | Customer’s first name. |
order.last_name | string | Customer’s last name. |
order.phone | string | Customer’s contact number. Optional for verification. |
order.currency | string | Currency code in ISO format (e.g., USD, MXN, EUR). |
order.items | array | List of items being purchased, each with name, price, and quantity. |
🧾 Items Structure
Each item object within the items array should follow this structure:
{
name: 'Product name', // (string) Name or description of the item.
price: 100.00, // (number) Unit price of the item in the selected currency.
quantity: 1 // (number) Number of units of the item.
}🧩 Optional Parameters
Enhance the checkout experience using optional fields:
| Parameter | Type | Description |
|---|---|---|
order.shipping_address | object | Full shipping address for physical product deliveries. |
order.available_payment_methods | array | List of allowed payment methods (e.g., card, cash, transfer). |
📦 Shipping Address
To collect delivery information for physical goods, include the shipping_address object:
shipping_address: {
first_name: 'John',
last_name: 'Doe',
address1: 'Main Street 123',
city: 'New York',
state: {
code: 'NY',
name: 'New York'
},
country: {
code: 'US',
name: 'United States'
},
postal_code: '10001'
}
Note: Providing accurate shipping data improves order processing and delivery times.
💳 Payment Methods
You can control which payment options are presented to the customer by specifying available_payment_methods:
available_payment_methods: ['card', 'cash', 'transfer']Supported Methods:
card– Credit and debit card payments.cash– Cash-based payments through supported outlets.transfer– Direct bank transfers.
Best Practice: Restrict methods based on customer location or transaction type.
✅ Best Practices & Recommendations
- ✅ Always load the SDK over HTTPS to ensure secure transmission.
- ✅ Validate all customer input before invoking the checkout.
- ✅ Use sandbox credentials during development to avoid unintended charges.
- ✅ Handle the promise returned by
Pay.Checkout.create()to manage success and failure states. - ✅ Consult the [EcartPay API Reference] for more advanced configurations.
🧪 Complete Example
Below is a complete HTML example implementing EcartPay Checkout with TailwindCSS and Alpine.js:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Checkout - eCartPay</title>
<script src="https://cdn.tailwindcss.com"></script>
<script src="https://unpkg.com/[email protected]/dist/cdn.min.js" defer></script>
<script src="https://sandbox.ecartpay.com/sdk/pay.js" onload="window.paySDKLoaded = true; window.dispatchEvent(new Event('paySDKReady'))"></script>
<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
<style>
body {
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}
.stripe-input {
transition: all 0.15s ease;
}
.stripe-input:focus {
outline: none;
border-color: #6772e5;
box-shadow: 0 0 0 1px #6772e5;
}
.loading {
animation: spin 1s linear infinite;
}
@keyframes spin {
from { transform: rotate(0deg); }
to { transform: rotate(360deg); }
}
.gradient-bg {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}
.card-shadow {
box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
}
.hover-lift {
transition: transform 0.2s ease, box-shadow 0.2s ease;
}
.hover-lift:hover {
transform: translateY(-2px);
box-shadow: 0 10px 25px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
}
</style>
</head>
<body class="bg-gray-50 min-h-screen">
<!-- Loading state while SDK loads -->
<div x-data="checkoutForm()" x-show="!sdkReady" class="min-h-screen flex items-center justify-center">
<div class="text-center">
<div class="w-16 h-16 border-4 border-blue-200 border-t-blue-600 rounded-full animate-spin mx-auto mb-4"></div>
<p class="text-gray-600">Loading checkout...</p>
</div>
</div>
<!-- Main checkout content -->
<div x-data="checkoutForm()" x-show="sdkReady" class="min-h-screen">
<!-- Header -->
<header class="bg-white border-b border-gray-200">
<div class="max-w-6xl mx-auto px-4 sm:px-6 lg:px-8">
<div class="flex justify-between items-center h-16">
<div class="flex items-center">
<div class="w-8 h-8 bg-gradient-to-r from-blue-600 to-purple-600 rounded-lg flex items-center justify-center mr-3">
<i class="fas fa-shopping-cart text-white text-sm"></i>
</div>
<span class="text-xl font-semibold text-gray-900">eCartPay</span>
</div>
<div class="flex items-center space-x-4">
<div class="flex items-center text-sm text-gray-500">
<i class="fas fa-lock mr-2"></i>
<span>Secure checkout</span>
</div>
</div>
</div>
</div>
</header>
<div class="max-w-6xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
<div class="grid lg:grid-cols-2 gap-12">
<!-- Checkout Form -->
<div class="lg:order-1">
<div class="bg-white rounded-xl card-shadow p-8">
<div class="mb-8">
<h1 class="text-2xl font-semibold text-gray-900 mb-2">Complete your purchase</h1>
<p class="text-gray-600">Enter your payment details to continue</p>
</div>
<form @submit.prevent="processPayment" class="space-y-6">
<!-- Email -->
<div>
<label class="block text-sm font-medium text-gray-700 mb-2">Email address</label>
<input
type="email"
x-model="form.email"
placeholder="[email protected]"
class="w-full px-4 py-3 border border-gray-300 rounded-lg stripe-input focus:ring-0"
required
>
</div>
<!-- Personal Information -->
<div class="grid grid-cols-2 gap-4">
<div>
<label class="block text-sm font-medium text-gray-700 mb-2">First name</label>
<input
type="text"
x-model="form.firstName"
placeholder="First name"
class="w-full px-4 py-3 border border-gray-300 rounded-lg stripe-input focus:ring-0"
required
>
</div>
<div>
<label class="block text-sm font-medium text-gray-700 mb-2">Last name</label>
<input
type="text"
x-model="form.lastName"
placeholder="Last name"
class="w-full px-4 py-3 border border-gray-300 rounded-lg stripe-input focus:ring-0"
required
>
</div>
</div>
<!-- Phone -->
<div>
<label class="block text-sm font-medium text-gray-700 mb-2">Phone number</label>
<input
type="tel"
x-model="form.phone"
placeholder="+1 (555) 123-4567"
class="w-full px-4 py-3 border border-gray-300 rounded-lg stripe-input focus:ring-0"
required
>
</div>
<!-- Shipping Address -->
<div class="border-t border-gray-200 pt-6">
<h3 class="text-lg font-medium text-gray-900 mb-4">Shipping address</h3>
<div class="space-y-4">
<div>
<label class="block text-sm font-medium text-gray-700 mb-2">Country or region</label>
<select class="w-full px-4 py-3 border border-gray-300 rounded-lg stripe-input focus:ring-0">
<option>United States</option>
<option>Canada</option>
<option>Mexico</option>
</select>
</div>
<div>
<label class="block text-sm font-medium text-gray-700 mb-2">Address</label>
<input
type="text"
x-model="form.address"
placeholder="Address"
class="w-full px-4 py-3 border border-gray-300 rounded-lg stripe-input focus:ring-0"
required
>
</div>
<div class="grid grid-cols-2 gap-4">
<div>
<input
type="text"
x-model="form.city"
placeholder="City"
class="w-full px-4 py-3 border border-gray-300 rounded-lg stripe-input focus:ring-0"
required
>
</div>
<div>
<input
type="text"
x-model="form.state"
placeholder="State"
class="w-full px-4 py-3 border border-gray-300 rounded-lg stripe-input focus:ring-0"
required
>
</div>
</div>
<div>
<input
type="text"
x-model="form.zipCode"
placeholder="ZIP code"
class="w-full px-4 py-3 border border-gray-300 rounded-lg stripe-input focus:ring-0"
required
>
</div>
</div>
</div>
<!-- Security Notice -->
<div class="text-center text-sm text-gray-500">
<i class="fas fa-shield-alt mr-1"></i>
Your payment information is encrypted and secure
</div>
</form>
</div>
</div>
<!-- Order Summary -->
<div class="lg:order-2">
<div class="bg-white rounded-xl card-shadow p-8 sticky top-8">
<h2 class="text-xl font-semibold text-gray-900 mb-6">Order summary</h2>
<!-- Product Items -->
<div class="space-y-4 mb-6">
<div class="flex items-center justify-between py-3">
<div class="flex items-center">
<div class="w-12 h-12 bg-gray-100 rounded-lg flex items-center justify-center mr-4">
<i class="fas fa-tshirt text-gray-600"></i>
</div>
<div>
<h3 class="font-medium text-gray-900">Premium T-Shirt</h3>
<p class="text-sm text-gray-500">Size: L • Color: Blue</p>
</div>
</div>
<span class="font-medium text-gray-900">$599 MXN</span>
</div>
<div class="flex items-center justify-between py-3">
<div class="flex items-center">
<div class="w-12 h-12 bg-gray-100 rounded-lg flex items-center justify-center mr-4">
<i class="fas fa-shipping-fast text-gray-600"></i>
</div>
<div>
<h3 class="font-medium text-gray-900">Express shipping</h3>
<p class="text-sm text-gray-500">2-3 business days</p>
</div>
</div>
<span class="font-medium text-gray-900">$119 MXN</span>
</div>
</div>
<!-- Totals -->
<div class="border-t border-gray-200 pt-4 space-y-3">
<div class="flex justify-between text-sm">
<span class="text-gray-600">Subtotal</span>
<span class="text-gray-900">$599 MXN</span>
</div>
<div class="flex justify-between text-sm">
<span class="text-gray-600">Shipping</span>
<span class="text-gray-900">$119 MXN</span>
</div>
<div class="flex justify-between text-sm">
<span class="text-gray-600">Tax</span>
<span class="text-gray-900">$59 MXN</span>
</div>
<div class="flex justify-between text-lg font-semibold border-t border-gray-200 pt-3">
<span class="text-gray-900">Total</span>
<span class="text-gray-900">$777 MXN</span>
</div>
</div>
<!-- Submit Button -->
<button
@click="processPayment"
:disabled="loading"
class="w-full bg-gradient-to-r from-blue-600 to-purple-600 text-white py-4 px-6 rounded-lg font-medium hover:from-blue-700 hover:to-purple-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed transition-all duration-200 hover-lift mt-6"
>
<span x-show="!loading" class="flex items-center justify-center">
<i class="fas fa-lock mr-2"></i>
Pay $777 MXN
</span>
<span x-show="loading" class="flex items-center justify-center">
<i class="fas fa-spinner loading mr-2"></i>
Processing...
</span>
</button>
</div>
</div>
</div>
</div>
</div>
<script>
function checkoutForm() {
return {
loading: false,
sdkReady: false,
form: {
email: '[email protected]',
firstName: 'Alejandro',
lastName: 'de la Cruz',
phone: '9123688056',
address: 'Belisario Dominguez 2470',
city: 'Monterrey',
state: 'Nuevo Leon',
zipCode: '64060'
},
async processPayment() {
this.loading = true;
try {
await Pay.Checkout.create({
publicID: 'pub6180483beab9d945a86da3bf',
order: {
email: this.form.email,
first_name: this.form.firstName,
last_name: this.form.lastName,
phone: this.form.phone,
currency: 'MXN',
items: [
{
name: 'Premium T-Shirt',
price: 599,
quantity: 1,
},
{
name: 'Express shipping',
price: 119,
quantity: 1,
}
],
shipping_address: {
first_name: this.form.firstName,
last_name: this.form.lastName,
address1: this.form.address,
country: {
code: 'MX',
name: 'Mexico'
},
state: {
code: 'NL',
name: this.form.state
},
city: this.form.city,
postal_code: this.form.zipCode,
},
//available_payment_methods: ['card', 'cash', 'transfer'] //You can specify the payment methods that will be available to the customer
}
});
} catch (error) {
console.error('Payment failed:', error);
// Handle error - you can add error display here
} finally {
this.loading = false;
}
},
showSuccess() {
// Create success modal
const modal = document.createElement('div');
modal.className = 'fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center z-50';
modal.innerHTML = `
<div class="bg-white rounded-xl p-8 max-w-md w-full mx-4 text-center">
<div class="w-16 h-16 bg-green-100 rounded-full flex items-center justify-center mx-auto mb-4">
<i class="fas fa-check text-green-600 text-2xl"></i>
</div>
<h3 class="text-xl font-semibold text-gray-900 mb-2">Payment successful!</h3>
<p class="text-gray-600 mb-6">Your order has been processed and you'll receive a confirmation email shortly.</p>
<button onclick="this.closest('.fixed').remove()" class="w-full bg-gradient-to-r from-blue-600 to-purple-600 text-white py-3 px-4 rounded-lg hover:from-blue-700 hover:to-purple-700 transition-all duration-200">
Continue shopping
</button>
</div>
`;
document.body.appendChild(modal);
},
init() {
// Wait for Pay SDK to be loaded
if (window.paySDKLoaded) {
this.sdkReady = true;
} else {
window.addEventListener('paySDKReady', () => {
this.sdkReady = true;
});
}
}
}
}
</script>
</body>
</html>
You can copy and paste this into an.htmlfile and run it locally to test a full checkout flow.
📞 Need Help?
For further assistance or detailed integration support, please contact our support team at [email protected] or visit our ecartpay.com .
Updated 8 days ago