SDK v1.1.0

Botões de Pagamento

SDK JavaScript para integrar o checkout Vpay em qualquer site

O que é o SDK de Botões?

Biblioteca JavaScript que adiciona automaticamente o botão de pagamento Vpay ao seu site

O SDK de Botões Vpay é uma biblioteca JavaScript que simplifica a integração do checkout em qualquer página HTML. Basta adicionar um container e o SDK cuida do resto: estilização, requisições e redirecionamento.

✨ Novidades v1.1.0

Produtos Novos: Adicione produtos com dados completos (nome, preço, imagem) sem pré-cadastro
Merchant Customer ID: Identifique o cliente no sistema do comerciante
Controle de Endereço: Desabilite campos de entrega quando necessário

Instalação

Adicione o SDK ao seu site

Para utilizar o SDK, adicione os seguintes scripts no topo da sua página (dentro do<head> ou antes de fechar o</body>):

1. Carregue o SDK

<script src="https://api.vpay.co.mz/sdk/button.js"></script>

Ambos os endpoints são válidos e apontam para o mesmo SDK

Uso Básico

Adicione o botão em qualquer lugar da sua página

Adicione o container onde deseja que o botão apareça:

Container do botão

<!-- Container do botão -->
<div id="void-button-container" buttonToken="SEU_BUTTON_TOKEN"></div>
<div id="error-message"></div>

Configuração de Produtos

Três formas de adicionar produtos ao carrinho

Use produtos já cadastrados no sistema (por ID):

<script>
  // Aguardar SDK carregar
  function waitForVoidPay(callback) {
    if (typeof window.VoidPay !== 'undefined' && window.VoidPay) {
      callback();
    } else {
      setTimeout(() => waitForVoidPay(callback), 50);
    }
  }

  waitForVoidPay(function() {
    // Adicionar produto existente (por ID)
    window.VoidPay.addProduct("prod_123", 2);
    
    // Ou definir múltiplos produtos
    window.VoidPay.setProducts([
      { id: "prod_123", quantity: 2 },
      { id: "prod_456", quantity: 1 }
    ]);
  });
</script>

Configurações Avançadas

Personalize o comportamento do checkout

Identifique o cliente no sistema do comerciante (MerchantCustomerId, ID do Cliente usando no seu sistema).Útil para Webooks:

<!-- Via atributo HTML -->
<div id="void-button-container" 
     buttonToken="SEU_BUTTON_TOKEN"
     data-merchant-customer-id="customer-789-xyz">
</div>

<!-- Ou via JavaScript -->
<script>
  waitForVoidPay(function() {
    window.VoidPay.setCustomerId("customer-789-xyz");
    
    // Verificar ID definido
    console.log('Customer ID:', window.VoidPay.getCustomerId());
  });
</script>

Referência da API v1.1.0

Métodos disponíveis no objeto window.VoidPay

📦 Produtos

VoidPay.addProduct(id, quantity)

Adiciona produto existente (por ID). Se já existir, soma à quantidade.

VoidPay.addProductWithDetails(data)

NOVO Adiciona produto novo com dados completos (name, price, originProductId).

VoidPay.removeProduct(id, quantity)

Remove quantidade específica. Use 'all' para remover tudo.

VoidPay.setProducts(array)

Substitui o carrinho por nova lista (aceita ambos os formatos).

VoidPay.getProducts()

Retorna array atual do carrinho.

👤 Cliente

VoidPay.setCustomerId(id)

NOVO Define o ID do cliente no sistema do comerciante.

VoidPay.getCustomerId()

NOVO Retorna o customer ID atual.

VoidPay.clearCustomerId()

NOVO Remove o customer ID.

📍 Endereço

VoidPay.disableShippingAddress()

NOVO Desabilita o campo de endereço de entrega.

VoidPay.disableDeliveryInfo()

NOVO Desabilita informações de entrega.

VoidPay.setAddressConfig(config)

NOVO Configura ambos com um objeto.

🔧 Utilitários

VoidPay.getTotalItems()

Retorna soma total de itens no carrinho.

VoidPay.hasProducts()

Retorna true se o carrinho tiver produtos.

VoidPay.removeAll()

Remove todos os produtos do carrinho.

