bancard_vpos 0.1.0

Flutter package for Bancard VPOS 2.0 payments (Paraguay). Supports single buy and recurring payments with native card management. No backend required.

bancard_vpos

Flutter package for Bancard VPOS 2.0 payments (Paraguay). Supports single buy payments, recurring payments with saved cards, and native card management — no backend required.

Features

• Single Buy — One-time payments via Bancard checkout form
• Card Registration — Save cards for future use
• Charge Saved Cards — Pay with previously registered cards (alias token)
• Card Management — List, add, and delete saved cards
• Transaction Rollback — Reverse completed transactions
• Payment Confirmation — Retrieve transaction details
• Native WebView — Bancard form rendered inside the app with URL interception
• Lottie Animations — Polished success/failure animations with customization support
• Zero Server Dependency — No backend or deep link configuration needed
• Sandbox + Production — Easy environment switching

How It Works

The package uses a custom URI scheme (bancardvpos://result) as the return_url for Bancard. When the payment completes, Bancard attempts to redirect to this URL. The WebView intercepts this navigation via shouldOverrideUrlLoading, cancels it (never loads the URL), and emits the result natively to Flutter.

This means:

• No real server at the return URL
• No deep link configuration in AndroidManifest.xml or Info.plist
• No backend of any kind

Getting Started

Installation

dependencies:
  bancard_vpos: ^0.1.0

Android Setup

Add internet permission in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>

iOS Setup

Add to ios/Runner/Info.plist (required for sandbox HTTP resources):

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key><true/>
</dict>

Usage

Quick Checkout

import 'package:bancard_vpos/bancard_vpos.dart';

final config = BancardConfig(
  publicKey: 'your_public_key',
  privateKey: 'your_private_key',
  environment: BancardEnvironment.sandbox,
);

// Full checkout with saved cards
final result = await Navigator.push<BancardPaymentResult>(
  context,
  MaterialPageRoute(builder: (_) => BancardCheckoutPage(
    config: config,
    shopProcessId: 123456,   // your unique transaction ID
    amount: 150000,
    description: 'Order #123',
    userId: 42,              // enables saved card selection
    currency: 'PYG',
  )),
);

if (result?.isSuccess == true) {
  print('Payment approved!');
}

Card Management

await Navigator.push(context, MaterialPageRoute(
  builder: (_) => BancardCardManagementPage(
    config: config,
    userId: 42,
    userEmail: '[e-mail]',
    userPhone: '0981000000',
  ),
));

Direct API Usage

final service = BancardService(config);

// Get saved cards
final cards = await service.getUserCards(42);

// Charge a saved card
final chargeResult = await service.charge(
  shopProcessId: 123456,
  amount: 150000,
  aliasToken: cards.first.aliasToken,
  description: 'Order #123',
);

// Rollback a transaction
await service.rollback(123456);

// Get confirmation
final confirmation = await service.getConfirmation(123456);

Card Selector Widget

BancardCardSelector(
  config: config,
  userId: 42,
  selectedCard: _selectedCard,
  onCardSelected: (card) => setState(() => _selectedCard = card),
  onAddNewCard: () => _openCardRegistration(),
)

Custom Result Animations

The result widget uses built-in Lottie animations for success and failure. You can override them with your own:

BancardResultWidget(
  result: paymentResult,
  onDone: () => Navigator.pop(context),
  // Use your own Lottie JSON assets:
  successAnimationAsset: 'assets/my_success.json',
  failedAnimationAsset: 'assets/my_error.json',
  animationSize: 200,
)

⚠️ Security Warning

The privateKey in BancardConfig is used to generate authentication tokens. Do NOT embed it in production apps distributed via Play Store / App Store. For public-facing apps, use a backend to generate the process_id and pass it directly to the WebView.

This package is suitable for:

• Enterprise / internal apps
• Apps paired with a backend proxy
• Prototyping and sandbox testing

Environments

Environment	Base URL
Sandbox	https://vpos.infonet.com.py:8888
Production	https://vpos.infonet.com.py

Sandbox Test Data

Field	Value
Card Number	4111 1111 1111 1111
Expiration	Any future date
CVV	123
Cédula	9661000
OTP Zimple	1234

API Reference

BancardService

Method	Description
initSingleBuy()	Start a single payment, returns process_id
initCardRegistration()	Start card registration, returns process_id
getUserCards()	Get saved cards for a user
charge()	Charge a saved card
deleteCard()	Delete a saved card
rollback()	Reverse a transaction
getConfirmation()	Get transaction details

Pages & Widgets

Component	Description
BancardCheckoutPage	Complete checkout flow (cards + payment + result)
BancardCardManagementPage	Card CRUD management
BancardCardSelector	Reusable saved card picker
BancardResultWidget	Embeddable payment result display
BancardResultPage	Full-page payment result

License

MIT