Wallet
Gerenciar carteira virtual para pagamentos de reservas
Wallet
A Wallet é sua carteira virtual para pagamento de reservas. Todas as transações de emissão de bilhetes são debitadas do saldo da wallet.
Como Funciona
- Você recarrega sua wallet via PIX, boleto ou cartão
- Ao criar reservas com
type: instant, o valor é debitado automaticamente - Para reservas
hold, o débito ocorre na confirmação
Modo de Teste
Quando você usa uma chave de API de teste, a carteira funciona em modo sandbox:
- Saldo fictício: R$ 5.000,00 disponível automaticamente
- Transações simuladas: Depósitos e débitos não afetam o saldo real
- Sem integração real: Não há cobranças reais via PIX/Boleto
Importante
O saldo de teste é sempre R$ 5.000,00 independente das transações de teste realizadas. Isso permite testar a integração sem se preocupar com saldo.
Todas as respostas incluem um campo _meta indicando o modo:
{
"success": true,
"data": { ... },
"_meta": {
"test_mode": true,
"message": "Saldo fictício de R$ 5.000,00 para testes"
}
}GET /api/v1/wallet/balance
Obtém o saldo atual da carteira.
Response
{
"success": true,
"data": {
"balance": "15750.00",
"currency": "BRL",
"available_credit": "15750.00",
"pending_amount": "2500.00",
"last_transaction_at": "2025-01-14T15:30:00Z"
}
}Campos
| Campo | Tipo | Descrição |
|---|---|---|
balance | string | Saldo total disponível |
currency | string | Moeda (sempre BRL) |
available_credit | string | Crédito disponível para uso imediato |
pending_amount | string | Valor em reservas pendentes (hold) |
last_transaction_at | string | Data da última movimentação |
Exemplo
curl -X GET https://app.reservei.co/api/v1/wallet/balance \
-H "Authorization: Bearer sua_chave_aqui"const response = await fetch('https://app.reservei.co/api/v1/wallet/balance', {
headers: {
'Authorization': `Bearer ${process.env.RESERVEI_API_KEY}`
}
});
const { data } = await response.json();
console.log(`Saldo disponível: R$ ${data.balance}`);import requests
response = requests.get(
'https://app.reservei.co/api/v1/wallet/balance',
headers={'Authorization': f'Bearer {api_key}'}
)
data = response.json()['data']
print(f"Saldo disponível: R$ {data['balance']}")GET /api/v1/wallet/transactions
Lista todas as transações da carteira com paginação e filtros.
Query Parameters
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
page | number | 1 | Página atual |
limit | number | 20 | Itens por página (máx: 100) |
type | string | - | Filtrar por tipo: credit ou debit |
start_date | string | - | Data inicial (YYYY-MM-DD) |
end_date | string | - | Data final (YYYY-MM-DD) |
Response
{
"success": true,
"data": {
"transactions": [
{
"id": "txn_0000AbCdEf123456",
"type": "debit",
"amount": "7825.60",
"currency": "BRL",
"description": "Reserva de voo - XJ59L2",
"reference_type": "booking",
"reference_id": "ord_0000GhIjKl789012",
"balance_after": "7924.40",
"created_at": "2025-01-15T10:30:00Z"
},
{
"id": "txn_0000MnOpQr345678",
"type": "credit",
"amount": "10000.00",
"currency": "BRL",
"description": "Recarga via PIX",
"reference_type": "recharge",
"reference_id": "rch_0000StUvWx901234",
"balance_after": "15750.00",
"payment_method": "pix",
"created_at": "2025-01-14T15:30:00Z"
},
{
"id": "txn_0000YzAbCd567890",
"type": "credit",
"amount": "1100.50",
"currency": "BRL",
"description": "Estorno - Cancelamento reserva ABC123",
"reference_type": "refund",
"reference_id": "ord_0000...",
"balance_after": "5750.00",
"created_at": "2025-01-12T09:15:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 127,
"pages": 7
},
"summary": {
"total_credits": "45000.00",
"total_debits": "29250.00",
"period_start": "2025-01-01",
"period_end": "2025-01-15"
}
}
}Campos da Transação
| Campo | Tipo | Descrição |
|---|---|---|
id | string | ID único da transação |
type | string | credit (entrada) ou debit (saída) |
amount | string | Valor da transação |
currency | string | Moeda (sempre BRL) |
description | string | Descrição da transação |
reference_type | string | Tipo de referência (booking, recharge, refund) |
reference_id | string | ID da entidade relacionada |
balance_after | string | Saldo após a transação |
payment_method | string | Método de pagamento (para recargas) |
created_at | string | Data/hora da transação |
POST /api/v1/wallet/recharge
Solicita uma recarga da carteira. Retorna dados para pagamento.
Request
{
"amount": "5000.00",
"currency": "BRL",
"payment_method": "pix"
}Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | string | Sim | Valor da recarga (mínimo: R$ 100,00) |
currency | string | Sim | Moeda (sempre BRL) |
payment_method | string | Sim | Método: pix, boleto |
Response (PIX)
{
"success": true,
"data": {
"id": "rch_0000AbCdEf123456",
"amount": "5000.00",
"currency": "BRL",
"status": "pending",
"payment_method": "pix",
"payment": {
"pix_copy_paste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540550005802BR5925RESERVEI TECNOLOGIA LTDA6009SAO PAULO62070503***6304ABCD",
"pix_qrcode_url": "https://app.reservei.co/api/v1/pix/qr/rch_0000AbCdEf123456",
"expires_at": "2025-01-15T12:00:00Z"
},
"created_at": "2025-01-15T10:00:00Z"
}
}Response (Boleto)
{
"success": true,
"data": {
"id": "rch_0000AbCdEf123456",
"amount": "5000.00",
"currency": "BRL",
"status": "pending",
"payment_method": "boleto",
"payment": {
"boleto_barcode": "23793.38128 60000.000003 00000.000400 1 84340000500000",
"boleto_url": "https://app.reservei.co/api/v1/boleto/rch_0000AbCdEf123456",
"boleto_pdf_url": "https://app.reservei.co/api/v1/boleto/rch_0000AbCdEf123456/pdf",
"expires_at": "2025-01-18T23:59:59Z"
},
"created_at": "2025-01-15T10:00:00Z"
}
}GET /api/v1/wallet/recharge/:id
Verifica o status de uma recarga específica.
Response
{
"success": true,
"data": {
"id": "rch_0000AbCdEf123456",
"amount": "5000.00",
"currency": "BRL",
"status": "completed",
"payment_method": "pix",
"paid_at": "2025-01-15T10:05:32Z",
"transaction_id": "txn_0000MnOpQr345678",
"created_at": "2025-01-15T10:00:00Z"
}
}Status da Recarga
| Status | Descrição |
|---|---|
pending | Aguardando pagamento |
completed | Pagamento confirmado, crédito adicionado |
expired | Prazo de pagamento expirado |
failed | Falha no processamento |
cancelled | Cancelada pelo usuário |
Métodos de Pagamento
| Método | Tempo de Confirmação | Disponibilidade |
|---|---|---|
pix | Instantâneo (< 1 min) | 24/7 |
boleto | 1-3 dias úteis | Dias úteis |
PIX Recomendado
Para maior agilidade, recomendamos o uso de PIX. O crédito é adicionado automaticamente após a confirmação do pagamento.
Limites e Regras
| Regra | Valor |
|---|---|
| Recarga mínima | R$ 100,00 |
| Recarga máxima por transação | R$ 50.000,00 |
| Recarga máxima por dia | R$ 100.000,00 |
| Validade do PIX | 30 minutos |
| Validade do Boleto | 3 dias úteis |
Webhooks de Wallet
Configure webhooks para ser notificado sobre eventos da wallet:
| Evento | Descrição |
|---|---|
wallet.credit | Crédito adicionado (recarga, estorno) |
wallet.debit | Débito realizado (reserva) |
wallet.recharge.completed | Recarga confirmada |
wallet.recharge.expired | Recarga expirada |
wallet.low_balance | Saldo abaixo de R$ 500,00 |
Exemplos de Integração
// 1. Verificar saldo antes de criar reserva
const balanceResponse = await fetch('https://app.reservei.co/api/v1/wallet/balance', {
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const { data: wallet } = await balanceResponse.json();
const bookingAmount = 7825.60;
if (parseFloat(wallet.balance) < bookingAmount) {
// 2. Solicitar recarga via PIX
const rechargeResponse = await fetch('https://app.reservei.co/api/v1/wallet/recharge', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: '10000.00',
currency: 'BRL',
payment_method: 'pix'
})
});
const { data: recharge } = await rechargeResponse.json();
// 3. Exibir QR Code para o cliente
console.log('PIX Copia e Cola:', recharge.payment.pix_copy_paste);
console.log('QR Code:', recharge.payment.pix_qrcode_url);
// 4. Aguardar confirmação via webhook ou polling
// ...
}
// 5. Criar reserva após saldo suficiente
const bookingResponse = await fetch('https://app.reservei.co/api/v1/bookings', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
offerId: 'off_xxx',
type: 'instant',
passengers: [...],
payments: [{ type: 'balance', amount: '1250.50', currency: 'USD' }]
})
});// Verificar saldo e alertar se baixo
async function checkBalance() {
const response = await fetch('https://app.reservei.co/api/v1/wallet/balance', {
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const { data } = await response.json();
const balance = parseFloat(data.balance);
if (balance < 1000) {
// Enviar alerta para admin
await sendSlackAlert(`⚠️ Saldo baixo na wallet: R$ ${balance.toFixed(2)}`);
}
return balance;
}
// Executar a cada hora
setInterval(checkBalance, 60 * 60 * 1000);// Gerar relatório de transações do mês
async function getMonthlyReport(year, month) {
const startDate = `${year}-${String(month).padStart(2, '0')}-01`;
const endDate = `${year}-${String(month).padStart(2, '0')}-${new Date(year, month, 0).getDate()}`;
let allTransactions = [];
let page = 1;
let hasMore = true;
while (hasMore) {
const response = await fetch(
`https://app.reservei.co/api/v1/wallet/transactions?page=${page}&limit=100&start_date=${startDate}&end_date=${endDate}`,
{ headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { data } = await response.json();
allTransactions = [...allTransactions, ...data.transactions];
hasMore = page < data.pagination.pages;
page++;
}
// Calcular totais
const totals = allTransactions.reduce((acc, txn) => {
const amount = parseFloat(txn.amount);
if (txn.type === 'credit') {
acc.credits += amount;
} else {
acc.debits += amount;
}
return acc;
}, { credits: 0, debits: 0 });
return {
period: `${month}/${year}`,
totalTransactions: allTransactions.length,
totalCredits: totals.credits.toFixed(2),
totalDebits: totals.debits.toFixed(2),
netChange: (totals.credits - totals.debits).toFixed(2)
};
}Erros Comuns
| Código | Erro | Causa | Solução |
|---|---|---|---|
400 | Minimum amount is R$ 100.00 | Recarga abaixo do mínimo | Aumente o valor |
400 | Invalid payment method | Método não suportado | Use pix ou boleto |
422 | Insufficient balance | Saldo insuficiente para débito | Recarregue a wallet |
422 | Daily limit exceeded | Limite diário atingido | Aguarde próximo dia |
404 | Recharge not found | ID de recarga inválido | Verifique o ID |