Entrar Criar conta
● Guia de Engenharia e SDK Drop-in

Implementação de Carteira em Sites Terceiros

Passo a passo completo e seguro para permitir que clientes introduzam códigos WePayCode e debitem o valor da carteira deles para creditar na conta do seu site parceiro.

🚀 Testar Demonstração Ao Vivo →

1. Arquitetura Segura de Ponta a Ponta

Para garantir segurança absoluta e impedir qualquer fraude ou adulteração de valores, o fluxo da carteira deve seguir rigorosamente a seguinte topologia:

ETAPA 1: NAVEGADOR
Cliente Digita Código

O cliente insere o código no Drop-in SDK no site parceiro. O SDK envia para o backend do parceiro.

ETAPA 2: SERVIDOR PARCEIRO
Comunicação Backend

O backend do parceiro assina a requisição com X-API-Key e X-API-Secret para a WePayCode.

ETAPA 3: LIQUIDAÇÃO
Lock Atômico & Crédito

WePayCode debita o token no banco central e confirma o valor. O parceiro credita a carteira local.

⚠️ REGRA DE OURO DE SEGURANÇA: Nunca exponha sua API Secret no JavaScript do navegador ou em repositórios públicos. Toda liquidação deve partir do seu backend server-to-server.

2. Implementação no Backend do Site Parceiro

No seu servidor, crie dois endpoints para sua aplicação web consumir: um para validação prévia e outro para efetuar o resgate oficial.

Exemplo Completo em PHP / Laravel:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\DB;

class PartnerWalletController extends Controller
{
    private string $apiKey = 'TECHSTORE-BR-994';
    private string $apiSecret = 'sec_live_techstore_secret_994821';
    private string $wepaycodeUrl = 'https://wepaycode.com';

    // 1. Endpoint que o frontend chama para validar o código
    public function validateCode(Request $request)
    {
        $code = strtoupper(trim($request->input('code')));

        $response = Http::withHeaders([
            'X-API-Key' => $this->apiKey,
            'X-API-Secret' => $this->apiSecret,
        ])->post("{$this->wepaycodeUrl}/api/v1/credits/validate", [
            'code' => $code,
        ]);

        return response()->json($response->json(), $response->status());
    }

    // 2. Endpoint que o frontend chama para resgatar e creditar a carteira local
    public function redeemCode(Request $request)
    {
        $code = strtoupper(trim($request->input('code')));
        $user = auth()->user(); // Usuário logado no site parceiro

        // Gerar chave de idempotência única baseada no código e no cliente
        $idempotencyKey = 'wallet-deposit-' . md5($code . $user->id);

        // Chamar a API v1 da WePayCode para liquidar
        $response = Http::withHeaders([
            'X-API-Key' => $this->apiKey,
            'X-API-Secret' => $this->apiSecret,
            'Idempotency-Key' => $idempotencyKey,
        ])->post("{$this->wepaycodeUrl}/api/v1/credits/redeem", [
            'code' => $code,
            'order_id' => 'WALLET-' . time(),
        ]);

        if (!$response->successful()) {
            return response()->json([
                'success' => false,
                'message' => $response->json('message') ?? 'Falha ao resgatar código.'
            ], 400);
        }

        $data = $response->json('data');
        $creditedAmountCents = $data['amount_cents']; // VALOR CONFIADO DA WEPAYCODE

        // Transação atômica no banco de dados do parceiro: credita a carteira do usuário
        DB::transaction(function () use ($user, $creditedAmountCents, $data) {
            $user->increment('wallet_balance_cents', $creditedAmountCents);

            // Grava o extrato na carteira do parceiro
            $user->walletTransactions()->create([
                'type' => 'wepaycode_deposit',
                'amount_cents' => $creditedAmountCents,
                'external_tx_id' => $data['transaction_id'],
                'description' => "Depósito WePayCode ({$data['code']})"
            ]);
        });

        return response()->json([
            'success' => true,
            'message' => 'Saldo creditado na carteira com sucesso!',
            'data' => [
                'transaction_id' => $data['transaction_id'],
                'credited_amount_formatted' => $data['amount_formatted'],
                'new_balance' => $user->fresh()->wallet_balance_cents / 100
            ]
        ]);
    }
}

