MOBILEPAX ENTERPRISE API (WEB SERVİS) Versiyon: 1.0.5
İçindekiler İçindekiler... 2 1. Belgenin Amacı... 3 2. Sistem Gereksinimleri... 3 3. Belge Sürümleri... 3 4. Kullanım Şekli... 3 4.1 Web den Başlatma... 3 4.1.1 Enterprise API Metotları:... 4 4.2 SMS ile Başlatma... 6 4.3 Ödeme Bilgilerinin Geri Dönüşü... 7 4.3.1 MobilePaxSMSStart... 7 4.3.2 MobilePaxWEBStart... 8 5. Hata Kodları... 10
1. Belgenin Amacı Enterprise API SOAP tabanlı bir entegrasyon sistemidir. Enterprise API de satın alma işlemi boyunca satın alma işlemini gerçekleştiren kullanıcı satın alma işlemini yaptığı site üzerinden başka bir siteye yönlendirilmek zorunda değildir. Satın alma işlemini başlatmak için satın alınan ürünü veya hizmeti Mobilepax servisine tanımlamanız gerekmez, GSM numarası ve tahsil edilecek tutarı göndererek satın alma işlemini başlatabilirsiniz. Ancak SMS ile başlatma ve buton oluşturmak için ürünlerinizi yine de Mobilepax sistemlerine tanımlamanız gerekmektedir. Bu doküman, üye iş yeri kullanıcılarının Mobilepax servisini mobil tahsilatı gerçekleştirmelerini sağlamak amacıyla kendi sistemlerine entegre edebilmeleri için hazırlanmıştır. 2. Sistem Gereksinimleri Mobilepax Product çözümünü kullanabilmeniz için gereken minimum sistem gereksinimleri aşağıda belirtilmiştir. Windows 98 SE, ME, 2000, XP, UNIX, Linux ya da MacOS İşletim Sistemi Internet Explorer 6 SP1 (Windows Platformu için) 3. Belge Sürümleri Tarih Sürüm Açıklama 10.08.2009 1.0.0 İlk sürüm 08.09.2009 1.0.1 Hata Kodları Güncellendi 14.11.2009 1.0.2 SMS ile Başlatma ve Web den Başlatma Eklendi 17.08.2010 1.0.3 Hata Kodları Güncellendi 25.08.2010 1.0.4 Hata Kodları Güncellendi 13.01.2011 1.0.5 Ödeme Bilgilerinin Geri Dönüşü Güncellendi 4. Kullanım Şekli 4.1 Web den Başlatma Merchantlar ödeme isteklerini aşağıdaki servis adresini kullanarak bize iletirler. http://api.mobilepax.com/mobilepax.asmx Servisin Wsdl dokümanına http://api.mobilepax.com/mobilepax.asmx?wsdl adresinden ulaşabilirsiniz.
4.1.1 Enterprise API Metotları: Start Mobilepax Request Data <startmobilepax xmlns="http://mobilepax.com/"> <merchantid>int</merchantid> <username>string</username> <password>string</password> <gsmno>string</gsmno> <paymenttype>int</paymenttype> <chargingunit>string</chargingunit> <chargingvalue>double</chargingvalue> <productdescription>string</productdescription> </startmobilepax> </soap:body> </soap:envelope> Request Data - Parametre Değerleri Merchantid String username String password GSM No Paymenttype Chargingunit Chargingvalue ProductDescription Üye İş Yeri Kodu API'leri kullanmak için gerekli Üye İş Yeri Kullanıcı Adı (merchant kodu) bilgisi API'leri kullanmak için gerekli Üye İş Yeri Parola Bilgisi Ödeme yapılacak GSM no Ödeme tipi SMS ya da TL cinsinden ödeme birimi Ödeme alınacak tutar Mesaj içinde ürün hakkında gidecek bilgi ProductDescription Örnek: Armut işlem bedeli 2.4 TL. Onay için Evet ; İptal için Hayir yazarak mesajı cevaplayınız. Not: Chargingvalue değerinde Nokta işareti kullanılmalıdır.
Paymenttype - Ödeme Tipi Adları ve Numaraları TURKCELL MOBİL ÖDEME 2 Fiziksel Ürün %8 3 Aidat / Otomat / Abonelik 4 Dijital İçerik / Hizmet / Servis - 20 TL Altı 5 Arkadaşlık / Sosyal Ağ / Sohbet - 20 TL Altı 6 Online Oyun 20 TL altı 29 Arkadaşlık / Sosyal Ağ / Sohbet - 20 TL Üstü 30 Bahis 34 Online Oyun 20 TL Üstü 36 Kutulu Oyun 37 Dijital İçerik / Hizmet / Servis - 20 TL Üstü 59 Fırsat Siteleri 38 Sigorta 61 Mobil Bilet 63 Abonelik 73 Eğitim AVEA MOBİL ÖDEME 10 Fiziksel Ürün 11 Dijital İçerik / Hizmet / Servis 12 Online Oyun 13 Arkadaşlık / Sosyal Ağ / Sohbet 33 Fiziksel Ürün 2 39 Aidat/Otomat 40 Etkinlik/Bilet 41 Grup İndirim 42 Kutulu Oyun 43 Film Kulübü 58 TURP 72 Eğitim 74 Oyun (Sadece Ön Ödemeli) 75 MyMediks 76 Sigorta
VODAFONE MOBİL ÖDEME 65 Biletleme / Fastfood / Kamu 66 Abonelik / Otomat 67 Arkadaşlık / Sosyal Ağ / Sohbet 68 Fiziksel Ürün 69 İçerik 70 İnternet Servisleri 71 Oyun Response Data <startmobilepaxresponse xmlns="http://mobilepax.com/"> <startmobilepaxresult> <status>string</status> <errcode>string</errcode> <transactionid>string</transactionid> </startmobilepaxresult> </startmobilepaxresponse> </soap:body> </soap:envelope> Response Data - Parametre Değerleri Status: İşlem durumu ( ERR dönerse işlem hatalı, OK dönerse işlem başarılı) transactionid: Yapılan işleme ait dönen tekil ID. 4.2 SMS ile Başlatma Ödeme yapılacak GSM numarasından servis numarasına üye iş yerine smskeyword u ve ürün keyword bilgisi yazılarak mesaj gönderilir. Üye iş yeri smskeyword bilgisi üyelik aktivasyonu yapılırken Mobilepax destek birimleri tarafından verilir ancak ürünlere ait sms keywordleri ürün tanımlamaları yapılırken üye iş yeri tarafından belirtilir.
Firma SMSkeyword= Mobiltim ürün keywordu= test1 gönderilir. mobiltim test1 yazılarak 8044 e mesaj gönderilir. Mesaj gönderildikten sonra Mobilepax tarafından SMS gönderen son kullanıcıya onay mesajı döner. Bu onay mesajı üye iş yerinin ürünü eklerken belirtmiş olduğu mesaj metnidir. Müşteri gelen mesajı onaylayarak 8044 e geri dönüş yapar ve charging işlemi yapılır. Charging işlemi başarılı ise üye iş yerinden 8 karakterli onay mesajı alınır ve son kullanıcıya SMS olarak gönderilir. 4.3 Ödeme Bilgilerinin Geri Dönüşü Merchant (üye iş yeri) tarafından host edilecek servis detayları Merchantlar yapılan isteğin durumunu kendilerine iletmemiz amacıyla taraflarında ekte verdiğimiz wsdl dokümana uygun bir web servisi host ederler. Host edilen web servisiyle ilgili açıklamalar aşağıda bulunmaktadır. Web servisini doğru yazıp yazmadıklarını ise; mobilepaxwstester.exe ile Windows komut satırından mobilepaxwstester.exe webservis URL si (örn: mobilepaxwstester.exe http://api.mobilepax.com/mobilepaxclient.asmx gibi) çalıştırdıklarında yazılım web servisini doğru yazıp yazmadıklarını söyleyecektir. Yazdığınız web servisini host edip bize URL ini göndermeniz gerekmektedir. MobilePaxSMSStart MobilePaxWEBStart 4.3.1 MobilePaxSMSStart SMS ile başlatılan işlemlerde geri dönüş için kullanılacak metot. Request Data <MobilePaxSMSStart xmlns="http://mobilepax.com/"> <TransactionId>string</TransactionId> <ProductCode>string</ProductCode> <GsmNo>string</GsmNo> </MobilePaxSMSStart> </soap:body> </soap:envelope>
Request Data - Parametre değerleri TransactionId: Sistem tarafından takip edilmek amacıyla oluşturulan tekil ID ProductCode: İşlem yapılan ürün kodu GsmNo: İşlemi başlatan GSM numarası Response Data <MobilePaxSMSStartResponse xmlns="http://mobilepax.com/"> <MobilePaxSMSStartResult> <Status>string</Status> <ProductMsg>string</ProductMsg> <VarinatCode>string</VarinatCode> </MobilePaxSMSStartResult> </MobilePaxSMSStartResponse> </soap:body> </soap:envelope> Response Data - Parametre Değerleri Status: İşlem durumu ( ERR dönerse işlem hatalı, OK dönerse işlem başarılı) ProductMsg: Merchantın müşteriye döndüğü mesajın içeriğidir. VarinatCode: Müşteriye dönen SMS içinde olan, ürüne ait, işleme ait, uygulamaya ait müşterinin kullanım amacına göre değişen koddur. 4.3.2 MobilePaxWEBStart Web ile başlatılan işlemlerde geri dönüş için kullanılacak metot. Request Data <MobilePaxWEBStart xmlns="http://mobilepax.com/"> <TransactionId>string</TransactionId> <ChargingOK>boolean</ChargingOK> </MobilePaxWEBStart>
</soap:body> </soap:envelope Request Data - Parametre Değerleri TransactionId: Web den başlatmak için kullanılan web servisinden dönen transactionid ChargingOK: Müşteri tahsilat için gelen mesajı Evet yazarak onaylarsa OK döner. Hayir yazarsa ERR döner. Zaman aşımı gerçekleşirse ERR döner. Response Data <MobilePaxWEBStartResponse xmlns="http://mobilepax.com/"> <MobilePaxWEBStartResult> <Status>string</Status> <ProductMsg>string</ProductMsg> <VarinatCode>string</VarinatCode> </MobilePaxWEBStartResult> </MobilePaxWEBStartResponse> </soap:body> </soap:envelope> Response Data - Parametre Değerleri Status: İşlem durumu ( ERR dönerse işlem hatalı, OK dönerse işlem başarılı) ProductMsg: Merchantın müşteriye döndüğü mesajın içeriğidir. VarinatCode: Yapılan işlemin sonucuyla ilgili, ödeme yapan numaraya bilgilendirme amacıyla gönderilen ID.
5. Hata Kodları 11 Web Servisine Boş Alan Gönderilemez 12 Hatalı MerchantId, Username veya Password 13 Charging Value Bir Seferde İzin Verilen Değerden Fazla 14 productdescription 50 karakterden Büyük 15 chargingunit SMS veya TL Girilebilir 16 Günlük Ödeme Limiti Aşıldı 17 Saatlik Ödeme Limiti Aşıldı 18 Üye İş Yeri Günlük Ödeme Limiti Aşıldı 99 Sistem Hatası. Tanımlanamayan Hata