pluspay_a2a #

POS+ (Pluspay) Android uygulaması ile App-to-App (A2A) iletişim kurmak için geliştirilmiş Flutter eklentisi. Bu paket, Flutter uygulamanızdan POS+ uygulamasını başlatarak ödeme, iptal, EFT işlemleri, sipariş ödemeleri, gün sonu raporları ve parametre güncellemeleri yapmanızı sağlar.

Not: Bu paket yalnızca Android platformunu desteklemektedir. iOS desteği bulunmamaktadır.

Kurulum #

Aşağıdaki komutu çalıştırın:

flutter pub add pluspay_a2a

Veya pubspec.yaml dosyanıza elle ekleyip flutter pub get çalıştırın:

dependencies:
  pluspay_a2a: ^0.7.0

Not: Mevcut versiyonları pub.flutter-io.cn/packages/pluspay_a2a sayfasından görebilirsiniz.

Hızlı Başlangıç #

import 'package:pluspay_a2a/pluspay_a2a.dart';

// 1. İstemciyi oluşturun ve başlatın
final pluspay = PPA2AClient();
await pluspay.initialize();

// 2. Ödeme başlatın
try {
  final result = await pluspay.startPayment(
    PPStartPaymentRequestModel.toRequest(
      clientToken: 'YOUR-CLIENT-TOKEN',
      orderCode: 'ORD-001',
      totalAmount: 150.0,
      paymentType: PPPaymentType.POS,
      paymentMethod: PPPaymentMethod.CC,
    ),
  );
  print('Ödeme başarılı: ${result.id}');
} on PPA2AException catch (e) {
  print('Ödeme başarısız: ${e.errorCode} - ${e.message}');
}

// 3. İşiniz bittiğinde kaynakları temizleyin
await pluspay.dispose();

İstemci Metodları #

Tüm metodlar PPA2AClient sınıfı üzerindedir. Her metod başarılı durumda tipli bir response modeli döner, hata durumunda PPA2AException fırlatır.

İstek Modelleri #

Her istek modeli, düz ve kullanışlı bir API sunan toRequest factory constructor'ına sahiptir. İlgili alanları doğrudan geçirirsiniz; model dahili header + data yapısını sizin için oluşturur.

Ödeme Başlat #

PPStartPaymentRequestModel.toRequest(
  clientToken: 'YOUR-CLIENT-TOKEN',
  orderCode: 'ORD-001',
  totalAmount: 100.0,
  paymentType: PPPaymentType.POS,
  paymentMethod: PPPaymentMethod.CC,
  installment: 3,               // opsiyonel
  isPartial: false,              // opsiyonel, varsayılan: false
  partialType: null,             // opsiyonel
  products: [],                  // opsiyonel
  billingInformation: null,      // opsiyonel
);

Ödeme İptal #

PPCancelPaymentRequestModel.toRequest(
  clientToken: 'YOUR-CLIENT-TOKEN',
  orderCode: 'ORD-001',
  transactionId: 'TX-123',
  note: 'Müşteri iptali talep etti', // opsiyonel
);

EFT Ödeme #

PPEftPaymentRequestModel.toRequest(
  clientToken: 'YOUR-CLIENT-TOKEN',
  totalAmount: 250.0,
  paymentType: PPPaymentType.POS,
  paymentMethod: PPPaymentMethod.CC,
  transactionId: 'EFT-001',
  taxRate: 18,
  installment: null, // opsiyonel
);

EFT İptal #

PPEftCancelRequestModel.toRequest(
  clientToken: 'YOUR-CLIENT-TOKEN',
  transactionId: 'EFT-001',
  totalAmount: 250.0,
);

Sipariş Ödemesi #

PPOrderPaymentRequestModel.toRequest(
  clientToken: 'YOUR-CLIENT-TOKEN',
  orderCode: 'ORD-001',
);

Gün Sonu (EOD) #

PPEodRequestModel.toRequest(
  clientToken: 'YOUR-CLIENT-TOKEN',
  isAll: false,
  types: [PPEodType.POS, PPEodType.MULTINET],
);

Parametre Yükleme #

PPParameterRequestModel.toRequest(
  clientToken: 'YOUR-CLIENT-TOKEN',
  isAll: true,
  types: null,
);