Exemplo em Node.js / Express:

const express = require('express');
const axios = require('axios');
const app = express();
app.use(express.json());

const WEPAYCODE_API = 'https://wepaycode.com/api/v1';
const API_KEY = 'TECHSTORE-BR-994';
const API_SECRET = 'sec_live_techstore_secret_994821';

app.post('/api/wallet/redeem', async (req, res) => {
  const { code } = req.body;
  const idempotencyKey = 'node-idemp-' + code + '-' + req.user.id;

  try {
    const { data } = await axios.post(`${WEPAYCODE_API}/credits/redeem`, {
      code,
      order_id: `TOPUP-${Date.now()}`
    }, {
      headers: {
        'X-API-Key': API_KEY,
        'X-API-Secret': API_SECRET,
        'Idempotency-Key': idempotencyKey
      }
    });

    // Credita a carteira do usuário no seu banco de dados
    await creditUserLocalWallet(req.user.id, data.data.amount_cents);

    res.json({ success: true, data: data.data });
  } catch (err) {
    res.status(400).json({ success: false, message: err.response?.data?.message || 'Erro no resgate' });
  }
});

3. Frontend Drop-in SDK

No frontend da área de carteira do cliente da sua loja, basta carregar o script do SDK e inicializar apontando para os seus dois endpoints de backend:

<!-- 1. Elemento onde o widget será renderizado -->
<div id="wepaycode-wallet-container"></div>

<!-- 2. Carrega o SDK WePayCode -->
<script src="https://wepaycode.com/js/wepaycode-wallet.js"></script>

<!-- 3. Inicialização -->
<script>
  document.addEventListener('DOMContentLoaded', function () {
    WePayCodeWallet.init({
      target: '#wepaycode-wallet-container',
      merchantName: 'Nome da Sua Loja',
      endpointValidate: '/api/wallet/validate', // Seu endpoint local
      endpointRedeem: '/api/wallet/redeem',     // Seu endpoint local
      onSuccess: function (transaction) {
        console.log('Depósito creditado com sucesso:', transaction);
        // Atualize o saldo do usuário na tela sem recarregar a página
        document.getElementById('user-balance').textContent = transaction.amount_formatted;
      },
      onError: function (err) {
        console.error('Falha no resgate:', err);
      }
    });
  });
</script>

4. Chaves de Idempotência

Em transações financeiras na internet, instabilidades de conexão móvel podem fazer o cliente clicar duas vezes ou o timeout acontecer antes da resposta HTTP chegar.

Para resolver isso de forma elegante:

  • Envie sempre um Idempotency-Key único por operação (ex: hash do código + ID do cliente).
  • Se a requisição for reenviada com a mesma chave, a WePayCode retorna o mesmo recibo de sucesso com o atributo "replayed": true sem debitar o código duas vezes.

5. Checklist de Segurança para Produção

✓ API Secret nunca exposta: Somente trafega entre seu servidor backend e a WePayCode via HTTPS.
✓ Valor do crédito vem do banco: Seu servidor confia somente no campo amount_cents retornado pela WePayCode.
✓ Idempotência implementada: Previne débito concorrente e duplicidade de recargas.
✓ Transação atômica local: O incremento de saldo na carteira local é feito com bloqueio de concorrência no seu banco de dados.
Navegação & Recursos
🚀
Como Funciona
⚡
Carteira Digital
🛍️
Lojas Parceiras
📱
Pagar via QR
Desenvolvedor
Seja Parceiro
🧪
Demo Checkout
🛡️
Segurança
Entrar Criar Conta
Instalar WePayCode no iPhone Adicione à Tela de Início para ter o App Nativo completo