@silapay/transparent-checkout

v1.0.0

Published

10 months ago

A Vue.js library for transparent checkout with multiple payment methods

0High
0Medium
0Low

checkout_silapay

vue typescript checkout payment pix credit-card transparent-checkout embed widget silapay brazil fintech

@silapay/transparent-checkout

Uma biblioteca Vue.js moderna para checkout transparente com múltiplos métodos de pagamento, incluindo PIX, Cartão de Crédito e Boleto Bancário.

✨ Características

🚀 Componente Vue 3 pronto para uso
💳 Múltiplos métodos de pagamento (PIX, Cartão, Boleto)
📱 Totalmente responsivo e otimizado para mobile
🎨 Personalizável com cores e logo da sua marca
🔒 Seguro com validações integradas
📦 TypeScript com tipagem completa
🌐 Fácil integração em HTML puro ou Vue.js

🚀 Instalação

# npm
npm install @silapay/transparent-checkout

# yarn
yarn add @silapay/transparent-checkout

# pnpm
pnpm add @silapay/transparent-checkout

📦 Importação dos Estilos

⚠️ Importante: A biblioteca inclui estilos CSS que devem ser importados:

import '@silapay/transparent-checkout/style.css'

⚡ Início Rápido

Instale a biblioteca:

npm install @silapay/transparent-checkout

Use diretamente no HTML (via CDN):

<script src="https://unpkg.com/@silapay/transparent-checkout@latest/dist/index.umd.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@silapay/transparent-checkout@latest/dist/style.css">

Configure seu checkout:

const config = {
  cart: {
    id: 'cart-123',
    amountTotal: 99.99,
    currency: 'BRL',
    items: [{ id: '1', name: 'Produto', price: 99.99, quantity: 1 }],
    paymentMethods: ['pix', 'creditCard', 'billet']
  },
  backendUrl: 'https://api.seubackend.com'
}

Veja os exemplos completos na pasta example/ deste repositório!

🎯 Guia de Uso

🔧 Integração em HTML Puro (Recomendado para iniciantes)

<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Checkout SilaPay</title>
    <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
    <script src="https://unpkg.com/@silapay/transparent-checkout@latest/dist/index.umd.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/@silapay/transparent-checkout@latest/dist/style.css">
</head>
<body>
    <div id="checkout"></div>

    <script>
        const checkoutConfig = {
            cart: {
                id: 'cart-123',
                amountTotal: 99.99,
                currency: 'BRL',
                items: [{
                    id: '1',
                    name: 'Produto Exemplo',
                    price: 99.99,
                    quantity: 1,
                    description: 'Descrição do produto'
                }],
                paymentMethods: ['pix', 'creditCard', 'billet']
            },
            backendUrl: 'https://api.seubackend.com',
            onPaymentSuccess: (data) => {
                console.log('Pagamento aprovado:', data)
                alert('Pagamento realizado com sucesso!')
            },
            onPaymentError: (error) => {
                console.error('Erro no pagamento:', error)
                alert('Erro no pagamento: ' + error.message)
            }
        }

        SilaPayTransparentCheckout.createTransparentCheckout('#checkout', checkoutConfig)
    </script>
</body>
</html>

🔧 Como Plugin Vue.js

import { createApp } from 'vue'
import TransparentCheckout from '@silapay/transparent-checkout'
import '@silapay/transparent-checkout/style.css'

const app = createApp(App)
app.use(TransparentCheckout)

🔧 Importação Direta do Componente

<template>
  <TransparentCheckout :config="checkoutConfig" />
</template>

<script setup>
import { TransparentCheckout } from '@silapay/transparent-checkout'
import '@silapay/transparent-checkout/style.css'

const checkoutConfig = {
  cart: {
    id: 'cart-123',
    amountTotal: 99.99,
    currency: 'BRL',
    items: [
      {
        id: '1',
        name: 'Produto Exemplo',
        price: 99.99,
        quantity: 1,
        description: 'Descrição do produto'
      }
    ],
    paymentMethods: ['pix', 'creditCard', 'billet']
  },
  backendUrl: 'https://api.seubackend.com',
  onPaymentSuccess: (data) => {
    console.log('Pagamento realizado com sucesso:', data)
  },
  onPaymentError: (error) => {
    console.error('Erro no pagamento:', error)
  }
}
</script>

🔧 Factory Function (Integração Dinâmica)

import { createTransparentCheckout } from '@silapay/transparent-checkout'

// Cria e monta o checkout em um elemento específico
const checkout = await createTransparentCheckout('#checkout-container', {
  cart: {
    id: 'cart-123',
    amountTotal: 99.99,
    currency: 'BRL',
    items: [/* seus produtos */],
    paymentMethods: ['pix', 'creditCard', 'billet']
  },
  backendUrl: 'https://api.seubackend.com'
})

⚙️ Configuração

CheckoutConfig

interface CheckoutConfig {
  cart: Cart
  customization?: CheckoutCustomization
  maxInstallments?: number
  backendUrl: string
  onPaymentSuccess?: (data: PaymentResponse) => void
  onPaymentError?: (error: any) => void
  isEmbedded?: boolean
  devMode?: {
    apiKey: string
    secretKey: string
    postbackUrl: string
    apiEndpoint?: string
    proxyUrl?: string
  }
}

