Servisin Kullanım Amacı
Servisin temel olarak iki kullanım amacı bulunmaktadır.
Bunlardan ilki ödeme alma veya ödeme iptal etme işlemlerinde, servislerden beklenmedik bir şekilde cevap alınamadığı durumlarda(bağlantı kopması, uygulamanın kapanması vb.) başlatılan işlemin durumunun bilinemeyeceğinden o işlemin geri alınması(reverse) için kullanılmasıdır. Bu gibi durumlarda eğer anlık olarak geri alma servis çağrısı yapılamıyor ise bu geri alınacak işlem kayıt altına alınmalıdır. Kayıt altına alınan geri alma isteği gönderilmeden de diğer servis istekleri yapılmamalıdır.
Bir diğer kullanım amacı ise Multinet sisteminde başarılı bir şekilde oluşmuş satış işleminin üye iş yerinin bilgisi ve isteği doğrultusunda iptal edilmesinin sağlanması için kullanılmısıdır.
Kart kullanıcıları için olan client uygulamalarda bu servis sadece satış işlemi sırasında oluşabilecek olan beklenmedik durumlarda geri alma(reverse) işlemi yapacak şekilde bağlanmalıdır.
Üye iş yerleri için kullanılan yönetim uygulamalarında da başarılı gerçekleşmiş bir satış işlemini iptal etmek için veya iptal etme işlemi sırasında gerçekleşecek beklenmedik durumlar sonrasında başlatılan iptal işlemini geri almak için kullanılmalıdır.
Servis Çağrısı Yapılması
-
MultiPaySdk.rollbackPayment( requestId = "sampleRequestId", sign = "sampleSign", merchantReferenceNumber = "sampleMerchantReferenceNumber", terminalReferenceNumber = "sampleTerminalReferenceNumber", rollbackReferenceNumber = "sampleRollbackReferenceNumber", reason = reason, // 2: Cancel || 3: Reversal referenceNumberType = referenceNumberType, // 0: Client || 1: Server referenceNumber = "sampleReferenceNumber", listener = multiPaySdkListener ) -
MultiPaySdk.rollbackPayment( "sampleRequestId", "sampleSign", "sampleMerchantReferenceNumber", "sampleTerminalReferenceNumber", "sampleRollbackReferenceNumber", reason, // 2: Cancel || 3: Reversal referenceNumberType, // 0: Client || 1: Server "sampleReferenceNumber", multiPaySdkListener );
Metodun değişkenleri:
requestId : Her servis isteği için unique olarak yaratılıp gönderilmesi gereken id değeri. Oluşturulması aşamasında unique bir değer olması dışında bir zorunluluk yoktur. Bu değer UUID v4 formatında olmalıdır.
Servis isteği sonucunda, işlemin doğru olup olmadığı validasyonunun yapılabilmesi için bu değer tekrar kullanılacaktır.
sign : Servis iletişim sürecinin güvenliğinin sağlanması için oluşturulması gereken bir değişkendir.Bu değişkenin, entegrasyonu yapan uygulama tarafından yaratılıp gönderilmesi gerekmektedir. Bu değerin nasıl yaratılacağı entegrasyon aşamasında tarafınıza özel olarak iletilecektir.
merchantReferenceNumber : Bu değer tarafınıza özel olarak iletilecektir. (Ödeme alma servisinde kullanılan merchantReferenceNumber değişkeni ile aynı değerde olacaktır)
terminalReferenceNumber : Bu değer tarafınıza özel olarak iletilecektir. (Ödeme alma servisinde kullanılan terminalReferenceNumber değişkeni ile aynı değerde olacaktır)
rollbackReferenceNumber : Her servis isteğinde tarafınızca unique olarak yaratılıp gönderilmesi gerekmektedir.
reason : 2(Cancel), 3(Reversal) olmak üzere 2 çeşit değer alabilir.
-
Ödeme alma veya ödeme iptal etme işlemlerinde, servislerden beklenmedik bir şekilde cevap alınamadığı durumlarda başlatılan işlemin geri alınması için buradaki değer 3(Reversal) olmalıdır.
-
Başarılı gerçekleşmiş bir satış işlemini iptal etmek için buradaki değer 2(Cancel) olmalıdır.
referenceNumberType : 0(Client), 1(Server) olmak üzere 2 çeşit değer alabilir.
-
Ödeme alma veya ödeme iptal etme işlemlerinde, servislerden beklenmedik bir şekilde cevap alınamadığı durumlarda başlatılan işlemin geri alınması için buradaki değer 0(Client) olmalıdır.
-
Başarılı gerçekleşmiş bir satış işlemini iptal etmek için buradaki değer 1(Server) olmalıdır.
referenceNumber : Bu alan bir önceki referenceNumberType parametresinin içeriğine göre değer alır.
-
referenceNumberType 0 ise başlatılan bir ödeme alma işleminin geri alınması durumu oluştuğunda, ödeme alma servisinde (confirmPayment) kullanılmış olan transferReferenceNumber değeri girilmelidir. Başlatılan bir ödeme iptal etme işleminin geri alınması durumu oluştuğunda, bu dokümanda anlatılan rollbackReferenceNumber değeri girilmelidir.
-
referenceNumberType 1 ise iptali yapılacak ödemenin, ödeme alma servisinden (confirmPayment) dönen cevapta, MultipaySdkListener’ın onConfirmPaymentReceived metodundan gelen transferServerReferenceNumber değeri girilmelidir.
listener : Servisten dönen cevabı dinleyebilmek için kullanılan callback. MultiPaySdkListener sınıfının bir ojesi yaratılıp kullanılır.
Servis Cevabının Alınması
MultiPaySdkListener objesi üzerinde;
onRollbackPaymentReceived metodu override edilerek ödeme geri alma servisinden gelen cevap dinlenir. Burada ödemenin doğruluğunu kontrol etmek için bir validasyon yapmak gerekmektedir. Validasyon başarılı bir şekilde sonuçlanırsa ödeme geri alma işleminin gerçekleşmiş olduğu anlaşılmaktadır.
Not : Validasyon detayları entegrasyon aşamasında tarafınıza özel olarak iletilecektir.
onServiceError metodu override edilerek de oluşabilecek hatalarla ilgili geri dönüş alınabilir.
-
private var multiPaySdkListener: MultiPaySdkListener? = object : MultiPaySdkListener { override fun onRollbackPaymentReceived(sign: String, rollbackServerReferenceNumber: String) { Log.i(TAG, "sign = $sign rollbackServerReferenceNumber = $rollbackServerReferenceNumber") // Validate rollback payment } override fun onServiceError(error: String?, code: Int) { Log.i(TAG, "error = $error code = $code") } } -
MultiPaySdkListener multiPaySdkListener = new MultiPaySdkListener() { @Override public void onRollbackPaymentReceived(@NotNull String sign, @NotNull String rollbackServerReferenceNumber) { Log.i(TAG, "sign = " + sign + "\nrollbackServerReferenceNumber = " + rollbackServerReferenceNumber); // Validate rollback payment } @Override public void onServiceError(@org.jetbrains.annotations.Nullable String error, int code) { Log.i(TAG, "error code = " + code + "\nerror = " + error); } @Override public void onConfirmPaymentReceived(@NotNull String sign, @NotNull String transferServerRefNo) { } @Override public void onUnSelectWalletReceived(@org.jetbrains.annotations.Nullable UnselectWalletResponse unSelectWallet) { } @Override public void onTokenReceived(@NotNull String token) { } @Override public void onMultiPaySdkClosed() { } @Override public void onSingeWalletReceived(@NotNull SingleWalletResponse singleWallet) { } };