Mevcut Ödeme Yöntemleri #

POS+ üzerinde o an aktif/kullanılabilir ödeme tiplerini ve yöntemlerini sorgular. Ekstra parametre gerektirmez.

PPAvailablePaymentMethodsRequestModel.toRequest();

Sipariş Oluşturma (Order Create) #

Ödeme başlatmadan yalnızca sipariş oluşturur. Oluşturulan sipariş daha sonra aynı orderCode ile startOrderPayment üzerinden tahsil edilebilir. orderCode POS+ üzerinde zaten kayıtlıysa sipariş güncellenir.

PPOrderCreateRequest.toRequest(
  orderCode: 'ORD-001',
  orderDate: DateTime.now(),
  products: [
    ProductModel(
      id: 1,
      sku: 'SKU-001',
      title: 'Ürün 1',
      price: 100.0,
      quantity: 1,
      taxRate: 10,
      unit: PPQtyEnums.ADET,
      vatInclude: true,
      productType: PPProductTypeEnum.PHYSICALLY,
      discountValue: 0,
    ),
  ],
  currency: PPCurrencyType.TRY,                // opsiyonel, varsayılan: TRY
  deliveryType: PPDeliveryTypeEnum.CASH_ORDER, // opsiyonel, varsayılan: CASH_ORDER
  discountAmount: 0,                           // opsiyonel, varsayılan: 0
  billingInformation: null,                    // opsiyonel
  installment: null,                           // opsiyonel
  groupCode: null,                             // opsiyonel
  note: null,                                  // opsiyonel
);

Yanıt PPOrderCreateResponseModel (PPMultiPaymentResponseModel ile aynı sipariş detayı yapısı) döner.

Çoklu Ödeme (Multi Payment) #

PPMultiPaymentRequest.toRequest(
  orderCode: 'ORD-001',
  orderDate: DateTime.now(),
  changePaymentStatus: true,
  products: [
    ProductModel(
      id: 1,
      sku: 'SKU-001',
      title: 'Ürün 1',
      price: 100.0,
      quantity: 1,
      taxRate: 10,
      unit: PPQtyEnums.ADET,
      vatInclude: true,
      productType: PPProductTypeEnum.PHYSICALLY,
      discountValue: 0,
      otvOrani: 0,             // opsiyonel, varsayılan: 0
      konaklamaOrani: 0,       // opsiyonel, varsayılan: 0
    ),
  ],
  transactions: [
    TransactionModel(
      paymentType: PPPaymentType.POS,
      totalAmount: 100.0,
      paymentMethod: PPPaymentMethod.CC,
    ),
  ],
  currency: PPCurrencyType.TRY,           // opsiyonel, varsayılan: TRY
  deliveryType: PPDeliveryTypeEnum.CASH_ORDER, // opsiyonel, varsayılan: CASH_ORDER
  discountAmount: 0,                       // opsiyonel, varsayılan: 0
  billingInformation: null,                // opsiyonel
  installment: null,                       // opsiyonel
  groupCode: null,                         // opsiyonel
  note: null,                              // opsiyonel
  canTryAgain: true,                       // opsiyonel, varsayılan: true
);

Yanıt Modelleri #

PPStartPaymentResponseModel #

startPayment, cancelPayment, startEftPayment ve cancelEftPayment metodları tarafından döndürülür.

PPOrderPaymentResponseModel #

startOrderPayment metodu tarafından döndürülür.

PPEodResponseModel #

triggerEod metodu tarafından döndürülür.

Her PPEodResponseItem; eodType (PPEodType), success (bool) ve opsiyonel errorMessage alanlarını içerir.

PPParametersResponseModel #

triggerParameters metodu tarafından döndürülür.

Her PPParameterResultModel; type (PPParameterTypes), completed (bool) ve opsiyonel errorMessage alanlarını içerir.

PPAvailablePaymentMethodsResponseModel #

getAvailablePaymentMethods metodu tarafından döndürülür. Liste, oturumun profil/cihaz filtrelerinden geçmiş hâliyle döner — yani "şu an gerçekten yapılabilecek" ödeme yöntemleridir.

Her PPPaymentTypeMethodsModel:

