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: 'user@email.com',
    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);

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