Cart

interface Cart {
  id: string
  amountTotal: number
  shippingCost?: number
  tax?: Tax
  discount?: number
  currency: string
  items: CartItem[]
  paymentMethods: string[]
}

interface CartItem {
  id: string
  name: string
  price: number
  quantity: number
  description?: string
  image?: string
}

Customização

interface CheckoutCustomization {
  isDarkMode?: boolean
  identityColorLight?: string
  identityColorDark?: string
  logoUrl?: string
  identityUrl?: string
  isTimerActive?: boolean
  acceptPayments?: PaymentMethod[]
}

🎨 Personalização

Cores e Tema

const customization = {
  isDarkMode: false,
  identityColorLight: '#007bff',
  identityColorDark: '#0056b3',
  logoUrl: 'https://example.com/logo.png',
  identityUrl: 'https://example.com'
}

Métodos de Pagamento

const acceptPayments = [
  { id: 'pix', label: 'PIX', active: true },
  { id: 'creditCard', label: 'Cartão de Crédito', active: true },
  { id: 'billet', label: 'Boleto', active: false }
]

🔐 Segurança

Configuração de Produção (Recomendada)

Para uso em produção, configure apenas a URL do seu backend:

const config = {
  backendUrl: 'https://api.seubackend.com',
  cart: {
    // dados do carrinho
  }
}

Modo de Desenvolvimento (Apenas para Testes)

⚠️ ATENÇÃO: Nunca use em produção!

const config = {
  backendUrl: 'https://api.seubackend.com',
  devMode: {
    apiKey: 'sua-api-key',
    secretKey: 'sua-secret-key',
    postbackUrl: 'https://seu-webhook.com/postback',
    proxyUrl: 'http://localhost:3001' // para contornar CORS
  },
  cart: {
    // dados do carrinho
  }
}

📱 Responsividade

O componente é totalmente responsivo e se adapta automaticamente a diferentes tamanhos de tela:

Desktop: Layout em duas colunas (produtos + formulários)
Mobile: Layout empilhado com navegação por etapas
Embedded: Modo otimizado para iframe

🛠 Métodos de Pagamento Suportados

PIX: Pagamento instantâneo via QR Code
Cartão de Crédito: Visa, Mastercard, Elo, etc.
Boleto Bancário: Tradicional boleto brasileiro

📋 Callbacks

onPaymentSuccess

Chamado quando o pagamento é processado com sucesso:

onPaymentSuccess: (data) => {
  console.log('Transaction ID:', data.txId)
  console.log('Payment Method:', data.method)
  console.log('Amount:', data.amount)

  // Redirecionar usuário ou mostrar confirmação
  window.location.href = '/success'
}

onPaymentError

Chamado quando ocorre erro no pagamento:

onPaymentError: (error) => {
  console.error('Erro:', error.message)

  // Mostrar mensagem de erro ao usuário
  alert('Erro no pagamento: ' + error.message)
}

🔧 Composables

A biblioteca exporta composables úteis para validação e pagamento:

import { useValidation, usePayment } from '@silapay/transparent-checkout'

// Validação de documentos
const { validateCPF, validateCNPJ, validateEmail } = useValidation()

// Processamento de pagamentos
const { processPayment, isLoading } = usePayment()

🌐 Compatibilidade

Vue: 3.0+
TypeScript: Suporte completo
Navegadores: Modernos (ES2015+)
Node.js: 14+

📄 Licença

MIT

🤝 Contribuição

Contribuições são bem-vindas! Consulte o repositório no GitHub para mais informações.

� Exemplos Práticos

Na pasta example/ você encontra exemplos completos:

🚀 Exemplo Simples (simple.html) - Integração básica em 5 minutos
🎯 Exemplo Completo (index.html) - Demo interativa com todas as funcionalidades
📖 Documentação (README.md) - Guia detalhado dos exemplos

# Para testar os exemplos localmente
git clone https://github.com/silabank/sdk-npm.git
cd sdk-npm/example
npx serve .  # ou abra index.html diretamente no navegador

�📞 Suporte

Para dúvidas ou suporte, entre em contato:

📧 Email: [email protected]
🐛 Issues: GitHub Issues
💬 Discussões: GitHub Discussions

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@silapay/transparent-checkout

✨ Características

🚀 Instalação

📦 Importação dos Estilos

⚡ Início Rápido

🎯 Guia de Uso

🔧 Integração em HTML Puro (Recomendado para iniciantes)

🔧 Como Plugin Vue.js

🔧 Importação Direta do Componente

🔧 Factory Function (Integração Dinâmica)

⚙️ Configuração

CheckoutConfig

Cart

Customização

🎨 Personalização

Cores e Tema

Métodos de Pagamento

🔐 Segurança

Configuração de Produção (Recomendada)

Modo de Desenvolvimento (Apenas para Testes)

📱 Responsividade

🛠 Métodos de Pagamento Suportados

📋 Callbacks

onPaymentSuccess

onPaymentError

🔧 Composables

🌐 Compatibilidade

📄 Licença

🤝 Contribuição

� Exemplos Práticos

�📞 Suporte