JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 13
  • Score
    100M100P100Q76694F
  • License ISC

Easyflow JavaScript SDK - Documentation and TypeScript definitions. For production use, use the CDN script: https://easyflow-sdk.pages.dev/easyflow-sdk.min.js

Package Exports

  • @easyflow/javascript-sdk
  • @easyflow/javascript-sdk/package.json

Readme

Easyflow JavaScript SDK

Build Status Version License Tests Coverage

Easyflow Logo

Freedom to sell more, better and longer

Enterprise-grade JavaScript SDK for integration with the Easyflow payment processing platform with robust validation, comprehensive security and Brazilian compliance

Website Start Free Documentation

About Easyflow

Easyflow is a payment platform that facilitates the sales process of digital products and services in a simple and intuitive way. Our mission is to transform Digital Commerce by offering a complete sales structure to maximize your LTV.

Why Choose Easyflow?

  • Outstanding approval rate: 95% to 98% credit card approval rate
  • High conversion checkout: Fastest loading in the market
  • Simplified recurrence: Recurring payments with your own rules
  • Bank-level security: PCI Compliance and advanced encryption
  • Same-day withdrawal: Same day, no bureaucracy
  • Simple integrations: Webhooks and API with few clicks

Payment Methods

  • Credit Card: Highest approval rate in the market
  • PIX: Instant Brazilian payment
  • Bank Billet: For those who prefer to pay via bank

Main Features

  • Optimized checkout for maximum conversion
  • AI-powered sales recovery (up to 40% increase)
  • Upsell, downsell and cross-sell to increase average ticket
  • Automated payment splitting for co-producers
  • Smart metrics and insights in real time
  • Integration with CRM, ERPs and third-party platforms

Plans and Fees

Clear and fair rate: 6.99% + R$2.50

Try It Now

Test SDK

Experience the Easyflow SDK in action with our interactive demo

What is the Easyflow JavaScript SDK?

The Easyflow JavaScript SDK is the official tool for developers to integrate their applications with the Easyflow platform. With this SDK, you can:

  • Process payments securely and reliably
  • Manage customers with complete Brazilian data validation
  • Create offers and process orders automatically
  • Implement recurrence with custom rules
  • Integrate with any system via REST API

SDK Advantages

  • 100% Plug & Play: Works with any type of business
  • Brazilian Compliance: CPF/CNPJ, phone, address validation
  • Enterprise Security: Multiple layers of protection
  • High Performance: Optimized for production
  • Complete Documentation: Practical examples for all use cases

What's New in v2.1.11

Credit Card Token Validation Fix

  • Real Token Support: Now accepts real encrypted/ciphered credit card tokens
  • Flexible Format: Supports Base64, URL-safe, and mixed character tokens
  • Variable Length: Accepts tokens from 16 to 2048 characters
  • Enhanced Security: Maintains security while accepting real-world tokens
  • Backward Compatibility: Works with all existing token formats

Workflow Corrections

Workflow Corrections

  • GitHub Actions Fixed: Resolved release workflow permissions and SRI hash generation
  • CDN Deployment: Automated deployment to Cloudflare Pages working correctly
  • Release Automation: GitHub releases created automatically with proper SRI hashes
  • Build Process: Streamlined build and deployment pipeline

Hybrid Distribution Strategy

Hybrid Distribution Strategy

  • NPM Package: Contains only documentation and TypeScript definitions
  • CDN Scripts: Production-ready obfuscated builds via Cloudflare Pages
  • Enhanced Security: Code source protected while maintaining accessibility
  • Better UX: Easy discovery via NPM, secure usage via CDN

Security & Privacy Improvements

  • README Anonymization: Removed all personal information and sensitive data
  • Privacy Protection: No personal emails, URLs, or contact information exposed
  • Professional Documentation: Clean, business-focused documentation
  • NPM Safety: Safe for public NPM publication

Security & Privacy Improvements

  • README Anonymization: Removed all personal information and sensitive data
  • Privacy Protection: No personal emails, URLs, or contact information exposed
  • Professional Documentation: Clean, business-focused documentation
  • NPM Safety: Safe for public NPM publication

Test Suite Improvements

  • Test Coverage Optimization: Fixed all failing unit tests for complete 250 test coverage
  • Mock Structure Corrections: Updated test mocks to align with actual API response patterns
  • Customer Management Tests: Corrected mock structures for createCustomer and getCustomer methods
  • Credit Card Tests: Fixed mock data structures for addCreditCard and getCreditCard methods
  • Consistent Test Patterns: Standardized mock response structures across all endpoints