VoidPay.setServerUrl(url)

Configura URL do servidor (para ambientes específicos).

Exemplo Completo

Código pronto para copiar e colar

<!-- ========================================== -->
<!-- SDK VOIDpay v1.1.0 - Botão de Pagamento -->
<!-- ========================================== -->

<!-- PASSO 1: Script do SDK -->
<script src="https://dashboard.voidpay.co.mz/sdk/button.js"></script>

<!-- PASSO 2: Container do botão -->
<div id="void-button-container" 
     buttonToken="SEU_BUTTON_TOKEN"
     data-merchant-customer-id="customer-789"
     data-shipping-address-disabled="true"
     data-delivery-info-disabled="true">
</div>
<div id="error-message"></div>

<!-- PASSO 3: Função de espera -->
<script>
  function waitForVoidPay(callback) {
    if (typeof window.VoidPay !== 'undefined' && window.VoidPay) {
      callback();
    } else {
      setTimeout(() => waitForVoidPay(callback), 50);
    }
  }
</script>

<!-- PASSO 4: Configuração dos produtos -->
<script>
  waitForVoidPay(function() {
    // Remover produtos anteriores
    window.VoidPay.removeAll();
    
    // Produto existente (por ID)
    window.VoidPay.addProduct("prod_existing", 1);
    
    // Produto novo (com dados completos)
    window.VoidPay.addProductWithDetails({
      name: "Camiseta Preta",
      price: 29.90,
      quantity: 2,
      imageUrl: "https://loja.com/camiseta.jpg",
      originProductId: "SKU-001",
      description: "Camiseta 100% algodão"
    });
    
    console.log(' Carrinho:', window.VoidPay.getProducts());
    console.log(' Cliente:', window.VoidPay.getCustomerId());
  });
</script>

Boas Práticas

Recomendações para implementação

Sempre use waitForVoidPay

Garanta que o SDK carregou antes de chamar qualquer método.

Use merchantCustomerId para integração

Identifique o cliente no seu sistema para receber webhooks e notificações.

originProductId é único por app

Use um identificador único para cada produto. Se o mesmo originProductId for enviado novamente, o produto existente será usado.

Desabilite endereço quando necessário

Para produtos digitais ou serviços, desabilite campos de entrega para simplificar o checkout.

Quer usar em outra linguagem?

Use IA para converter nosso código para qualquer framework

Copie o código do exemplo acima, cole no MuffinsIA ou qualquer IA e peça para converter para:

Next.js

React.js

Vue.js

Angular

HTML/CSS

Node.js

PHP

Laravel

Java

Python

Flutter

💡 Exemplo: "Converta este código para React com hooks e useEffect"

v1.1.0

Suporte Youtube

<div id="void-button-container" buttonToken="SEU_BUTTON_TOKEN" data-merchant-customer-id="customer-789-xyz"> </div>  <script> waitForVoidPay(function() { window.VoidPay.setCustomerId("customer-789-xyz"); // Verificar ID definido console.log('Customer ID:', window.VoidPay.getCustomerId()); }); </script>

<script src="https://dashboard.voidpay.co.mz/sdk/button.js"></script>  <div id="void-button-container" buttonToken="SEU_BUTTON_TOKEN" data-merchant-customer-id="customer-789" data-shipping-address-disabled="true" data-delivery-info-disabled="true"> </div> <div id="error-message"></div>  <script> function waitForVoidPay(callback) { if (typeof window.VoidPay !== 'undefined' && window.VoidPay) { callback(); } else { setTimeout(() => waitForVoidPay(callback), 50); } } </script>  <script> waitForVoidPay(function() { // Remover produtos anteriores window.VoidPay.removeAll(); // Produto existente (por ID) window.VoidPay.addProduct("prod_existing", 1); // Produto novo (com dados completos) window.VoidPay.addProductWithDetails({ name: "Camiseta Preta", price: 29.90, quantity: 2, imageUrl: "https://loja.com/camiseta.jpg", originProductId: "SKU-001", description: "Camiseta 100% algodão" }); console.log(' Carrinho:', window.VoidPay.getProducts()); console.log(' Cliente:', window.VoidPay.getCustomerId()); }); </script>