LatinAmericanPaymentGateway - Package Documentation¶

abstract class LatinAmericanPaymentGateway {
  /// Unique identifier for the gateway
  String get id;

  /// Display name
  String get name;

  /// Primary country of operation
  Country get primaryCountry;

  /// Additional supported countries (for multi-country gateways)
  Set<Country> get supportedCountries;

  /// Supported payment methods
  Set<PaymentMethodType> get supportedMethods;

  /// Supported currencies
  Set<Currency> get supportedCurrencies;

  /// Initialize with configuration
  Future<void> initialize(PaymentGatewayConfiguration config);

  /// PCI compliant card tokenization
  /// Returns a secure token representing the card
  Future<CardToken> tokenizeCard({
    required String cardNumber,
    required String expiryMonth,
    required String expiryYear,
    required String cvv,
    required String cardHolderName,
    CardBillingAddress? billingAddress,
  });

  /// Process a payment
  /// [amount]: Amount in smallest currency unit (e.g., 1000 = $10.00)
  /// [currency]: Payment currency
  /// [method]: Payment method (CardToken, Pix, Sinpe, etc.)
  Future<PaymentResult> processPayment({
    required int amount,
    required Currency currency,
    required PaymentMethodType method,
    required String description,
    String? orderId,
    Customer? customer,
    Map<String, dynamic>? metadata,
  });

  /// Check transaction status
  Future<PaymentResult> getTransaction(String transactionId);

  /// Refund transaction
  /// [amount]: If null, full refund
  Future<RefundResult> refund({
    required String transactionId,
    int? amount,
    String? reason,
  });

  /// Check gateway availability
  Future<bool> healthCheck();

  /// Dispose resources
  Future<void> dispose();
}

/// Configuration for any LATAM payment gateway
class PaymentGatewayConfiguration {
  /// Public API Key (for client-side tokenization)
  final String? publicKey;

  /// Private API Key (for backend, if applicable)
  final String? privateKey;

  /// API Secret (for gateways requiring it)
  final String? apiSecret;

  /// Environment: sandbox or production
  final bool sandbox;

  /// Request timeout (default: 30s)
  final Duration timeout;

  /// Gateway-specific configuration
  final Map<String, dynamic>? extraConfig;

  const PaymentGatewayConfiguration({
    this.publicKey,
    this.privateKey,
    this.apiSecret,
    this.sandbox = true,
    this.timeout = const Duration(seconds: 30),
    this.extraConfig,
  });

  /// Factory for minimal configuration (tokenization only)
  factory PaymentGatewayConfiguration.minimal({
    required String publicKey,
    bool sandbox = true,
  }) => PaymentGatewayConfiguration(
    publicKey: publicKey,
    sandbox: sandbox,
  );
}

enum Country {
  costaRica('CR', 'Costa Rica'),
  panama('PA', 'Panamá'),
  colombia('CO', 'Colombia'),
  mexico('MX', 'México'),
  brazil('BR', 'Brasil'),
  argentina('AR', 'Argentina'),
  chile('CL', 'Chile'),
  peru('PE', 'Perú');

  final String code;
  final String displayName;
  const Country(this.code, this.displayName);
}

enum Currency {
  crc('CRC', 'Costa Rican Colón', '₡'),
  pab('PAB', 'Panamanian Balboa', 'B/.'),
  cop('COP', 'Colombian Peso', r'$'),
  mxn('MXN', 'Mexican Peso', r'$'),
  brl('BRL', 'Brazilian Real', r'R$'),
  usd('USD', 'US Dollar', r'$');

  final String code;
  final String name;
  final String symbol;
  const Currency(this.code, this.name, this.symbol);
}

enum PaymentMethodType {
  creditCard,
  debitCard,
  sinpeMovil,      // Costa Rica
  pse,             // Colombia
  nequi,           // Colombia
  spei,            // México
  oxxo,            // México
  pix,             // Brasil
  boleto,          // Brasil
  yape,            // Perú
  plin,            // Perú
}