Test Suite Improvements

  • Test Coverage Optimization: Fixed all failing unit tests for complete 250 test coverage
  • Mock Structure Corrections: Updated test mocks to align with actual API response patterns
  • Customer Management Tests: Corrected mock structures for createCustomer and getCustomer methods
  • Credit Card Tests: Fixed mock data structures for addCreditCard and getCreditCard methods
  • Consistent Test Patterns: Standardized mock response structures across all endpoints

API Response Pattern Standardization

  • Customer Methods: Properly handle response.data.customer structure
  • Credit Card Methods: Correctly process response.data.creditCard structure
  • Order Methods: Maintain existing response.data pattern
  • Improved Reliability: Enhanced test reliability and maintainability

Enhanced ID Validation Support

  • Multiple ID Format Support: Now accepts UUID v4, UUID v7, and MongoDB ObjectId formats
  • UUID v4: Standard format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (y = 8,9,A,B)
  • UUID v7: Modern format xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx (y = 8,9,A,B)
  • MongoDB ObjectId: 24-character hexadecimal format 507f1f77bcf86cd799439011
  • Strict Validation: Rejects any other formats for enhanced security

Lovable Integration Fixes

  • Event System Implementation: Complete event system with on() and off() methods
  • Iframe Compatibility: Fixed iframe blocking issues for low-code platforms
  • Global Instance: window.easyflowSDK instance with all methods and events
  • Event Emissions: Automatic events for customerCreated, orderPlaced, and paymentProcessed

Quick Start

Installation

Add this script tag to your HTML:

<!-- Latest version -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>

<!-- Specific version -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.v2.1.11.min.js"></script>

Option 2: NPM Package (Documentation Only)

npm install @easyflow/javascript-sdk

Note: The NPM package contains only documentation. For production use, use the CDN script above.

Option 3: Direct Download

Download the latest obfuscated build from GitHub Releases.

Basic Usage

<!-- Load SDK via script tag -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>

<script>
    // Configure the global instance
    easyflowSDK.configure({
        businessId: 'demo-business-12345',
    })

    // Process a payment
    easyflowSDK
        .placeOrder('demo-offer-67890', {
            customer: {
                name: 'João Silva',
                email: 'joao@exemplo.com',
                document: {
                    type: 'CPF',
                    number: '12345678901',
                },
            },
            payments: [
                {
                    method: 'credit-card',
                    numberInstallments: 1,
                },
            ],
        })
        .then((orderId) => {
            console.log('Pedido criado:', orderId)
        })
        .catch((error) => {
            console.error('Erro ao criar pedido:', error.message)
        })
</script>

Method 2: Global Instance (For Low-Code Platforms & Simple HTML)

<!-- Load SDK via script tag -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>

<script>
    // Configure the global instance
    easyflowSDK.configure({
        businessId: 'demo-business-12345',
    })

    // Now you can use all methods directly
    easyflowSDK
        .createCustomer({
            name: 'Maria Silva',
            email: 'maria@exemplo.com',
            document: { type: 'CPF', number: '12345678901' },
        })
        .then((customer) => {
            console.log('Cliente criado:', customer)
        })
        .catch((error) => {
            console.error('Erro ao criar cliente:', error.message)
        })

    // Validation methods are always available
    if (easyflowSDK.validate.email('teste@exemplo.com')) {
        console.log('Email válido!')
    }

    // Listen to events
    easyflowSDK.on('customerCreated', (data) => {
        console.log('Evento cliente criado:', data)
    })
</script>

Features

Payment Processing

  • Credit Card: Highest approval rate with advanced fraud detection
  • PIX: Instant Brazilian payment method
  • Bank Billet: Traditional bank payment option
  • Recurring Payments: Custom subscription rules

Customer Management

  • Complete Validation: CPF/CNPJ, phone, address validation
  • Data Sanitization: XSS protection and input cleaning
  • Secure Storage: Encrypted sensitive data handling

Security Features

  • PCI Compliance: Bank-level security standards
  • Fingerprinting: Advanced fraud detection
  • Rate Limiting: Protection against abuse
  • Input Validation: Comprehensive data validation
  • Obfuscated Builds: Production builds are obfuscated for enhanced security
  • Controlled Distribution: Secure distribution via CDN and GitHub Releases

Low-Code Platform Support

  • Lovable Integration: Full compatibility with Lovable platform
  • Global Instance: window.easyflowSDK for easy integration
  • Event System: Built-in event handling for on() and off()
  • Validation Methods: Always available validation functions
  • Configuration: Simple setup with easyflowSDK.configure()

