fl_openpay #

Flutter plugin for Openpay payment gateway. Provides card tokenization, device fingerprinting (anti-fraud), one-time charges, customer management, subscription billing, and 3D Secure support for iOS and Android.

Built on top of the official native SDKs:

• Android: openpay-android v3.0.1
• iOS: openpay-swift-ios v3.2.1

Features #

Requirements #

Installation #

Add the dependency to your pubspec.yaml:

dependencies:
  fl_openpay: ^0.0.1

Or run:

flutter pub add fl_openpay

Android setup #

Your app's android/gradle.properties must include jetifier (the Openpay SDK uses legacy support libraries):

android.useAndroidX=true
android.enableJetifier=true

Your app's android/app/build.gradle (or .kts) needs packaging excludes for duplicate META-INF files:

// build.gradle.kts
android {
    packaging {
        resources {
            excludes += setOf(
                "META-INF/DEPENDENCIES",
                "META-INF/LICENSE",
                "META-INF/LICENSE.txt",
                "META-INF/NOTICE",
                "META-INF/NOTICE.txt",
            )
        }
    }
}

No other Android configuration is needed. Internet and network state permissions are declared by the plugin automatically.

iOS setup #

Set the deployment target to at least 14.3 in your ios/Podfile:

platform :ios, '14.3'

Then run cd ios && pod install. No other iOS configuration is needed.

Two components #

This plugin provides two separate clients for different use cases:

Use FlOpenpay in your mobile app to securely tokenize cards. Use OpenpayApi on your backend (or in the app for prototyping) to create charges and manage subscriptions.

Security note: The OpenpayApi class uses your private API key. In production, these calls should be made from your backend server, not from the mobile app. For prototyping and sandbox testing, using it directly in the app is fine.

Quick start: One-time charge #

import 'package:fl_openpay/fl_openpay.dart';

// === MOBILE APP (public key) ===

final sdk = FlOpenpay();
await sdk.initialize(
  merchantId: 'YOUR_MERCHANT_ID',
  publicApiKey: 'pk_test_XXXX',
  productionMode: false,
  country: OpenpayCountry.mexico,
);

// 1. Get device fingerprint
final sessionId = await sdk.createDeviceSessionId();

// 2. Tokenize the card
final token = await sdk.tokenizeCard(
  OpenpayCard(
    holderName: 'Juan Perez',
    cardNumber: '4111111111111111',
    expirationMonth: '12',
    expirationYear: '29',
    cvv2: '123',
  ),
);

// 3. Send token.id + sessionId to your backend...

// === BACKEND (private key) ===

final api = OpenpayApi(
  merchantId: 'YOUR_MERCHANT_ID',
  apiKey: 'sk_test_XXXX',
  isSandbox: true,
  countryCode: 'MX',
);

// 4. Create the charge
final charge = await api.charges.create(OpenpayCharge(
  sourceId: token.id,
  method: 'card',
  amount: 150.00,
  currency: 'MXN',
  description: 'Order #1234',
  deviceSessionId: sessionId,
  customer: OpenpayChargeCustomer(
    name: 'Juan',
    lastName: 'Perez',
    email: 'juan@example.com',
  ),
));

print(charge.id);     // "trfcfhakixfkpsjubnk"
print(charge.status); // "completed"

Quick start: Subscription #

final api = OpenpayApi(
  merchantId: 'YOUR_MERCHANT_ID',
  apiKey: 'sk_test_XXXX',
  isSandbox: true,
);

// 1. Create a customer
final customer = await api.customers.create(OpenpayCustomer(
  name: 'Maria',
  lastName: 'Garcia',
  email: 'maria@example.com',
  phoneNumber: '5512345678',
));

// 2. Save a card on the customer (using a token from FlOpenpay.tokenizeCard)
final card = await api.cards.createForCustomer(
  customer.id!,
  'tok_XXXXXXXXXXXX', // token.id from tokenizeCard()
  deviceSessionId: sessionId,
);

// 3. Create a plan (do this once, reuse the plan ID)
final plan = await api.plans.create(OpenpayPlan(
  name: 'Premium Monthly',
  amount: 299.00,
  currency: 'MXN',
  repeatEvery: 1,
  repeatUnit: 'month',
  trialDays: 14,
  retryTimes: 3,
  statusAfterRetry: 'unpaid',
));

// 4. Subscribe the customer to the plan
final subscription = await api.subscriptions.create(
  customer.id!,
  OpenpaySubscription(
    planId: plan.id!,
    cardId: card.id,
  ),
);

print(subscription.id);     // "szfcfhakixfkpsjubnk"
print(subscription.status); // "trial" (14-day trial)

Full integration guide #

Architecture overview #

┌──────────────────────────────┐
│      Your Flutter App         │
│                               │
│  FlOpenpay (public key)       │
│  ├─ tokenizeCard() ──────────────► Openpay servers (returns token)
│  └─ createDeviceSessionId()   │
│                               │
│  Sends token_id + session_id  │
│  to your backend              │
└──────────────┬────────────────┘
               │
               ▼
┌──────────────────────────────┐       ┌──────────────────────┐
│      Your Backend             │       │    Openpay REST API   │
│                               │       │                      │
│  OpenpayApi (private key)     │──────►│  /charges            │
│  ├─ api.charges.create()      │       │  /customers          │
│  ├─ api.customers.create()    │       │  /cards              │
│  ├─ api.plans.create()        │       │  /plans              │
│  └─ api.subscriptions.create()│       │  /subscriptions      │
└───────────────────────────────┘       └──────────────────────┘