enum PaymentGatewayType {
  onvoPay,
  tilopay,
  wompi,
  openpay,
  conekta,
  mercadoPago,
  ebanx,
}

class PaymentGatewayFactory {
  static LatinAmericanPaymentGateway create({
    required PaymentGatewayType type,
    required PaymentGatewayConfiguration config,
  }) {
    switch (type) {
      case PaymentGatewayType.onvoPay:
        return OnvoPayPaymentGateway(config);
      case PaymentGatewayType.tilopay:
        return TilopayPaymentGateway(config);
      case PaymentGatewayType.wompi:
        return WompiPaymentGateway(config);
      case PaymentGatewayType.openpay:
        return OpenpayPaymentGateway(config);
      case PaymentGatewayType.conekta:
        return ConektaPaymentGateway(config);
      case PaymentGatewayType.mercadoPago:
        return MercadoPagoPaymentGateway(config);
      case PaymentGatewayType.ebanx:
        return EbanxPaymentGateway(config);
    }
  }

  static List<PaymentGatewayType> availableFor(Country country) {
    return PaymentGatewayRegistry.gatewaysByCountry[country] ?? [];
  }

  static Set<PaymentMethodType> nativeMethodsFor(Country country) {
    return switch (country) {
      Country.costaRica => {PaymentMethodType.sinpeMovil},
      Country.colombia => {PaymentMethodType.pse, PaymentMethodType.nequi},
      Country.mexico => {PaymentMethodType.spei, PaymentMethodType.oxxo},
      Country.brazil => {PaymentMethodType.pix, PaymentMethodType.boleto},
      _ => {},
    };
  }
}

class PaymentGatewayRegistry {
  static const Map<Country, List<PaymentGatewayType>> gatewaysByCountry = {
    Country.costaRica: [
      PaymentGatewayType.onvoPay,
      PaymentGatewayType.tilopay,
    ],
    Country.panama: [
      // To be defined
    ],
    Country.colombia: [
      PaymentGatewayType.wompi,
      PaymentGatewayType.mercadoPago,
      PaymentGatewayType.ebanx,
    ],
    Country.mexico: [
      PaymentGatewayType.openpay,
      PaymentGatewayType.conekta,
      PaymentGatewayType.mercadoPago,
    ],
    Country.brazil: [
      PaymentGatewayType.mercadoPago,
      PaymentGatewayType.ebanx,
    ],
  };
}

import 'package:latam_payments/latam_payments.dart';

// Initialize gateway
final gateway = PaymentGatewayFactory.create(
  type: PaymentGatewayType.onvoPay,
  config: PaymentGatewayConfiguration(
    publicKey: 'pk_live_...',
    sandbox: false,
  ),
);

// Tokenize card
final token = await gateway.tokenizeCard(
  cardNumber: '4242424242424242',
  expiryMonth: '12',
  expiryYear: '2025',
  cvv: '123',
  cardHolderName: 'John Doe',
);

// Process payment
final result = await gateway.processPayment(
  amount: 50000, // ₡50,000
  currency: Currency.crc,
  method: PaymentMethodType.creditCard,
  description: 'Purchase',
);

if (result.success) {
  print('Payment successful: ${result.transactionId}');
}

// Consumer app configuration
class MyAppPaymentConfig {
  static LatinAmericanPaymentGateway gatewayFor(Country country) {
    return PaymentGatewayFactory.create(
      type: _gatewayTypeFor(country),
      config: PaymentGatewayConfiguration(
        publicKey: _getPublicKeyFor(country),
        sandbox: const bool.fromEnvironment('SANDBOX', defaultValue: true),
      ),
    );
  }

  static PaymentGatewayType _gatewayTypeFor(Country country) {
    return switch (country) {
      Country.costaRica => PaymentGatewayType.onvoPay,
      Country.colombia => PaymentGatewayType.wompi,
      Country.mexico => PaymentGatewayType.openpay,
      Country.brazil => PaymentGatewayType.mercadoPago,
      _ => throw UnsupportedError('Country not supported yet: $country'),
    };
  }
}