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.
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:
O cliente insere o código no Drop-in SDK no site parceiro. O SDK envia para o backend do parceiro.
O backend do parceiro assina a requisição com X-API-Key e X-API-Secret para a WePayCode.
WePayCode debita o token no banco central e confirma o valor. O parceiro credita a carteira local.
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": truesem debitar o código duas vezes.
5. Checklist de Segurança para Produção
amount_cents retornado pela WePayCode.