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.8.0

Not: Mevcut versiyonları pub.dev/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(
      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();

Dil (Locale)

POS+, isteğin header'ındaki locale alanına göre arayüzünü işlem süresince o dile çevirir ve cevap döndükten sonra cihazın önceki diline geri döner.

// Tüm istekler için varsayılan dil
await pluspay.initialize(locale: 'en');
// veya daha sonra
pluspay.locale = 'de';

// Tek bir istek için override
PPStartPaymentRequestModel.toRequest(
  orderCode: 'ORD-001',
  totalAmount: 150.0,
  paymentType: PPPaymentType.POS,
  paymentMethod: PPPaymentMethod.CC,
  locale: 'ar',
);
  • Desteklenen diller ppSupportedLocales sabitinde listelenir: tr, en, ar, de, fr, it, es, ru, zh.
  • en, en_US ve en-US biçimlerinin hepsi kabul edilir.
  • Alan gönderilmezse ya da desteklenmeyen bir dil gönderilirse POS+ mevcut dilinde açılır; hata dönmez.
  • Kiosk cihazlarında bu alan yok sayılır.
  • İsteğe ait locale, istemcinin locale değerinden önceliklidir.
  • error_message metinleri seçilen dilden bağımsız olarak her zaman Türkçedir (bkz. Hata Yönetimi).

İ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.

Metod İstek Modeli Yanıt Modeli Açıklama
startPayment PPStartPaymentRequestModel PPStartPaymentResponseModel Ödeme başlat
cancelPayment PPCancelPaymentRequestModel PPStartPaymentResponseModel Ödeme iptal et
startEftPayment PPEftPaymentRequestModel PPStartPaymentResponseModel EFT POS ödemesi başlat
cancelEftPayment PPEftCancelRequestModel PPStartPaymentResponseModel EFT POS ödemesini iptal et
startOrderPayment PPOrderPaymentRequestModel PPOrderPaymentResponseModel Sipariş ödemesi başlat
startMultiPayment PPMultiPaymentRequest PPMultiPaymentResponseModel Çoklu ödeme başlat
createOrder PPOrderCreateRequest PPOrderCreateResponseModel Ödeme başlatmadan sipariş oluştur
triggerEod PPEodRequestModel PPEodResponseModel Gün sonu tetikle
triggerParameters PPParameterRequestModel PPParametersResponseModel Parametre güncellemesi tetikle
getAvailablePaymentMethods PPAvailablePaymentMethodsRequestModel PPAvailablePaymentMethodsResponseModel Aktif/kullanılabilir ödeme yöntemlerini sorgula
getTransactionResult PPTransactionResultRequestModel PPStartPaymentResponseModel Tek bir işlemin sonucunu sorgula
getOrderResult PPOrderResultRequestModel PPOrderPaymentResponseModel Siparişi ve tüm işlemlerini sorgula
technicalCancel PPTechnicalCancelRequestModel PPTechnicalCancelResponseModel İşlemi teknik olarak iptal et

Aynı anda tek istek: POS+ aynı anda yalnızca bir isteği işler. Bir isteğin cevabı beklenirken yeni bir istek gönderilirse, istemci intent atmadan hemen PP_A2A_015 (PPA2AErrorCodes.requestInProgress) fırlatır; bekleyen istek etkilenmez. 20 dakikadan uzun süredir cevapsız kalan bir istek kaybolmuş sayılır ve yeni isteği engellemez.

İ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(
  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(
  orderCode: 'ORD-001',
  transactionId: 'TX-123',
  note: 'Müşteri iptali talep etti', // opsiyonel
);

EFT Ödeme

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

EFT İptal

PPEftCancelRequestModel.toRequest(
  transactionId: 'EFT-001',
  totalAmount: 250.0,
);

Sipariş Ödemesi

PPOrderPaymentRequestModel.toRequest(
  orderCode: 'ORD-001',
);

Gün Sonu (EOD)

PPEodRequestModel.toRequest(
  isAll: false,
  types: [PPEodType.POS, PPEodType.MULTINET],
);

Parametre Yükleme

PPParameterRequestModel.toRequest(
  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
);

İşlem Sonucu Sorgulama (Transaction Result)

Tek bir işlemin güncel durumunu sorgular; ödeme başlatmaz. Zaman aşımı (PP_A2A_014) veya beklenmeyen hata (PP_A2A_007) sonrası işlemin gerçekten tamamlanıp tamamlanmadığını öğrenmek için kullanın. İşlem siparişte bulunamazsa PP_A2A_016 döner.

final tx = await pluspay.getTransactionResult(
  PPTransactionResultRequestModel.toRequest(
    orderCode: 'ORD-001',
    transactionId: 'TX-001',
  ),
);
print(tx.status); // örn. "SUCCESS"

Sipariş Sonucu Sorgulama (Order Result)

Siparişi ve üzerindeki tüm işlemleri (web, link vb. kanallardan yapılanlar dahil) döner; ödeme başlatmaz. Her results[] öğesinde completed, işlem başarılıysa true olur.

final order = await pluspay.getOrderResult(
  PPOrderResultRequestModel.toRequest(orderCode: 'ORD-001'),
);
print('${order.status} — kalan: ${order.amountDue}');

Teknik İptal (Technical Cancel)

Sonucu belirsiz kalan veya tutarsız bir işlemi teknik olarak iptal eder. Başarısız olursa PP_A2A_012 döner.

Cihaz desteği: Teknik iptal yalnızca PAX ve Kozen cihazlarda desteklenir. Diğer cihazlarda (Sunmi, SoftPOS, Kiosk vb.) istek PP_A2A_012 ile döner.

await pluspay.technicalCancel(
  PPTechnicalCancelRequestModel.toRequest(
    orderCode: 'ORD-001',
    transactionId: 'TX-001',
  ),
);

Yanıt Modelleri

Bilinmeyen enum değerleri: POS+ bu paket sürümünün tanımadığı bir enum değeri döndürürse yanıt hata vermez; ilgili alan UNKNOWN olur (PPParameterTypes için unknown). Zorunlu enum alanları hiç gelmezse de UNKNOWN olur; nullable alanlarda null, alanın gönderilmediği anlamına gelir. Liste alanlarında (örn. methods) bilinmeyen değerler atlanır. UNKNOWN yalnızca yanıtlarda görülür, isteklerde kullanmayın.

PPStartPaymentResponseModel

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

Alan Tip Açıklama
id String İşlem ID
orderCode String Sipariş kodu
paymentType PPPaymentType? Kullanılan ödeme tipi
paymentMethod PPPaymentMethod? Kullanılan ödeme yöntemi
totalAmount double Toplam tutar
totalPaid double? Ödenen tutar
amountDue double? Kalan tutar
isPartial bool Parçalı ödeme olup olmadığı
partialType PPPartialPaymentType? Parçalı ödeme tipi
source String? Kaynak bilgisi
status String? Durum metni
actionStatus bool? İşlem başarı durumu
invoice PPInvoiceModel? Fatura detayları
payment PPPaymentModel? Ödeme detayları (RRN, maskelenmiş kart, slip)
delivery PPDeliveryModel? Teslimat detayları

PPOrderPaymentResponseModel

startOrderPayment ve getOrderResult metodları tarafından döndürülür.

Alan Tip Açıklama
grandTotal double Genel toplam
status PPOrderStatusEnum? Sipariş durumu
orderCode String Sipariş kodu
totalAmount double Toplam tutar
totalPaid double Ödenen tutar
amountDue double Kalan tutar
results List<PPOrderTransactionResult> İşlem sonuçları

PPEodResponseModel

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

Alan Tip Açıklama
results List<PPEodResponseItem> Tip bazında gün sonu sonuçları

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

PPParametersResponseModel

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

Alan Tip Açıklama
results List<PPParameterResultModel> Parametre güncelleme sonuçları

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.

Alan Tip Açıklama
paymentTypes List<PPPaymentTypeMethodsModel> Aktif ödeme tipleri

Her PPPaymentTypeMethodsModel:

Alan Tip Açıklama
code PPPaymentType? Ödeme tipi
methods List<PPPaymentMethod> O tip için kullanılabilir yöntemler
title String? Görünen ad (opsiyonel) 
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.

Alan Tip Açıklama
id String İşlem ID
orderCode String Sipariş kodu
products List<PPMultiPaymentProduct> Ürün detayları
transactions List<PPMultiPaymentTransaction> İşlem detayları
paymentType PPPaymentType? Ödeme tipi
paymentMethod PPPaymentMethod? Ödeme yöntemi
status PPOrderStatusEnum? Sipariş durumu
totalAmount double Toplam tutar
discountAmount double İndirim tutarı
subTotal double Ara toplam
taxAmount double Vergi tutarı
grandTotal double Genel toplam
totalPaid double Ödenen tutar
amountDue double Kalan tutar
preTotal PPMultiPaymentPreTotal Ön toplam bilgileri
deliveryType PPDeliveryTypeEnum? Teslimat tipi
customer PPMultiPaymentCustomer? Müşteri bilgileri

PPTechnicalCancelResponseModel

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

Alan Tip Açıklama
orderCode String Sipariş kodu
transactionId String İptal edilen işlem ID
status String Başarılı durumda "SUCCESS"

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, INSTALLMENT

PPPaymentMethod

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

CC, CASH, QR, QR_R, NFC, QUICKCODE, MOBILE, SWIPE, NONE, ONLINE, TRENDYOL, GETIR, YEMEKSEPETI, MIGROSYEMEK, CHIP, LINK, NFC_R, PAYCELL_LINK, PAYCELL_MERCHANT_PAGE

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, IADE

PPOrderSourceEnum

POS, WEB, TSM, KIOSK

Hata Yönetimi

POS+ bir hata yanıtı döndürdüğünde (örn. kullanıcı iptali, reddedilen ödeme), istemci PPA2AException fırlatır. Hata kodlarını PPA2AErrorCodes sabitleriyle karşılaştırın:

try {
  final result = await pluspay.startPayment(request);
} on PPA2AException catch (e) {
  switch (e.errorCode) {
    case PPA2AErrorCodes.requestInProgress:
      // önceki isteğin cevabını bekleyin
      break;
    case PPA2AErrorCodes.timeout:
    case PPA2AErrorCodes.unexpectedException:
      // işlemin durumunu getTransactionResult / getOrderResult ile sorgulayın
      break;
    default:
      showError(myTextFor(e.errorCode));
  }
}

message her zaman Türkçedir. POS+'ın döndürdüğü error_message, header'da gönderilen locale'den bağımsızdır. Kullanıcıya göstereceğiniz metni errorCode üzerinden kendiniz üretin.

Hata Kodu Sabit Açıklama
PP_A2A_001 requestCannotBeNull İstek boş
PP_A2A_002 dataCannotBeNull İşlem data gerektiriyor ama gönderilmedi
PP_A2A_003 invalidClientToken Client token geçersiz
PP_A2A_004 invalidEodRequest Geçersiz gün sonu isteği (is_all false iken types boş)
PP_A2A_005 invalidParameterRequest Geçersiz parametre isteği (is_all false iken types boş)
PP_A2A_006 invalidRequestParameter data içindeki bir alan eksik/geçersiz
PP_A2A_007 unexpectedException POS+'ta beklenmeyen hata; işlemin durumunu sorgulayın
PP_A2A_008 invalidRequestHeader header eksik/geçersiz
PP_A2A_009 invalidTransactionType Bilinmeyen transaction_type
PP_A2A_010 invalidFieldHeader İşlemin gerektirdiği header alanı (order_code, transaction_id) eksik/geçersiz
PP_A2A_011 needsToLoginAtLeastOnce POS+ bu cihazda hiç giriş yapmamış
PP_A2A_012 errorOnProcess İşlem POS+'ta başarısız oldu (detay mesajda)
PP_A2A_013 autoLoginFailed POS+ otomatik giriş yapamadı
PP_A2A_014 timeout Zaman aşımı (bkz. Zaman Aşımı)
PP_A2A_015 requestInProgress Önceki bir istek hâlâ işleniyor
PP_A2A_016 transactionNotFound TRANSACTION_RESULT: işlem siparişte bulunamadı
LAUNCH_INTENT_ERROR launchIntentError İstemci: POS+ uygulaması başlatılamadı
PP-A2A-PARSE parseError İstemci: yanıt JSON'ı ayrıştırılamadı

Zaman Aşımı

  • POS+ kapalıyken gelen bir istekte, uygulamanın açılıp isteği karşılayacak hâle gelmesi için 3 dakika beklenir.
  • İşlemin kendisi için üst sınır 15 dakikadır.
  • İki durumda da POS+ PP_A2A_014 döner.
  • İstemci tarafında kendi zaman aşımınızı uyguluyorsanız bu süre 15 dakikadan uzun olmalıdır; aksi hâlde POS+'ta tamamlanmış bir ödeme sizin tarafınızda başarısız görünebilir.
  • PP_A2A_014 veya PP_A2A_007 aldığınızda işlemin gerçek sonucunu getTransactionResult (TRANSACTION_RESULT) ya da getOrderResult (ORDER_RESULT) ile sorgulayın.

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

Libraries

pluspay_a2a