API Reference

Core Methods

placeOrder(offerId, data, headers)

Creates an order using an existing offer.

const orderId = await easyflowSDK.placeOrder('demo-offer-67890', {
    customer: {
        name: 'João Silva',
        email: 'joao@exemplo.com',
        document: { type: 'CPF', number: '12345678901' },
    },
    payments: [{ method: 'credit-card', numberInstallments: 1 }],
})

charge(data, headers)

Processes a direct charge without using an offer.

const orderId = await easyflowSDK.charge({
    items: [{ name: 'Produto Demo', price: 1000 }],
    payments: [{ method: 'pix', numberInstallments: 1 }],
})

encrypt(creditCardData, headers)

Encrypts credit card data for secure processing.

const token = await easyflowSDK.encrypt({
    number: '4111111111111111',
    holderName: 'João Silva',
    expirationMonth: '12',
    expirationYear: '2025',
    cvv: '123',
})

Customer Management

createCustomer(customerData, headers)

Creates a new customer.

const customer = await easyflowSDK.createCustomer({
    name: 'João Silva',
    email: 'joao@exemplo.com',
    document: { type: 'CPF', number: '12345678901' },
})

getCustomer(customerId, headers)

Retrieves customer information.

const customer = await easyflowSDK.getCustomer('demo-customer-12345')

updateCustomer(customerId, updateData, headers)

Updates existing customer information.

const result = await easyflowSDK.updateCustomer('demo-customer-12345', {
    name: 'João Atualizado',
    email: 'joao.atualizado@exemplo.com',
})

Credit Card Management

addCreditCard(customerId, creditCardToken, headers)

Adds a credit card to a customer.

const result = await easyflowSDK.addCreditCard(
    'demo-customer-12345',
    'encrypted-token-demo'
)

getCreditCard(customerId, creditCardId, headers)

Retrieves credit card information.

const creditCard = await easyflowSDK.getCreditCard(
    'demo-customer-12345',
    'demo-card-67890'
)

removeCreditCard(customerId, creditCardId, headers)

Removes a credit card from a customer.

const result = await easyflowSDK.removeCreditCard(
    'demo-customer-12345',
    'demo-card-67890'
)

Validation

ID Validation

All entity IDs must follow specific formats:

  • UUID v4: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (y = 8,9,A,B)
  • UUID v7: xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx (y = 8,9,A,B)
  • MongoDB ObjectId: 24-character hexadecimal format
// Valid IDs
Validator.validateOrderId('f47ac10b-58cc-4372-a567-0e02b2c3d479') // UUID v4
Validator.validateOrderId('01890b24-2d7f-7c3f-8f1a-123456789abc') // UUID v7
Validator.validateOrderId('507f1f77bcf86cd799439011') // MongoDB ObjectId

Data Validation

Comprehensive validation for all input data:

// Customer validation
Validator.validateCustomer({
    name: 'John Doe',
    email: 'john@example.com',
    document: { type: 'CPF', number: '12345678901' },
})

// Payment validation
Validator.validateOrderData({
    items: [{ name: 'Product', price: 1000 }],
    payments: [{ method: 'credit-card', numberInstallments: 1 }],
})

Events

The SDK provides an event system for monitoring operations:

// Listen to events
easyflowSDK.on('customerCreated', (data) => {
    console.log('Cliente criado:', data)
})

easyflowSDK.on('orderPlaced', (data) => {
    console.log('Pedido criado:', data)
})

easyflowSDK.on('paymentProcessed', (data) => {
    console.log('Pagamento processado:', data)
})

// Remove event listeners
easyflowSDK.off('customerCreated', callback)

Error Handling

The SDK provides comprehensive error handling:

try {
    const result = await easyflowSDK.placeOrder('demo-offer-67890', orderData)
} catch (error) {
    if (error.name === 'ValidationError') {
        console.log('Falha na validação:', error.message)
    } else if (error.name === 'NetworkError') {
        console.log('Erro de rede:', error.message)
    } else if (error.name === 'SecurityError') {
        console.log('Violação de segurança:', error.message)
    }
}

Configuration

SDK Options (CDN Implementation)

// Configure the global instance
easyflowSDK.configure({
    businessId: 'demo-business-12345',
    environment: 'production', // 'production' or 'sandbox'
    debug: false, // Enable debug logging
    timeout: 30000, // Request timeout in milliseconds
})

Environment Variables

