Flutter checkout SDK

Open VenPays hosted card checkout inside a Flutter WebView. Card numbers never touch your app — the shopper pays on the VenPays / Mastercard page.

This version is card only. Benefit, BenefitPay, and Apple Pay are not in the Flutter SDK yet. For native Apple Pay on iOS, see Apple Pay iOS.

Credentials

Never put a secret or legacy key in the Flutter app. The SDK never accepts or stores VenPays API keys.

1. Create a session and start card pay on your server

POST /v1/sdk/checkout
Host: init-vpay.venlabs.link
X-API-KEY: sk_test_…
Content-Type: application/json

{ "amount": 12.500, "currency": "BHD" }

Then start card payment:

POST /v1/sdk/checkout/{track_id}/pay
Host: init-vpay.venlabs.link
Content-Type: application/json

{ "method": "card" }

Live host: merchant.venpays.com. Use a secret or legacy key, not the publishable key.

Return only safe fields to the app:

{
  "track_id": "…",
  "payment_url": "https://…/mastercard/payment?payment_id=…",
  "amount": 12.5,
  "currency": "BHD"
}

2. Install the Flutter package

dependencies:
  venpays_flutter: ^0.1.0

flutter pub get

Package: venpays_flutter
Source: venpays-flutter

3. Start checkout in the app

import 'package:venpays_flutter/venpays_flutter.dart';

final result = await VenPaysCheckout.start(
  context: context,
  paymentUrl: payment.paymentUrl, // from your backend
  trackId: payment.trackId,       // from your backend
  successUrl: 'https://merchant.example/payment/success',
  failureUrl: 'https://merchant.example/payment/failure',
);

switch (result.status) {
  case PaymentStatus.success:
    // Informational only — confirm on your backend before fulfillment.
    break;
  case PaymentStatus.failed:
    break;
  case PaymentStatus.cancelled:
    break;
  case PaymentStatus.error:
    break;
}

Custom URL schemes (myapp://…) are not supported by the Payment Engine return-URL validator. See Return URLs.

4. Confirm on your server

After the WebView closes, treat PaymentResult as a hint only. Fulfill the order from a webhook or POST /merchant/payment-status with your secret key. See Payment status and Webhooks.

Sandbox and live

The Flutter app does not choose sandbox vs live. Your backend selects the environment by which Payment Engine host and API key it uses; the app only opens the payment_url you return.

What the Flutter SDK does not do

• Collect or store card PAN / CVV
• Hold secret, legacy, or publishable keys
• Call initiate, refund, or status APIs
• Select Benefit, BenefitPay, or Apple Pay

Troubleshooting