Step 1: Get your Openpay credentials #

1. Create an account at openpay.mx (or .co / .pe)
2. Go to Dashboard > API Keys
3. Copy your Merchant ID, Public API Key, and Private API Key
4. For testing, use the sandbox credentials

Step 2: Initialize the native SDK (mobile app) #

final sdk = FlOpenpay();

await sdk.initialize(
  merchantId: 'YOUR_MERCHANT_ID',
  publicApiKey: 'pk_test_XXXX',
  productionMode: false,
  country: OpenpayCountry.mexico,
);

Step 3: Generate device session ID #

final sessionId = await sdk.createDeviceSessionId();

Step 4: Tokenize the card #

final token = await sdk.tokenizeCard(
  OpenpayCard(
    holderName: _nameController.text,
    cardNumber: _cardController.text.replaceAll(' ', ''),
    expirationMonth: '12',
    expirationYear: '29',
    cvv2: '123',
    address: OpenpayAddress( // optional, improves anti-fraud
      line1: 'Av. Insurgentes Sur 253',
      city: 'Ciudad de Mexico',
      state: 'CDMX',
      postalCode: '06600',
      countryCode: 'MX',
    ),
  ),
);
// Send token.id + sessionId to your backend

Step 5: One-time charge (backend) #

final api = OpenpayApi(
  merchantId: 'YOUR_MERCHANT_ID',
  apiKey: 'sk_test_XXXX',
  isSandbox: true,
);

final charge = await api.charges.create(OpenpayCharge(
  sourceId: token.id,
  method: 'card',
  amount: 150.00,
  currency: 'MXN',
  description: 'Order #1234',
  deviceSessionId: sessionId,
));

if (charge.status == 'completed') {
  // Payment successful
}

Step 6: Pre-authorized charge (capture later) #

// Create a pre-auth (hold funds without capturing)
final preAuth = await api.charges.create(OpenpayCharge(
  sourceId: token.id,
  method: 'card',
  amount: 500.00,
  currency: 'MXN',
  description: 'Hotel reservation hold',
  deviceSessionId: sessionId,
  capture: false, // <-- pre-authorization
));

// Later, capture the full or partial amount
final captured = await api.charges.capture(preAuth.id!, amount: 450.00);

// Or refund if not needed
final refunded = await api.charges.refund(preAuth.id!, description: 'Cancelled');

Step 7: Set up recurring subscriptions #

// 1. Create customer
final customer = await api.customers.create(OpenpayCustomer(
  name: 'Carlos',
  lastName: 'Lopez',
  email: 'carlos@example.com',
));

// 2. Save card on customer
final card = await api.cards.createForCustomer(customer.id!, token.id);

// 3. Create a plan (reuse across customers)
final plan = await api.plans.create(OpenpayPlan(
  name: 'Pro Monthly',
  amount: 499.00,
  currency: 'MXN',
  repeatEvery: 1,
  repeatUnit: 'month',
  trialDays: 7,
  retryTimes: 3,
  statusAfterRetry: 'cancelled',
));

// 4. Subscribe
final sub = await api.subscriptions.create(customer.id!, OpenpaySubscription(
  planId: plan.id!,
  cardId: card.id,
));

// 5. Check subscription status
final updated = await api.subscriptions.get(customer.id!, sub.id!);
print(updated.status); // "trial", "active", "past_due", "unpaid", "cancelled"

// 6. Cancel at end of period (soft cancel)
await api.subscriptions.update(customer.id!, sub.id!, OpenpaySubscription(
  planId: plan.id!,
  cancelAtPeriodEnd: true,
));

// 7. Or cancel immediately
await api.subscriptions.cancel(customer.id!, sub.id!);

Step 8: Handle 3D Secure #

final charge = await api.charges.create(OpenpayCharge(
  sourceId: token.id,
  method: 'card',
  amount: 150.00,
  currency: 'MXN',
  description: 'Order #1234',
  deviceSessionId: sessionId,
  use3dSecure: true,
  redirectUrl: 'https://yoursite.com/payment-callback',
));

if (charge.status == 'charge_pending' && charge.paymentMethod?.url != null) {
  // Open the URL in a WebView or browser for 3DS authentication
  // After authentication, verify charge status on your backend
}

REST API reference #

OpenpayApi #

final api = OpenpayApi(
  merchantId: 'xxx',
  apiKey: 'sk_xxx',
  isSandbox: true,     // default: true
  countryCode: 'MX',   // default: 'MX'. Also: 'CO', 'PE'
);

api.charges #

api.customers #

api.cards #

api.plans #

api.subscriptions #

Native SDK reference (FlOpenpay) #

Exceptions #

Sandbox test cards #

Error codes reference #

General (1xxx) #

Card / storage (2xxx) #

Gateway (3xxx) #

ProGuard / R8 #

The plugin ships its own proguard-rules.pro via consumerProguardFiles. No additional configuration needed.

Running the example app #

cd example
flutter run

Contributing #

1. Edit the Pigeon schema in pigeons/openpay_api.dart
2. Regenerate: flutter pub run pigeon --input pigeons/openpay_api.dart
3. Implement in FlOpenpayPlugin.kt (Android) and FlOpenpayPlugin.swift (iOS)
4. Run flutter analyze && flutter test

License #

MIT License. See LICENSE file.