final res = await pluspay.getAvailablePaymentMethods(
  PPAvailablePaymentMethodsRequestModel.toRequest(),
);
for (final type in res.paymentTypes) {
  print('${type.code} -> ${type.methods}');
}

PPMultiPaymentResponseModel #

startMultiPayment metodu tarafından döndürülür.

Enum'lar #

PPPaymentType #

POS+ tarafından desteklenen ödeme tipleri.

POS, PAYCELL, HEPSIPAY, ISTANBULCARD, CASH, ONLINE, BANK_TRANSFER, GASTROPAY, CIO_CARD, IWALLET, PAYE, MULTINET, METROPOL, FASTPAY, TICKET, EDENRED, SETCARD, SODEXO, GETIRPAY, TOKENFLEX, YEMEKMATIK, ON_CREDIT, VIRTUAL_POS, CUZDANPLUS

PPPaymentMethod #

POS+ tarafından desteklenen ödeme yöntemleri.

CC, CASH, QR, QR_R, NFC, QUICKCODE, MOBILE, SWIPE, NONE, ONLINE, TRENDYOL, GETIR, YEMEKSEPETI, MIGROSYEMEK

PPEodType #

Gün sonu rapor tipleri.

POS, CASH, BANK_TRANSFER, ONLINE, OTHER, MULTINET, SODEXO, SETCARD, TICKET, METROPOL, PAYE, TOKENFLEX, EDENRED, CUZDANPLUS, IWALLET

PPParameterTypes #

Parametre güncelleme tipleri.

bank, multinet, metropol, paye, iwallet

PPPartialPaymentType #

AMOUNT, PRODUCT

PPOrderStatusEnum #

CANCEL, NOT_RESPONSE, WAITING, SUCCESS

PPDeliveryStatusEnum #

WAITING, PREPREING, READY, ONWAY, COMPLETE, CANCEL

PPDeliveryTypeEnum #

CASH_ORDER, PACKAGE_ORDER, TABLE_ORDER, TAKE_AWAY, TAKE_CLOSE

PPCurrencyType #

TRY, USD, EUR, GBP

PPProductTypeEnum #

PHYSICALLY, VIRTUAL, INFO, MD, DSN, QP, KFO, COMMISSION, HGS

PPQtyEnums #

Miktar birimleri.

ADET, KG, GR, LT, MT, KOLI, PAKET, PORSIYON

PPDiscountTypeEnum #

PERCENTAGE, FIXED_AMOUNT

PPDocumentTypeEnum #

EFATURA, EARSIV, BILGIFISI

PPDocumentStatusEnum #

SUCCESS, CANCEL, FAIL, WAITING, NONE

PPTransactionStatusEnum #

SUCCESS, CANCEL, FAIL, NONE, WAITING, NOT_RESPONSE

PPTransactionTypeEnum #

START, SATIS, CANCEL, REFUND

PPOrderSourceEnum #

POS, WEB, KIOSK

Hata Yönetimi #

POS+ bir hata yanıtı döndürdüğünde (örn. yetersiz bakiye, kullanıcı iptali), istemci PPA2AException fırlatır:

try {
  final result = await pluspay.startPayment(request);
} on PPA2AException catch (e) {
  print(e.errorCode);  // örn. "PP-A2A-006"
  print(e.message);    // örn. "İşlem kullanıcı veya sistem tarafından iptal edildi!"
}

İstemci tarafındaki hatalar için de aynı exception fırlatılır:

Yaşam Döngüsü #

class _MyPageState extends State<MyPage> {
  final _pluspay = PPA2AClient();

  @override
  void initState() {
    super.initState();
    _pluspay.initialize();
  }

  @override
  void dispose() {
    _pluspay.dispose();
    super.dispose();
  }
}

initialize() diğer tüm metodlardan önce çağrılmalıdır. Uygulamanın paket bilgilerini alır ve POS+ sonuçları için bir broadcast receiver kaydeder. İstemciye artık ihtiyaç kalmadığında receiver'ı temizlemek için dispose() çağrılmalıdır.

Gereksinimler #

• Yalnızca Android
• Cihazda POS+ uygulaması yüklü olmalıdır
• Minimum SDK: 24