moveme_wallet 0.2.2

SDK Flutter/Dart for MoveMe Digital Wallet (safe client + server payments entry).

moveme_wallet

SDK Flutter/Dart para /api/digital-wallet.

Install

dependencies:
  moveme_wallet: ^0.2.2
  moveme_wallet_notifications: ^0.1.0

Client (seguro)

import 'package:moveme_wallet/moveme_wallet.dart';

final wallet = WalletClient(
  options: WalletClientOptions(
    baseUrl: 'YOUR_BASE_URL',
    apiKey: 'YOUR_API_KEY',
  ),
);

final account = await wallet.ensureAccount('moveme:driver_42');
await wallet.debit(
  externalUserId: 'moveme:driver_42',
  amount: 100,
  idempotencyKey: idempotencyKey('trip', 99, 'fare'),
);

Métodos: createAccount, getByExternalUserId, ensureAccount, getBalance, getStatement, debit, debitForTrip, transfer, listPaymentMethods, createCheckout, getCheckout, health.

Não exporta load / crédito.

Gateway — métodos e checkout

final methods = await wallet.listPaymentMethods();
// ecrã Pagamento via Gateway — não uses lista fixa na app

final checkout = await wallet.createCheckout(
  externalUserId: 'moveme:driver_42',
  amount: 2000,
  paymentMethod: 'multicaixa_express',
);
// abrir checkout.paymentUrl / checkout.openUrl (ex. w.appmove.com)

Payments (backend only)

import 'package:moveme_wallet/payments.dart';

await PaymentsClient(
  options: PaymentsClientOptions(
    baseUrl: 'YOUR_BASE_URL',
    paymentsApiKey: 'YOUR_PAYMENTS_API_KEY',
  ),
).load(
  externalUserId: 'moveme:driver_42',
  amount: 2000,
  paymentId: 'pay_xxx',
);

Iniciar carregamento (top-up)

1. Flutter: listPaymentMethods → utilizador escolhe método + valor
2. Flutter: createCheckout → abre paymentUrl
3. Utilizador paga no gateway / PSP
4. Gateway confirma → wallet credita (ou BFF chama POST /loads)
5. App: onLoadConfirmed / polling → notificação local

A app não envia initialBalance ao criar conta (admin define).
Na 1ª criação, use created / initialBalanceApplied para boas-vindas.

Nunca creditar com API_KEY genérica.

Security

• API_KEY → BFF / app controlada. Preferir: mobile → vosso backend → WalletClient.
• PAYMENTS_API_KEY → nunca na app móvel; só payments.dart.

Local notifications

await ensureAccountWithNotify(
  wallet: wallet,
  notifications: notifs,
  externalUserId: 'moveme:driver_42',
);

Errors

try {
  await wallet.debit(externalUserId: id, amount: 100);
} on WalletApiError catch (e) {
  if (isInsufficientFunds(e)) { /* top-up */ }
}

License

MIT