EASYFLOW_BUSINESS_ID=demo-business-12345
EASYFLOW_ENVIRONMENT=production
EASYFLOW_DEBUG=false

Examples

Complete Checkout Flow

// 1. Create customer
const customer = await easyflowSDK.createCustomer({
    name: 'João Silva',
    email: 'joao@exemplo.com',
    document: { type: 'CPF', number: '12345678901' },
})

// 2. Encrypt credit card
const token = await easyflowSDK.encrypt({
    number: '4111111111111111',
    holderName: 'João Silva',
    expirationMonth: '12',
    expirationYear: '2025',
    cvv: '123',
})

// 3. Add credit card to customer
const creditCard = await easyflowSDK.addCreditCard(customer.id, token)

// 4. Place order
const orderId = await easyflowSDK.placeOrder('demo-offer-67890', {
    customer: customer,
    payments: [
        {
            method: 'credit-card',
            creditCardId: creditCard.creditCardId,
            numberInstallments: 1,
        },
    ],
})

PIX Payment

const orderId = await easyflowSDK.placeOrder('demo-offer-67890', {
    customer: {
        name: 'Maria Santos',
        email: 'maria@exemplo.com',
        document: { type: 'CPF', number: '98765432100' },
    },
    payments: [
        {
            method: 'pix',
            numberInstallments: 1,
        },
    ],
})

// Get PIX data
const pixData = await easyflowSDK.getPix(orderId)
console.log('PIX QR Code:', pixData.qrCode)

Bank Billet Payment

const orderId = await easyflowSDK.placeOrder('demo-offer-67890', {
    customer: {
        name: 'Pedro Costa',
        email: 'pedro@exemplo.com',
        document: { type: 'CPF', number: '11122233344' },
    },
    payments: [
        {
            method: 'bank-billet',
            numberInstallments: 1,
        },
    ],
})

// Get bank billet data
const bankBillet = await easyflowSDK.getBankBillet(orderId)
console.log('Bank Billet Link:', bankBillet.link)

Distribution & Security

Why CDN Scripts?

  • Obfuscated Builds: Production code is obfuscated for security
  • Controlled Access: Secure distribution via Cloudflare Pages
  • Version Control: Specific versions available for stability
  • Performance: Global CDN for fast loading

Available CDN URLs

<!-- Latest version -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>

<!-- Versioned (recommended for production) -->
<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.v2.1.8.min.js"></script>

<!-- With SRI (Subresource Integrity) -->
<script
    src="https://easyflow-sdk.pages.dev/easyflow-sdk.v2.1.11.min.js"
    integrity="sha384-[hash]"
    crossorigin="anonymous"
></script>

Browser Support

Node.js Support

  • Node.js: 18+
  • npm: 8+
  • yarn: 1.22+

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v2.1.11

  • Credit Card Token Fix: Accepts real encrypted/ciphered tokens from vault services
  • Flexible Validation: Supports Base64, URL-safe, and mixed character formats
  • Variable Length: Accepts tokens from 16 to 2048 characters
  • Enhanced Security: Maintains security while accepting real-world tokens
  • Backward Compatibility: Works with all existing token formats

v2.1.10

  • Workflow Fixed: Resolved GitHub Actions permissions and SRI hash generation
  • CDN Automation: Automated deployment to Cloudflare Pages working correctly
  • Release Process: GitHub releases created automatically with proper SRI hashes
  • Build Pipeline: Streamlined build and deployment process

v2.1.9

  • Hybrid Distribution: NPM for docs, CDN for secure obfuscated code
  • Enhanced Security: Code source protected while maintaining accessibility
  • Better UX: Easy discovery via NPM, secure usage via CDN
  • Documentation: Complete setup and usage instructions

v2.1.8

  • Security & Privacy: Anonymized README.md for safe NPM publication
  • Documentation: Removed all personal information and sensitive data
  • Professional: Clean, business-focused documentation

v2.1.7

  • Fixed all failing unit tests for complete 250 test coverage
  • Corrected mock structures for customer and credit card management
  • Standardized API response patterns across all endpoints
  • Enhanced test reliability and maintainability

v2.1.6

  • Enhanced ID validation with UUID v4, UUID v7, and MongoDB ObjectId support
  • Fixed iframe compatibility issues for low-code platforms
  • Implemented complete event system with on() and off() methods
  • Added global SDK instance for easier integration

v2.1.5

  • Added browser fingerprinting for enhanced security
  • Implemented automatic x-fingerprint-id header generation
  • Enhanced security validation and error handling
  • Improved documentation and examples

Built with ❤️ by the Easyflow Team