Giriş - İstanbul Halk Ekmek A.Ş. · Web viewTEKNİK ENTEGRASYON DOKÜMANI [email protected] İçindekiler 1Giriş3 1.1Temel Bilgiler3 1.2Kurgu Seçimi3 1.2.1Basic API3 1.2.2Pro

TEKNİK ENTEGRASYON DOKÜMANI

[email protected]

Versiyon [email protected]

1

İçindekiler1 Giriş................................................................................................................................................3

1.1 Temel Bilgiler..........................................................................................................................3

1.2 Kurgu Seçimi...........................................................................................................................3

1.2.1 Basic API.........................................................................................................................3

1.2.2 Pro API............................................................................................................................3

1.2.3 API Plus...........................................................................................................................4

1.2.4 SMS-Keyword Kurgusu....................................................................................................4

1.2.5 SMS-Keyword Kurgusu (Pinli)..........................................................................................4

1.2.6 SMS-Keyword Yönlendirme............................................................................................5

1.2.7 Abonelikler......................................................................................................................5

2 Basic API Entegrasyonu..................................................................................................................7

3 Pro API Entegrasyonu.....................................................................................................................9

4 API Plus Entegrasyonu..................................................................................................................12

5 SMS-Keyword Entegrasyonu........................................................................................................16

6 SMS-Keyword Entegrasyonu (Pinli)..............................................................................................17

7 SMS-Keyword Yönlendirme Entegrasyonu...................................................................................18

8 Abonelik Servisi............................................................................................................................19

8.1 Abonelik Listeleme...............................................................................................................19

8.2 Abonelik Detayı Görüntüleme..............................................................................................21

8.3 Aboneliği İptal Etme.............................................................................................................23

9 Bilgi SMS’i Gönderim Servisi.........................................................................................................24

10 SMS İçeriği İletim Servisi...........................................................................................................25

11 İşlem Sonuç Servisi...................................................................................................................27

11.1 Email Yöntemi.......................................................................................................................27

11.2 Web Sayfası Yöntemi............................................................................................................27

11.3 Web Servis Yöntemi..............................................................................................................29


2

1 GirişBu dokümanda üye işyerlerinin 3pay|Mikro Ödeme tarafından sunulan ödeme kurgularından kendileri için uygun olan(lar)ı seçmeleri için senaryo örnekleri ve sistemlerini bu kurgularla ödeme yapılabilir duruma nasıl getireceklerini adım adım gösteren açıklamalar anlatılmıştır.

1.1 Temel Bilgiler 3pay|Mikro Ödeme sisteminde yapılan tüm işlemlerin süresi max. 5 dakikadır. Bu sürede

tamamlanmayan işlemler iptal edilir. Kurgu seçimi yapıldıktan sonra ilgili kurgu ile ödeme işlemi yapılabilmesi için seçimin

[email protected] adresine bildirilmesi gereklidir. Entegrasyon tamamlanana kadar üye işyeri 3pay|Mikro Ödeme sisteminde test statüsünde

tanımlıdır. Bu statüde sadece 0.01 TL’lik işlem yapılabilmektedir. Gerçek ücretler entegrasyon tamamlandıktan ve operatörlerden onay alındıktan sonra devreye alınmaktadır.

1.2 Kurgu SeçimiKuruluşunuzun ihtiyaçlarına, sistem gereksinimlerine ve işlem hacmine paralel olarak, bu bölümde açıklanan kurgulardan uygun olanı seçerek ilgili kurgunun başlığına geçebilirsiniz.

1.2.1 Basic APIAz ve sabit sayıda ürünü olan, ürün fiyatları sık değişmeyen, detaylı sistem entegrasyonu yapmak istemeyen, satışları bir web sitesi üzerinden yapan kuruluşlar için uygun bir çözümdür. Mobil ödemeye ek olarak kredi kartı ile ödeme yapılması da mümkündür.

Bu kurguda kuruluşun yetkilisi tarafından MÖ panelinde bir ürün tanımlanır ve panelde ürün için sunulan sabit link, satış yapılacak web sitesinde ürünün satış sayfasına eklenir. Bu link, müşteriyi MÖ ortak ödeme sayfasına yönlendirerek ödeme yapılmasını sağlar ve işlem sonunda siteye geri yönlendirir.

Her yeni ürün için üye işyeri yetkilisi tarafından ayrı bir ürün oluşturulmalı, ürünlerin fiyatları her değiştiğinde panelden bu fiyatlar güncellenmelidir.

Kurgunun entegrasyonu için, bkz. Basic API Entegrasyonu.

Basic API kullanıldığında gerçekleşen akış için aşağıdaki simgeye çift tıklayınız:

1.2.2 Pro APIPro API, web servis tabanlı olan ve ödeme işlemini 3pay|Mikro Ödeme ortak ödeme sayfası üzerinden gerçekleştiren bir 3pay|Mikro Ödeme çözümüdür. Satışı bir web sitesi üzerinden yapan, çok sayıda ve değişken fiyatlı ürün veya hizmetleri bulunan şirketler için uygun bir çözümdür. Mobil ödemeye ek olarak kredi kartı ve TTNET Ödeme ile ödeme yapılması da mümkündür.


3

mailto:[email protected]

Bu modelde üye işyeri ürünün fiyat ve kategori bilgilerini 3pay|Mikro Ödeme tarafından sunulan web servise iletir. 3pay|Mikro Ödeme web servisi, üye işyeri web sitesinden iletilen bilgileri kullanarak her işlem için ayrı bir link üreterek üye işyerine response olarak bu linki döner. Üye işyeri web sitesi ise müşteriyi bu linke yönlendirir. Müşteri bu linkteki 3pay|Mikro Ödeme ortak ödeme sayfasında telefon veya kredi kartı numarasını girerek işlemini yapar ve web sitesine geri yönlendirilir.

Kurgunun entegrasyonu için, bkz. Error: Reference source not found.

Pro API kullanıldığında gerçekleşen akış için aşağıdaki simgeye çift tıklayınız:

1.2.3 API PlusAPI Plus, web servis tabanlı çalışan, satışların genellikle bir web sitesi üzerinden yapıldığı (bazı durumlarda satış SMS ile de başlatılabilir), ödeme işleminde 3pay|Mikro Ödeme ortak ödeme sayfasını kullanmayan, müşterinin süreç boyunca üye işyerinin web sitesinden ayrılmadığı, çok sayıda ve değişken fiyatlı ürünleri/hizmetleri bulunan şirketler için uygundur.

Bu modelde üye işyeri, kendi sitesinde müşterinin telefon numarasını alır. 3pay|Mikro Ödeme web servisine telefon numarası, fiyat ve kategori verileri iletilerek işlem başlatılır. İşlem asenkron gerçekleşir, bu sebeple işlem sonucu ayrı bir web servis metoduyla sorgulanır.

Kurgunun entegrasyonu için, bkz. API Plus Entegrasyonu.

API Plus kullanıldığında gerçekleşen akış için aşağıdaki simgeye çift tıklayınız:

1.2.4 SMS-Keyword KurgusuBu kurguda satış bir web sitesi üzerinden yapılmaz. Üye işyeri tarafından 3pay|Mikro Ödeme sisteminde bir ürün oluşturulur ve ürünle ilişkilendirilmiş bir keyword tanımlanır. Üye işyeri bu keywordü muhtelif bilgilendirme kanallarıyla müşteriye iletir (web sitesi, gazete ilanı, broşür, vs). Müşterinin bu keywordü SMS ile 7979’a göndermesiyle işlem başlar ve satış gerçekleşir.

Bu kurguda gerçekleşen işlemlerin üye işyerine iletilmesi için üye işyeri tarafından başlığında açıklanan şekilde bir web servis geliştirmesi gereklidir. İşlem sonuçları 3pay|Mikro Ödeme tarafından bu web servise iletilecektir.

Kurgunun entegrasyonu için, bkz. .

SMS-Keyword kurgusunda gerçekleşen akış için aşağıdaki simgeye çift tıklayınız:


4

1.2.5 SMS-Keyword Kurgusu (Pinli)Pinler, bir ürün veya hizmetin müşteri tarafından alınmasını sağlayacak tek kullanımlık şifrelerdir. 1.2.4’te anlatılan SMS-Keyword modelindeki akışın sonunda müşteriye 7979’dan bir pin gönderilir. Pinler ürün ile ilişkili olup üye işyeri tarafından düzenli olarak [email protected] adresine gönderilmelidir. Her pin tek kullanımlık olduğu için unique olmasına dikkat edilmelidir. Ayrıca bir işlemde kullanılan bir pin başka bir işlemde tekrar kullanılamaz.

Kurgunun entegrasyonu için, bkz. .

Pinli SMS-Keyword kurgusundaki akış için aşağıdaki simgeye çift tıklayınız:

1.2.6 SMS-Keyword YönlendirmeBu kurguda üye işyeri tarafından ürün oluşturulmamaktadır. Müşteri, üye işyerinin belirleyeceği bir keyword ile bu keywordün sonuna eklenecek bir ibareyi SMS ile 7979’a göndererek işlemi başlatır.

Örnek SMS: “SATINAL 150”

Bu örnekte “SATINAL” kısmı keyword prefixidir. Ardından gelen “150” kısmı ise üye işyerinin sistemi tarafından yorumlanarak nasıl bir satın alma işlemi gerçekleşeceğinin belirlenmesini sağlar (örneğin müşterinin 150 puan satın alması gibi).

Bu kurgunun sistemsel akışında farklılık bulunmaktadır. Öncelikle üye işyeri tarafından başlığında açıklanan şekilde bir web servis geliştirmelidir. Müşterinin 7979’a gönderdiği mesaj 3pay|Mikro Ödeme tarafından SMS İçeriği İletim Servisi doğrudan üye işyerine iletilir. Üye işyeri sistemi bu mesajın içeriğini yorumlayarak müşteriden alınacak tutarı belirler. Ardından API Plus Entegrasyonu başlığında açıklanan web servisi kullanarak ödeme işleminin yapılmasını sağlar.

Kurgunun entegrasyonu için, bkz. SMS-Keyword Yönlendirme Entegrasyonu.

SMS-Keyword Yönlendirme kurgusundaki akış için aşağıdaki simgeye çift tıklayınız:

1.2.7 AboneliklerYukarıdaki kurguların tümünde ödemeler tek çekimlik, haftalık abonelik ve aylık abonelik olmak üzere 3 ödeme tipinde tanımlanabilir.


5

Tek çekimli işlemlerde sadece bir kereliğine müşteriden tutar düşülür. Yeni bir ödeme için ayrı bir işlem başlatılmalıdır.

Haftalık ve aylık abonelikli işlemlerde tutar her hafta ya da her ay müşteriden düşülür. Aboneliğin başlayabilmesi için başlangıç ödemesinin başarılı sonuçlanması gereklidir, aksi takdirde abonelik iptal olur. Başlangıç ödemesi başarısız olursa abonelik iptal olur. Müteakip ödeme dönemlerinde ise başarısız bir ödeme gerçekleşirse o ödeme dönemi atlanır ve bir sonraki ödeme dönemi beklenir, abonelik iptal olmaz.

Abonelik içeren satışlarla ilgili işlemler bölümünde bulunmaktadır.

Abonelik içeren işlemlerde gerçekleşen akış için aşağıdaki simgeye çift tıklayınız:


6

2 Basic API Entegrasyonu1) www.3pay.com adresinden üye işyeri kullanıcı adı ve şifresiyle giriş yapılır.2) Bilgiler bölümündeki Ürünler linkine tıklanır.3) Soldaki Yeni Ekle linkine tıklanır.4) Ürüne ilişkin bilgiler doldurularak Ekle butonuna tıklanır.5) Oluşturulan ürüne 3pay|Mikro Ödeme tarafından onay verilmesi sağlanır ([email protected]

adresine talep iletilerek).6) Panelde Ürünler linkine tıklanır, ilgili ürünün ürün detayı ikonuna tıklanır.7) Açılan sayfada Web Satış Kanalı kutusundaki Satış Adresi linki üye iş yerinin web sitesinde

satış için kullanılır.a. Örnek satış adresi şu şekildedir:

http://www.mikro-odeme.com/sale-api/tr/step1.aspx?partner=X&product=X

b. Üye işyeri tarafından tercihe bağlı olarak her işlem için unique bir ID eklenebilir. Bunun için adresin sonuna mpay parametresi ile değer eklenmelidir:

http://www.mikro-odeme.com/sale-api/tr/step1.aspx?partner=X&product=X&mpay=123456789

Bu mpay değeri ile sorgulama yapmanız veya kendi işlem numaranız ile tahsilat numarasını eşleştirmeniz mümkün olacaktır.

8) Müşteri ödemeyi başarıyla tamamladıktan sonra aşağıdaki tabloda Başarılı URL ile açıklanan adrese geri yönlendirilir. Bu URL’de aşağıdaki parametreler 3pay|Mikro Ödeme tarafından adrese eklenir:

pid İşlem numarası(Eski Format)mpy Üye işyeri tarafından tanımlanan ve işlem sırasında gönderilen, işlem takibi

için kullanılabilecek değer. (parametre “mpay” değildir!)sid Abonelik numarası (Abonelik dışındaki işlemlerde bu değer boş döner) (eski

format)order Sipariş numarası(Yeni Format)subscriber Abonelik numarası(Yeni Format)

Örnek sonuç URL’i şu şekildedir: .../basarili.asp?mpy=123456789&pid=XXX&sid=XXX&order=f6e54685-a373-4405-9d4b-2540aebd9e2c&subscriber=d9aa23cb-1832-490a-92ca-2acddc86837f

Ürün bilgileri doldurulurken gereken alanların açıklaması aşağıdaki gibidir:

SMS Şirket Adı Müşteri tarafından görülecek firma adıdır. Not: Ortak ödeme sayfasında ve onay SMS’inde bu ad görüneceği için dikkatle seçilmesi gereklidir.

Ürün Adı Müşteri tarafından görünecek ürün adıdır. (Örnek: Wordpress Teması Satışı, Deneme.com 1 Aylık Abonelik) Not: Ortak ödeme sayfasında bu ad görüneceği için dikkatle seçilmesi gereklidir.


7


http://www.3pay.com/

Ürün Kategorisi 3pay|Mikro Ödeme ile satılan hizmetler/ürünler kategorilere ayrılmıştır. Her bir kategorinin komisyon oranının farklı olmasından dolayı, doğru kategorinin seçilmesi önemlidir. Hatalı kategori seçilerek işlem yapılması durumunda sözleşme gereği cezalar uygulanmaktadır. Güncel oranlar için web sitemizi ziyaret edebilirsiniz.

Satış Türü Satış türü Tekil Ürün Satışı ve Abonelik olarak ikiye ayrılmıştır. Tekil Ürün Satışı seçildiğinde sistem belirlenen ücreti sadece 1 defa çekmektedir. Abonelik seçildiğinde ise aylık veya haftalık olarak aynı tutar düzenli bir şekilde, tekrar bir onay istenmeden tahsil edilmektedir.

Açıklama Ürünün içeriğini anlatan bilgilendirmedir. Müşteri memnuniyeti için bunun çok önemli olduğunu hatırlatırız.

Ürün Fiyatı 3pay|Mikro Ödeme ile satışını yapacağınız ürünün/hizmetin fiyatıdır. İlk olarak Lira kısmı daha sonra kuruş kısmı yazılır.

Müşteri Hizmetleri E-Posta

Müşteriler için destek verilecek ödeme ve siparişlerle ilgilenen birimin mail adresidir.

Web Adresi Ürünü yayınlayacağınız web sitesinin adresidir. Ürünü ekledikten sonra 3pay|Mikro Ödeme tarafından web sitesi kontrol edilecektir.

Başarılı URL Ödeme başarıyla tamamlandığında müşterinin yönlendirileceği internet adresidir. (Örnek: http://www.deneme.com/odemebasarili.aspx)

Başarısız URL Ödeme başarısız olduğunda müşterinin yönlendirileceği internet adresidir. (Örnek: http://www.deneme.com/basarisiz.aspx)


8

3 Pro API Entegrasyonu1) 3pay|Mikro Ödeme sisteminde Pro API ile işlem yapılabilmesi için [email protected]

adresine yetki talebi iletilir.2) Üye işyeri tarafından geliştirilen web sitesi projesine aşağıdaki link web referansı olarak

eklenir:http://vas.mikro-odeme.com/services/msaleservice.asmx

3) Bu web servisindeki SaleWithTicket metoduna aşağıdaki değerler iletilir:

Token (Servislerin kullanımı için gereken üye iş yeri bilgileri. Bu bilgiler MO tarafından üye iş yerine bildirilir):

<token><UserCode>string</UserCode>- MO tarafından atanan üye iş yeri numarası<Pin>string</Pin>- MO tarafından atanan pin

</token>

Input (Üye iş yeri tarafından gönderilen ödeme bilgileri):

<input><MPAY>string</MPAY>- Üye iş yeri tarafından tanımlanan bir değer. Kullanımı isteğe

bağlıdır. İşlemlerin üye işyeri sisteminde temsil edildiği ID ya da kullanıcı adı gibi değerler kullanılabilir.

<Content>string</Content>- Sipariş içeriği/tanımı<SendOrderResult>bool</SendOrderResult>- ile işlem sonuç bilgisi gönderim isteği:- ‘True’ bilgi gönderilsin- ‘False’ bilgi gönderilmesin<PaymentTypeId>int</PaymentTypeId>- Ödeme yöntemi:- ‘1’ Tek çekim- ‘2’ Aylık abonelik (iletilen miktar her ay otomatik çekilir)- ‘3’ Haftalık abonelik (iletilen miktar her hafta otomatik çekilir)- ‘4’ 2 haftalık abonelik- ‘5’ 3 aylık abonelik- ‘6’ 6 aylık abonelik- ‘7’ aylık denemeli (ilk ay ücretlendirme yapılmaz)- ‘8’ haftalık denemeli (ilk hafta ücretlendirme yapılmaz)- ‘9’ 2 haftalık denemeli (ilk 2 hafta ücretlendirme yapılmaz)- ‘10’ 3 aylık denemeli- ‘11’ 6 aylık denemeli- ‘13’ 30 günlük<ReceivedSMSObjectId>Guid</ReceivedSMSObjectId>- Daima ‘00000000-0000-0000-0000-000000000000’ olarak

gönderilmelidir. <ProductList>


9


- Bu listede sadece tek bir adet MSaleProduct elemanı bulunmalıdır.<MSaleProduct>

<ProductId>int</ProductId>- Daima ‘0’ olarak iletilmelidir.<ProductCategory>int</ProductCategory>- Sipariş ile ilgili ürünün/hizmetin kategorisi:- ‘1’ Fiziksel Ürün- ‘2’ Oyun- ‘3’ Dijital İçerik- ‘4’ Servis- ‘5’ Sosyal Ağ/Arkadaşlık- ‘6’ Aidat/Otomat- ‘7’ Bahis- ‘8’ Sigorta- ‘10’ Kamu - bilet - fastfood- ‘11’ Cep Sigorta- ‘12’ Kutu Oyun- ‘14’ Mobil Uygulama / Mobil Market- ‘15’ Eğitim- ‘16’ Bağış (sadece Turkcell aboneleri bağış ödemesi

yapabilir)- ‘19’ Sağlık- ‘20’ White Label Adult<ProductDescription>string</ProductDescription>- Ürünün açıklaması<Price>double</Price>- Ödenecek tutar.<Unit>int</Unit>- Daima 1 gönderilmelidir.

</MSaleProduct></ProductList><SendNotificationSMS>bool</SendNotificationSMS>- Ödeme sonucunda kullanıcıya gönderilecek bilgi SMS’i isteği:- ‘True’ bilgi SMS’i gönderilsin- ‘False’ bilgi SMS’i gönderilmesin<OnSuccessfulSMS>string</OnSuccessfulSMS>- SendNotificationSMS parametresi ‘True’ verilmişse, ödemenin

başarılı olması durumunda kullanıcıya gönderilecek bilgi SMS’i içeriğini belirtir.(Türkçe karakter kullanılmamalıdır)<OnErrorSMS>string</OnErrorSMS>- SendNotificationSMS parametresi ‘True’ verilmişse, ödemenin

başarısız olması durumunda kullanıcıya gönderilecek bilgi SMS’i içeriğini belirtir.(Türkçe karakter kullanılmamalıdır)<RequestGsmOperator>int</RequestGsmOperator>- Mobil ve kredi kartı ödemelerinde 0 olarak gönderilmelidir.- TTNET Ödeme ile yapılacak ödemelerde 20 gönderilmelidir.<RequestGsmType>int</RequestGsmType>- Daima 0 olarak gönderilmelidir.<Url>string</Url>- İşlemin gerçekleştiği sitenin adresini belirtir.<SuccessfulPageUrl>string</SuccessfulPageUrl>


10

- İşlem başarıyla sonuçlanırsa müşterinin geri yönlendirileceği sayfayı belirtir.

<ErrorPageUrl>string</ErrorPageUrl>- İşlem başarısız sonuçlanırsa müşterinin geri yönlendirileceği

sayfayı belirtir.<Country>string</Country>- Türkiye’den yapılacak mobil ödeme işlemlerinde boş bırakılır.- Yurtdışı mobil ödeme işlemlerinde işlemin gerçekleştirileceği

ülkenin kodunu belirtir. Ülke kodları ‘ISO 3166-1-alpha-2’ standardındadır ve şu adreste bulunabilir:

http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm

<Currency>string</Currency>- Türkiye’den yapılacak mobil ödeme işlemlerinde boş bırakılır.- Yurtdışı mobil ödeme işlemlerinde işlemin gerçekleştirileceği

ülkenin para birimini belirtir. Ülke para birim kodları ‘ISO 4217’ standardındadır ve şu adreste bulunabilir:

http://www.currency-iso.org/dl_iso_table_a1.xls<Extra>string</Extra>- Mobil ödemelerde boş gönderilmelidir.- Kredi kartı ödemeleri için ‘3pay=true&cconly=true’ değeri

gönderilmelidir.<TurkcellServiceId>string</TurkcellServiceId>- Entegrasyon çalışması süresince, operatör onayı gelene kadar 0

gönderilir.- Entegrasyon tamamlanıp operatörlerden onay alındıktan sonra üye işyerine 3pay|Mikro Ödeme tarafından bildirilen, tüm mobil işlemlerde kullanılması gereken bir değerdir.

</input>

4) SaleWithTicket metoduna yukarıdaki XML iletildiğinde, web servis tarafından aşağıdaki gibi bir response dönülür. Aşağıdaki RedirectUrl değeri, müşterinin ödeme yapacağı sayfanın adresini belirtir. Satış yapılacak sitede müşteri bu adrese yönlendirilir.

<SaleWithTicketResult><RedirectUrl>string</RedirectUrl>- Müşterinin yönlendirileceği 3pay|Mikro Ödeme ortak ödeme sayfasının

adresidir.<StatusCode>int</StatusCode>- ‘0’ değeri Pro API satış linki oluşturma bilgisinin alındığını

belirtir. İşlem başlatılmış demektir.- ‘1’ değeri Pro API satış linki oluşturma bilgisinin alınmadığını

belirtir. İşlem başlatılamamış demektir.<ErrorCode>string</ErrorCode>- Pro API satış linki oluşturma bilgisi iletimi hata kodu.<ErrorMessage>string</ErrorMessage>- Pro API satış linki oluşturma bilgisi iletimi hata açıklaması.

</SaleWithTicketResult>


11

http://www.currency-iso.org/dl_iso_table_a1.xls



5) Müşteri, ödeme tamamlandıktan sonra 3pay|Mikro Ödeme ortak ödeme sayfasından SuccessfulPageUrl sayfasına yönlendirilmişse ödeme başarıyla sonuçlanmış demektir. ErrorPageUrl sayfasına yönlendirilmişse ödeme başarısızlıkla sonuçlanmış demektir.

6) Ödeme sonucunun üye işyeri sistemine aktarılması için İşlem Sonuç Servisi bölümündeki yöntemlerden biri kullanılmalıdır.


12

4 API Plus Entegrasyonu1) 3pay|Mikro Ödeme sisteminde API Plus ile işlem yapılabilmesi için [email protected]

adresine yetki talebi iletilir.2) Üye işyeri tarafından geliştirilen web sitesi projesine aşağıdaki link web referansı olarak

eklenir:http://vas.mikro-odeme.com/services/msaleservice.asmx

3) Bu web servisindeki SaleWithConfirm metoduna aşağıdaki XML iletilir:

Token (Servislerin kullanımı için gereken üye iş yeri bilgileri. Bu bilgiler MO tarafından üye iş yerine bildirilir.)

<token><UserCode>string</UserCode>- MO tarafından atanan üye iş yeri numarası<Pin>string</Pin>- MO tarafından atanan pin

</token>

Input (Üye iş yeri tarafından gönderilen ödeme bilgileri)

<input><MPAY>string</MPAY>- Üye iş yeri tarafından tanımlanan bir değer. Kullanımı isteğe

bağlıdır. İşlemlerin üye işyeri sisteminde temsil edildiği ID ya da kullanıcı adı gibi değerler kullanılabilir.

<Gsm>string</Gsm>- Müşterinin telefon numarasını belirtir, 5XXXXXXXXX formatında

olmalıdır<Content>string</Content>- Sipariş tanımı<SendOrderResult>bool</SendOrderResult>- ile işlem sonuç bilgisi gönderim isteği:- ‘True’ bilgi gönderilsin- ‘False’ bilgi gönderilmesin<PaymentTypeId>int</PaymentTypeId>- Ödeme yöntemi:- ‘1’ Tek çekim- ‘2’ Aylık abonelik (iletilen miktar her ay otomatik çekilir)- ‘3’ Haftalık abonelik (iletilen miktar her hafta otomatik çekilir)- ‘4’ 2 haftalık abonelik- ‘5’ 3 aylık abonelik- ‘6’ 6 aylık abonelik- ‘7’ aylık denemeli (ilk ay ücretlendirme yapılmaz)- ‘8’ haftalık denemeli (ilk hafta ücretlendirme yapılmaz)- ‘9’ 2 haftalık denemeli (ilk 2 hafta ücretlendirme yapılmaz)- ‘10’ 3 aylık denemeli- ‘11’ 6 aylık denemeli- ‘13’ 30 günlük<Url>string</Url>


13


- Ödemenin yapıldığı web sitesi.<ProductList>- Bu listede sadece tek bir adet MSaleProduct elemanı bulunmalıdır.

<MSaleProduct><ProductId>int</ProductId>- Daima ‘0’ olarak iletilmelidir.<ProductCategory>int</ProductCategory>- Sipariş ile ilgili ürünün/servisin kategorisi:- ‘1’ Fiziksel Ürün- ‘2’ Oyun- ‘3’ Dijital İçerik- ‘4’ Servis- ‘5’ Sosyal Ağ/Arkadaşlık- ‘6’ Aidat/Otomat- ‘7’ Bahis- ‘8’ Sigorta- ‘10’ Kamu - bilet - fastfood- ‘11’ Cep Sigorta- ‘12’ Kutu Oyun- ‘14’ Mobil Uygulama / Mobil Market- ‘15’ Eğitim- ‘16’ Bağış (sadece Turkcell aboneleri bağış ödemesi

yapabilir)- ‘19’ Sağlık- ‘20’ White Label Adult<ProductDescription>string</ProductDescription>- Ürünün açıklaması<Price>double</Price>- Ödenecek bedeli belirtir.<Unit>int</Unit>- Daima 1 verilmelidir.

</MSaleProduct></ProductList><ReceivedSMSObjectId>Guid</ReceivedSMSObjectId>- Daima ‘00000000-0000-0000-0000-000000000000’ olarak gönderilir.<SendNotificationSMS>bool</SendNotificationSMS>- Ödeme sonucunda kullanıcıya gönderilecek bilgi SMS’i isteği:- ‘True’ bilgi SMS’i gönderilsin- ‘False’ bilgi SMS’i gönderilmesin<OnSuccessfulSMS>string</OnSuccessfulSMS>- SendNotificationSMS parametresi ‘True’ verilmişse, ödemenin

başarılı olması durumunda kullanıcıya gönderilecek bilgi SMS’i içeriğini belirtir.(Türkçe karakter kullanılmamalıdır)<OnErrorSMS>string</OnErrorSMS>- SendNotificationSMS parametresi ‘True’ verilmişse, ödemenin

başarısız olması durumunda kullanıcıya gönderilecek bilgi SMS’i içeriğini belirtir.(Türkçe karakter kullanılmamalıdır)<RequestGsmOperator>int</RequestGsmOperator>- Daima ‘0’ olarak gönderilmelidir. <RequestGsmType>int</RequestGsmType>- Daima ‘0’ olarak gönderilmelidir.<TurkcellServiceId>string</TurkcellServiceId>


14

- Entegrasyon çalışması süresince, operatör onayı gelene kadar 0 gönderilir.

- Entegrasyon tamamlanıp operatörlerden onay alındıktan sonra üye işyerine 3pay|Mikro Ödeme tarafından bildirilen, tüm işlemlerde kullanılması gereken bir değerdir.<CustomerIpAddress>string</CustomerIpAddress>

- Müşterinin IP adresi. Bu alan her işlemde dolu olarak iletilmelidir.</input>

4) SaleWithConfirm metoduna yukarıdaki XML iletildiğinde, web servis tarafından aşağıdaki gibi bir response dönülür. SaleWithConfirm metodu asenkron çalışmaktadır, işlemin sonucunun başarılı olup olmadığını öğrenmek için İşlem Sonuç Servisi başlığına bakınız.

<SaleWithConfirmResult><OrderObjectId>Guid</OrderObjectId>- Sipariş idsini belirtir. İşlemin sonucunu sorgulamak için

kullanılır.<Gsm>string</Gsm>- Ödemenin yapıldığı telefon numarasını belirtir(5XXXXXXXXX

formatında)<GsmOperator>int</GsmOperator>- Bu değer daima 0’dır. İşlem yapılan operatörü öğrenmek için bir

sonraki maddeye bakınız.<GsmType>int</GsmType>- Bu değer daima 0’dır. Hattın faturalı mı kontörlü mü olduğunu

öğrenmek için bir sonraki maddeye bakınız.<State>int</State>- İşlem durumunu belirtir. Bu değer nihai değildir. İşlem sonucunu

öğrenmek için bir sonraki maddeye bakınız.- 100’den küçük değerler ödemenin devam ettiğini belirtir.- 100 ödemenin başarıyla sonuçlandığını belirtir.- 100’den büyük değerler ödemenin başarısız olduğunu belirtir.<OrderChannelId>int</OrderChannelId>- Bu değer daima ‘104’ olarak dönecektir.<PaymentCategoryId>int</PaymentCategoryId>- Sipariş ile ilgili ürünün/servisin kategorisi:- ‘1’ Fiziksel Ürün- ‘2’ Oyun- ‘3’ Dijital İçerik- ‘4’ Servis- ‘5’ Sosyal Ağ/Arkadaşlık- ‘6’ Aidat/Otomat- ‘7’ Bahis- ‘8’ Sigorta- ‘10’ Kamu - bilet - fastfood- ‘11’ Cep Sigorta- ‘12’ Kutu Oyun- ‘14’ Mobil Uygulama / Mobil Market- ‘15’ Eğitim


15

- ‘16’ Bağış (sadece Turkcell aboneleri bağış ödemesi yapabilir)- ‘19’ Sağlık- ‘20’ White Label Adult<LastTransactionDate>DateTime</LastTransactionDate>- Ödeme tarihini belirtir.<MPAY>string</MPAY>- Üye iş yeri tanımlı değer. <SubscriberId>Guid</SubscriberId>- Bu değer boş dönecektir. Yapılan işlem bir abonelik işlemi ise bir

sonraki maddede anlatılan yöntemle abonelik idsi öğrenilebilir.<PIN>string</PIN>- Bu değer boş dönecektir. Yapılan işlem pinli kurgu ise kullanıcıya gönderilen PIN değerini öğrenmek için bir sonraki maddedeki yöntem kullanılır.<MicroPaymentResults>- İşlem sonuçlanmadığı için bu parametreler boş dönecektir. İşlem

sonucunu öğrenmek için bir sonraki maddeye bakınız.<MMicroPaymentOutput>

<PaymentObjectId>Guid</PaymentObjectId><StatusCode>int</StatusCode><ErrorCode>string</ErrorCode><ErrorMessage>string</ErrorMessage>

</MMicroPaymentOutput></MicroPaymentResults><StatusCode>int</StatusCode>- Sipariş durum kodunu belirtir. ‘0’ dönerse siparişin başarılı bir

şekilde başladığını belirtir. Ödemenin başarılı sonuçlandığı anlamına gelmez.

<ErrorCode>string</ErrorCode>- Sipariş hata kodunu belirtir. Operatör tarafından gönderilir.

Siparişe ait ödemenin hata kodudur.<ErrorMessage>string</ErrorMessage>- Sipariş hata açıklamasını belirtir. İlgili hata koduna ait

açıklama.</SaleWithConfirmResult>


16

5 SMS-Keyword Entegrasyonu1) www.mikro-odeme.com adresinden üye işyeri kullanıcı adı ve şifresiyle giriş yapılır.2) Bilgiler bölümündeki Ürünler linkine tıklanır.3) Soldaki Yeni Ekle linkine tıklanır.4) Ürüne ilişkin bilgiler doldurularak Ekle butonuna tıklanır.5) Oluşturulan ürüne 3pay|Mikro Ödeme tarafından onay verilmesi sağlanır (onay talebi

[email protected] adresine iletilebilir).6) 3pay|Mikro Ödeme entegrasyon yetkilisiyle birlikte keyword belirlenir

([email protected]), entegrasyon yetkilisi bu keywordü ürünle ilişkilendirir.7) İşlem sonucunu öğrenmek için kullanılır.


17



6 SMS-Keyword Entegrasyonu (Pinli)1) www.mikro-odeme.com adresinden üye işyeri kullanıcı adı ve şifresiyle giriş yapılır.2) Bilgiler bölümündeki Ürünler linkine tıklanır.3) Soldaki Yeni Ekle linkine tıklanır.4) Ürüne ilişkin bilgiler doldurularak Ekle butonuna tıklanır.5) Oluşturulan ürüne 3pay|Mikro Ödeme tarafından onay verilmesi sağlanır (onay talebi

[email protected] adresine iletilebilir).6) 3pay|Mikro Ödeme entegrasyon yetkilisiyle birlikte keyword belirlenir, entegrasyon yetkilisi

bu keywordü ürünle ilişkilendirir.7) Müşteriye gönderilecek pin listesi, [email protected] adresine ürün ismi belirtilerek

gönderilir.8) İşlem sonucunu öğrenmek için kullanılır.


18


7 SMS-Keyword Yönlendirme Entegrasyonu1) Üye işyeri tarafından 3pay|Mikro Ödeme yetkilileri ile birlikte bir keyword prefix belirlenir.2) başlığında açıklanan şekilde bir web servis geliştirilir. Müşterilerin ilgili keyword prefix ile

7979’a göndereceği mesaj metni 3pay|Mikro Ödeme tarafından bu web servise yönlendirilecektir.

3) Seçilen keyword’ün tanımlanması için [email protected] adresine bilgi iletilir.4) İletilen SMS metinleri üye işyerinin sistemi tarafından yorumlanır, müşteriden çekilecek tutar

tespit edilir.5) API Plus Entegrasyonu başlığında açıklanan şekilde müşteriden çekilecek tutar web servise

iletilir.6) İşlemin sonucu İşlem Sonuç Servisi bölümündeki yöntemlerden biriyle öğrenilebilir.


19


8 Abonelik ServisiAbonelik işlemleri yapmak için http://vas.mikro-odeme.com/services/MSubscriberManagementService.asmx adresindeki web servisin metotları kullanılabilir. Bu metotlar ve işlevleri:

SelectSubscriber : abonelik listeleme SelectSubscriberDetail : abonelik detayı görüntüleme DeactivateSubscriber : aboneliği pasife çekme

8.1 Abonelik ListelemeSelectSubscriber metodu vasıtası ile üye iş yerine ait abonelikler listelenebilir. Metoda ait parametreler vasıtası ile filtreleme yapılabilir. Bir parametrenin değeri boş gönderilirse o parametre kriteri göz ardı edilecektir.

Parametreler:

1) Input

<SelectSubscriber xmlns="http://services.mikro-odeme.com/"> <token>

<UserCode>string</UserCode>- MO tarafından atanan üye iş yeri numarası<Pin>string</Pin>- MO tarafından atanan API anahtarı

</token><input>

<ProductId>int</ProductId>- Aboneliğin hangi ürün üzerinden yapıldığını belirtir. ‘0’

değeri belirli bir üzerinden abonelik yapılmadığını gösterir.<GSM>string</GSM>- Aboneliğin hangi GSM numarasını tarafından yapıldığını

belirtir(5XXXXXXXXX formatında olmalı).<OrderChannelId>int</OrderChannelId>Aboneliğin yapıldığı satış kanalını belirtir- ‘100’ Pro API- ‘101’ Basic API- ‘102’ SMS- ‘103’ Direct API- ‘104’ API Plus<Active>int</Active>- Aboneliğin aktif/pasif bilgisini belirtir- ‘1’ Aktif- ‘0’ Pasif- ‘-1’ Hepsi<SubscriberType>int</SubscriberType>- Abonelik türünü belirtir- ‘2’ Aylık Abonelik- ‘3’ Haftalık Abonelik<StartDateMin>DateTime</StartDateMin>


20

- Abonelik başlangıç tarihini belirtir(alt sınır) <StartDateMax>DateTime</StartDateMax>- Abonelik başlangıç tarihini belirtir(üst sınır)

<LastSuccessfulPaymentDateMin>DateTime</LastSuccessfulPaymentDateMin>- Aboneliğe ait son başarılı ödeme tarihini belirtir(alt sınır)

<LastSuccessfulPaymentDateMax>DateTime</LastSuccessfulPaymentDateMax>- Aboneliğe ait son başarılı ödeme tarihini belirtir(üst sınır)

</input></SelectSubscriber>

2) Output

<SelectSubscriberResponse xmlns="http://services.mikro-odeme.com/"><SelectSubscriberResult>

<StatusCode>int</StatusCode>- Sonuç kodu.<ErrorCode>string</ErrorCode>- Hata kodunu belirtir.<ErrorMessage>string</ErrorMessage>- Hata kodu açıklamasını belirtir.<Subscribers>- İlgili kriterlere göre dönen abonelik kayıtları:

<Subscriber><SubscriberId>Guid</SubscriberId>- Abonelik idsi<GSM>string</GSM>- Aboneliğin yapıldığı GSM numarası<StartDate>DateTime</StartDate>- Aboneliğin başlangıç tarihi<SubscriberTypeId>int</SubscriberTypeId>- Abonelik türü<PaymentCategoryId>int</PaymentCategoryId>- Abonelik kategorisi- ‘1’ Fiziksel Ürün- ‘2’ Oyun- ‘3’ Dijital İçerik- ‘4’ Servis- ‘5’ Sosyal Ağ/Arkadaşlık- ‘6’ Aidat/Otomat- ‘7’ Bahis- ‘8’ Sigorta- ‘10’ Kamu - bilet - fastfood- ‘11’ Cep Sigorta- ‘12’ Kutu Oyun- ‘14’ Mobil Uygulama / Mobil Market- ‘15’ Eğitim- ‘16’ Bağış- ‘19’ Sağlık- ‘20’ White Label Adult<BasePrice>double</BasePrice>


21

- Abonelik bedeli<BaseUnitPrice>double</BaseUnitPrice>- Kredi miktarını belirtir.<ProductId>int</ProductId>- Aboneliğin ait olduğu ürün idsi<ProductName>string</ProductName>- Aboneliğin ait olduğu ürün adı<OrderChannelId>int</OrderChannelId>- Aboneliğin yapıldığı satış kanalı<Active>bool</Active>- Aboneliğin aktiflik durumu- ‘True’: Aktif- ‘False’: Pasif<LastSuccessfulPaymentDate>DateTime

</LastSuccessfulPaymentDate>- Aboneliğe ait son başarılı ödeme tarihi<GsmOperator>int</GsmOperator>- Aboneliğin yapıldığı numaranın ait olduğu

operatör- 1: Turkcell- 3: Avea- 7: Vodafone

</Subscriber></Subscribers>

</SelectSubscriberResult></SelectSubscriberResponse>

8.2 Abonelik Detayı GörüntülemeSelectSubscriberDetail metodu kullanılarak bir aboneliğin detayını getirir. Kullanılması için abonelik ID’sinin biliniyor olması gereklidir, bu ID 8.1’de anlatılan SelectSubscriber metoduyla alınabilir.

Parametreler:

1) Input

<SelectSubscriberDetail xmlns="http://services.mikro-odeme.com/"><token>


</token><subscriberId>Guid</subscriberId>- Abonelik idsi

</SelectSubscriberDetail>

2) Output

<SelectSubscriberDetailResponse xmlns="http://services.mikro-odeme.com/"><SelectSubscriberDetailResult>

<StatusCode>int</StatusCode>- Sonuç kodu.


22

<ErrorCode>string</ErrorCode>- Hata kodunu belirtir.<ErrorMessage>string</ErrorMessage>- Hata kodu açıklamasını belirtir.<Subscriber>

<SubscriberId>Guid</SubscriberId>- Abonelik idsi<GSM>string</GSM>- Aboneliğin yapıldığı GSM numarası<StartDate>DateTime</StartDate>- Aboneliğin başlangıç tarihi<SubscriberTypeId>int</SubscriberTypeId>- Abonelik türü<PaymentCategoryId>int</PaymentCategoryId>- Abonelik kategorisi<BasePrice>double</BasePrice>- Abonelik bedeli<BaseUnitPrice>double</BaseUnitPrice>- Abonelik kontör bedeli<ProductId>int</ProductId>- Aboneliğin ait olduğu ürünün idsi<ProductName>string</ProductName>- Aboneliğin ait olduğu ürünün adı<OrderChannelId>int</OrderChannelId>- Aboneliğin yapıldığı satış kanalı

<LastSuccessfulPaymentDate>DateTime</LastSuccessfulPaymentDate>- Aboneliğe ait son başarılı ödeme tarihi<GsmOperator>int</GsmOperator>- Aboneliğin yapıldığı GSM numarasının ait olduğu

operatör- 1: Turkcell- 3: Avea- 7: Vodafone<Active>bool</Active>- Aboneliğin aktiflik durumu- ‘True’: Aktif- ‘False’: Pasif<Payments>- Aboneliğe ait ödeme kayıtları

<Payment><PaymentDate>DateTime</PaymentDate>- Ödeme tarihini belirtir<IsPaid>bool</IsPaid>- Ödemenin başarılı olup olmadığını belirtir- ‘True’ Başarılı- ‘False’ Başarısız<OrderObjectId>Guid</PaymentDate>- Ödemenin ait olduğu siparişin idsini

belirtir</Payment>

</Payments>Versiyon [email protected]

23

</Subscriber></SelectSubscriberDetailResult>

</SelectSubscriberDetailResponse>

8.3 Aboneliği İptal EtmeDeactivateSubscriber metodu vasıtası ile yapılan bu işlem ilgili aboneliği pasif duruma getirir. Aboneliğin ödeme tarihi geldiğinde tahsilat yapılmaz. Pasif duruma getirilen bir abonelik ileride tekrar aktif duruma çekilebilir.

Parametreler:

1) Input

<DeactivateSubscriber xmlns="http://services.mikro-odeme.com/"><token>


</token><subscriberId>Guid</subscriberId>- Abonelik idsi

</DeactivateSubscriber>

2) Output

<DeactivateSubscriberResponse xmlns="http://services.mikro-odeme.com/"><DeactivateSubscriberResult>

<StatusCode>int</StatusCode>- Sonuç kodu. ‘0’ döndüğünde aboneliğin başarılı bir şekilde

pasife çekildiğini belirtir. <ErrorCode>string</ErrorCode>- Abonelik pasife çekilememişse hata kodunu belirtir.<ErrorMessage>string</ErrorMessage>- Hata kodu açıklamasını belirtir.

</DeactivateSubscriberResult></DeactivateSubscriberResponse>


24

9 Bilgi SMS’i Gönderim Servisi1) Bilgi SMS’i Gönderim Servisi, müşteriye üye işyeri tarafından bir ödeme işemiyle ilgili

7979’dan ücretsiz bilgilendirme SMS’i gönderilmesini sağlar.2) Üye işyeri, bilgi gönderiminde 7979 numarasını kullanacaksa http://vas.mikro-

odeme.com/services/msendsmsservice.asmx adresindeki web servis, projeye referans olarak eklenir.

3) Üye işyeri, kendine ait kısa numarayı kullanacaksa http://vas.mikro-odeme.com/services/MCustomSendSMSService.asmx adresindeki web servis, projeye referans olarak eklenir.

4) Bilgi SMS’i gönderim yetkisi için [email protected] adresine yetki talebi iletilir.5) Gönderilecek bilgi mesajı, web servisin SendSMS metoduna iletilir. Bu metodun

parametreleri şöyledir:

<token><UserCode>string</UserCode><Pin>string</Pin>

</token><input>

<Gsm>string</Gsm>- SMS’in gönderileceği GSM numarasını belirtir(5XXXXXXXXX formatında)<Content>string</Content>- Gönderilecek SMS’in içeriğini belirtir.(Türkçe karakter

kullanılmamalı)<RequestGsmOperator>int</RequestGsmOperator>- Bu parametre daima ‘0’ olarak gönderilecektir.<RequestGsmType>int</RequestGsmType>- Bu parametre daima ‘0’ olarak gönderilecektir.

</input>

6) Metodun döneceği response ise şöyledir:

<SendSMSResult><SendSMSObjectId>Guid</SendSMSObjectId>- SMS’in idsini belirtir.<StatusCode>int</StatusCode>- SMS’in gönderim durumunu belirtir. ‘0’ olduğu durumlarda SMS başarı

ile gönderilmiştir.<ErrorCode>string</ErrorCode>- SMS gönderimi hata kodunu belirtir. Operatör tarafından gönderilir.<ErrorMessage>string</ErrorMessage>- SMS gönderimi hata açıklamasını belirtir. İlgili hata koduna ait

açıklama.</SendSMSResult>


25


10 SMS İçeriği İletim Servisi1) 3pay|Mikro Ödeme’ye gelen SMS’ler, 1.1.6’da anlatılan SMS-Keyword Yönlendirme

kurgusunu kullanan şirketler için üye işyerine iletilmektedir.2) Bu iletim, üye işyeri tarafından geliştirilecek bir web servis üzerinden yapılmaktadır. Söz

konusu web servis, ReceiveMOMessage adlı bir metoda sahip olmalıdır. Servisin formatı şu URL’deki yapıda olmalıdır:http://vas.mikro-odeme.com/proxy/CReceiveMOMessageService.asmx?op=ReceiveMOMessage

3) Web servisin adresi [email protected] adresine iletilerek MÖ sisteminde tanımlanması sağlanır.

4) ReceiveMOMessage metodu, aşağıdaki XML değerini alacak şekilde parametrelere sahip olmalıdır:

<input xmlns="http://cservices.mikro-odeme.com.tr/mapping/generated"><ReceivedSMSId>Guid</ReceivedSMSId>- Müşteriden 3pay|Mikro Ödeme’ye iletilen SMS’in Id’si<SenderGSM>string</SenderGSM>- Gönderen GSM numarası<ReceiverGSM>string</ReceiverGSM>- Alıcı GSM numarası<OriginalContent>string</OriginalContent>- SMS içeriği<FixedContent>string</FixedContent>- Güncellenmiş SMS içeriği. Asıl SMS içeriğinin Türkçe karakterbulundurmayan, büyük harfe çevrilmiş ve boşluklardan arındırılmışversiyonu.<DateReceived>DateTime</DateReceived>- SMS tarihi<GsmOperator>int</GsmOperator>- SMS’in gönderildiği GSM operatörü- ‘1’ Turkcell- ‘7’ Vodafone- ‘3’ AVEA<GsmType>int</GsmType>- SMS’in gönderildiği GSM türü- ‘0’ Bilinmiyor- ‘1’ PostPaid- ‘2’ PrePaid

</input>

5) 3pay|Mikro Ödeme tarafından ReceiveMOMessage metodu çağırılarak müşterinin 7979’a gönderdiği SMS içeriğine ilişkin veriler üye işyerinin web servisine gönderilecektir.

6) ReceiveMOMessage metodu, aşağıdaki gibi bir response değerini 3pay|Mikro Ödeme’ye dönmelidir:

<CReceiveMOMessageOutput xmlns="http://cservices.mikro-odeme.com.tr/mapping/generated">

<StatusCode>int</StatusCode>


26


http://vas.mikro-odeme.com/proxy/CReceiveMOMessageService.asmx?op=ReceiveMOMessage

http://vas.mikro-odeme.com/proxy/CReceiveMOMessageService.asmx?op=ReceiveMOMessage

- SMS bilgisi iletim durumunu belirtir- ‘0’ gönderilirse SMS bilgisinin alındığını belirtir- ‘1’ gönderilirse SMS bilgisinin alınmadığını belirtir<ErrorCode>string</ErrorCode>- SMS bilgisi iletiminde hata oluştuğu durumda(StatusCode=1)açıklayıcı bir değer gönderilir.- SMS bilgisi iletimi başarılı olduğunda boş gönderilir.<ErrorMessage>string</ErrorMessage>- SMS bilgisi iletiminin açıklama mesajı- SMS bilgisi iletimi başarılı ise ‘Message ReceivedSuccessfully.’ şeklinde gönderilir.- SMS bilgisi iletimi başarısız ise ilgili exception içeriğiveya açıklayıcı bir hata mesajı gönderilir.

</CReceiveMOMessageOutput>


27

11 İşlem Sonuç Servisiİşlem Sonuç Servisi, tüm kurgular için işlemlerin sonucunun 3pay|Mikro Ödeme tarafından üye işyerine iletilmesini sağlar. Bu servisin kullanımı için üç yöntem mevcuttur:

Birinci yöntem, üye işyerine ait bir email adresine işlem sonuçlarının email halinde gönderilmesidir.

İkinci yöntem, HTTP/GET ile işlem sonuçlarının iletileceği bir web sayfası hazırlanmasıdır. 3pay|Mikro Ödeme sistemi tarafından bu sayfa çağırılarak gerekli parametreler iletilir.

Üçüncü yöntem, üye işyeri tarafından bir web servis hazırlanmasıdır. 3pay|Mikro Ödeme sistemi bu web servisin ilgili metodunu çağırarak işlem sonuçlarını iletir.

Tüm yöntemlerde ilgili email adresi/sayfa adresi/web servis adresi [email protected] adresine bildirilmelidir. İşlem Sonuç Servisi’ne bağlanacak IP’lerin güvenlik önlemi amacıyla kısıtlanması istenirse, 3pay|Mikro Ödeme’nin bağlanacağı adresler aşağıdaki gibidir:

46.34.90.215 46.34.90.216 195.46.135.110

11.1 Email YöntemiÜye işyeri tarafından seçilecek olan bir email adresi 3pay|Mikro Ödeme yetkililerine iletilir. İşlem sonuçları bu adrese aşağıdaki formatta email olarak gönderilir:

Üye İşyeri : ÜYE_İŞYERİ_NO ÜYE_İŞYERİ_ADIGsm : 5XXXXXXXXX (Operatör Adı)İşlem Tarihi : GG.AA.YYYY SS:DD:SSFiyat : XX,XX TLDurum : İşlem Başarılı/İşlem BaşarısızSatış Kanalı : Satış Kanalı İsmiSatış Türü : Tekil Satış/Haftalık Abonelik/Aylık AbonelikSatılan Ürün : Ürün İsmiPin : (Pin gönderiliyorsa, gönderilen pin)Gelen SMS : Müşterinin Gönderdiği SMS İçeriğiHata Kodu : 1000Hata Mesajı : Islem Basarili

11.2 Web Sayfası Yöntemi1) Üye işyeri tarafından aşağıdaki parametreleri alacak bir web sayfası hazırlanır:

http://www.websitesi.com/servissayfasi.php?order=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&gsm=5XXXXXXXXX&status=0&state=100&date=14.03.2012+17%3a11%3a59&errorcode=1000


28


&errormsg=Islem+Basarili&price=2,49&sms=ONAY&category=2&saletype=1&subscriber=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&operator=1&gsmtype=1&productid=1&productdesc=Your+product+desc&mpay=XXXXX&channel=XXX

2) Bu http parametrelerinin anlamları:

Parametre Anlamıstate Ödemenin sonucunu belirtir.

100 başarılı işlem sonucunu belirtir.100’den büyük değerler işlemin başarısız olduğunu belirtir.

order İşlemin ID’sini belirtir.gsm İşlemin yapıldığı GSM numarasını belirtirstatus Sipariş durum kodunu belirtir. ‘0’ dönerse siparişin başarılı

bir şekilde oluşturulduğunu belirtir. Ödemenin başarılı olduğu anlamına gelmez.

date İşlem tarihini bulundurmaktadır.errorcode Sipariş hata kodunu belirtir. Operatör tarafından gönderilir.

Siparişe ait ödemenin hata kodudur.errormsg Sipariş hata açıklamasını belirtir. İlgili hata koduna ait

açıklama. Siparişe ait ödemenin hata açıklamasıdır.price İşlemin toplam tutarısms Gönderilen SMS’in içeriğini belirtircategory Sipariş ile ilgili ürünün/servisin kategorisisaletype Ödeme yöntemi:

- ‘1’ Tek çekim- ‘2’ Aylık abonelik (iletilen miktar her ay otomatik

çekilir)- ‘3’ Haftalık abonelik (iletilen miktar her hafta

otomatik çekilir)- ‘4’ 2 haftalık abonelik- ‘5’ 3 aylık abonelik- ‘6’ 6 aylık abonelik- ‘7’ aylık denemeli (ilk ay ücretlendirme yapılmaz)- ‘8’ haftalık denemeli (ilk hafta ücretlendirme

yapılmaz)- ‘9’ 2 haftalık denemeli (ilk 2 hafta ücretlendirme

yapılmaz)- ‘10’ 3 aylık denemeli- ‘11’ 6 aylık denemeli- ‘13’ 30 günlük

subscriber Yapılan işlem bir abonelik işlemi ise, bu aboneliğin idsini belirtir. Aboneliğin tüm periyodik ödemelerinin


29

işlemlerinde aynı SubscriberId gönderilir.Abonelikli olmayan işlemlerde ‘00000000-0000-0000-0000-000000000000’ gönderilir.

operator Siparişi oluşturan numaranın GSM operatörü- ‘1’ Turkcell- ‘7’ Vodafone- ‘3’ AVEA- ‘4’ Kredi Kartı- ‘20’ TTNET

gsmtype Siparişi oluşturan numaranın GSM türü- ‘0’ Bilinmiyor- ‘1’ PostPaid- ‘2’ PrePaid

productid Ürün ID’si.productdesc Ürünün açıklaması.mpay Yapılan işlem başlatılırken iletilen, üye işyeri tarafından

tanımlanan Id. (abonelik işlemlerindeki dönemsel ödemelerde mpay gönderilmez.)

channel Mobil Ödeme işleminin gerçekleştiği kanal:- ‘100’ Pro API- ‘101’ Basic API- ‘102’ SMS- ‘103’ Direct API- ‘104’ API Plus- ‘111’ Abonelik yenilemesi

3) Sayfanın URL’si [email protected] adresine iletilerek 3pay|Mikro Ödeme sisteminde tanımlanması sağlanır.

4) 3pay|Mikro Ödeme, bu sayfaya ilgili parametreler ile işlem sonucunu gönderir. Parametrelerin açıklamaları Error: Reference source not found başlığı altında görülebilir.

5) Bu sayfa, hem başarılı hem de başarısız işlemler için, parametreler başarıyla alınmışsa, içeriğinde sadece “OK” değerini barındırmalıdır. Parametrelerin alımı başarısızsa boş sayfa oluşmalıdır.

11.3 Web Servis Yöntemi1) İşlem sonuçlarının 3pay|Mikro Ödeme tarafından gönderilmesi için üye işyeri tarafından bir

web servis geliştirilmelidir. Bu web servis ReceiveOrderResult adlı bir metoda sahip olmalıdır. Web servis formatı aşağıdaki URL’de belirtilen şekilde olmalıdır:http://vas.mikro-odeme.com/proxy/CReceiveOrderResultService.asmx?op=ReceiveOrderResult

2) Web servisin URL’si [email protected] adresine iletilerek 3pay|Mikro Ödeme sisteminde tanımlanması sağlanır.

3) 3pay|Mikro Ödeme sistemi ReceiveOrderResult metoduna ödeme sonucunu iletir. Metodun alacağı parametreler aşağıdaki XML değerinde belirtildiği şekilde olmalıdır:

<input xmlns="http://cservices.mikro-odeme.com.tr/mapping/generated"><OrderObjectId>Guid</OrderObjectId>- İşlemin idsini belirtir


30


http://vas.mikro-odeme.com/proxy/CReceiveOrderResultService.asmx?op=ReceiveOrderResult

http://vas.mikro-odeme.com/proxy/CReceiveOrderResultService.asmx?op=ReceiveOrderResult


<GSM>string</GSM>- İşlemin yapıldığı GSM numarasını belirtir<MPAY>string</MPAY>- Yapılan işlem başlatılırken iletilen, üye işyeri tarafından

tanımlanan Id. (abonelik işlemlerindeki dönemsel ödemelerde mpay gönderilmez.)

<SMSContent>string</SMSContent>- Gönderilen SMS’in içeriğini belirtir<TotalPrice>double</TotalPrice>- İşlemin toplam tutarı<TotalUnitPrice>double</TotalUnitPrice>- İşlemin toplam kontör tutarı<State>int</State>- İşlemin sonucunu belirtir.- 100 başarılı işlem sonucunu belirtir.- 100’den büyük değerler işlemin başarısız olduğunu belirtir.<StatusCode>int</StatusCode>- Sipariş durum kodunu belirtir. ‘0’ dönerse siparişin başarılı bir

şekilde oluşturulduğunu belirtir. Ödemenin başarılı olduğu anlamına gelmez.

<ErrorCode>string</ErrorCode>- Sipariş hata kodunu belirtir. Operatör tarafından gönderilir.

Siparişe ait ödemenin hata kodudur.<ErrorMessage>string</ErrorMessage>- Sipariş hata açıklamasını belirtir. İlgili hata koduna ait

açıklama. Siparişe ait ödemenin hata açıklamasıdır.<PaymentDateTime>DateTime</PaymentDateTime>İşlem tarihini bulundurmaktadır.<GsmOperator>int</GsmOperator>- Siparişi oluşturan numaranın GSM operatörü- ‘1’ Turkcell - ‘7’ Vodafone - ‘3’ AVEA- ‘4’ Kredi Kartı<GsmType>int</GsmType>- Siparişi oluşturan numaranın GSM türü- ‘0’ Bilinmiyor- ‘1’ PostPaid- ‘2’ PrePaid<SubscriberId>Guid</SubscriberId>- Yapılan işlem bir abonelik işlemi ise, bu aboneliğin idsini

belirtir. Aboneliğin tüm periyodik ödemelerinin işlemlerinde aynı SubscriberId gönderilir.

<Products><CSaleProduct>

<ProductId>int</ProductId>- Ürün idsi. ‘0’ olarak iletilir.<ProductCategory>int</ProductCategory>- Sipariş ile ilgili ürünün/servisin kategorisi:- ‘1’ Fiziksel Ürün- ‘2’ Oyun- ‘3’ Dijital İçerik


31

- ‘4’ Servis- ‘5’ Sosyal Ağ/Arkadaşlık- ‘6’ Aidat/Otomat- ‘7’ Bahis- ‘8’ Sigorta- ‘10’ Kamu - bilet - fastfood- ‘11’ Cep Sigorta- ‘12’ Kutu Oyun- ‘14’ Mobil Uygulama / Mobil Market- ‘15’ Eğitim- ‘16’ Bağış- ‘19’ Sağlık- ‘20’ White Label Adult<ProductDescription>string</ProductDescription>- Ürünün açıklaması<BasePrice>double</BasePrice>- Ürünün fiyatı<BaseUnitPrice>double</BaseUnitPrice>- Ürünün kontör fiyatı<Unit>int</Unit>- Ürün adedi

</CSaleProduct></Products><OrderChannelId>int</OrderChannelId>- Mobil Ödeme işleminin gerçekleştiği kanal:- ‘100’ Pro API- ‘101’ Basic API - ‘102’ SMS - ‘103’ Direct API - ‘104’ API Plus- ‘111’ Subscription renewal<PaymentTypeId>int</PaymentTypeId>- Ödeme yöntemi:- ‘1’ Tek çekim- ‘2’ Aylık abonelik (iletilen miktar her ay otomatik çekilir)- ‘3’ Haftalık abonelik (iletilen miktar her hafta otomatik çekilir)- ‘4’ 2 haftalık abonelik- ‘5’ 3 aylık abonelik- ‘6’ 6 aylık abonelik- ‘7’ aylık denemeli (ilk ay ücretlendirme yapılmaz)- ‘8’ haftalık denemeli (ilk hafta ücretlendirme yapılmaz)- ‘9’ 2 haftalık denemeli (ilk 2 hafta ücretlendirme yapılmaz)- ‘10’ 3 aylık denemeli- ‘11’ 6 aylık denemeli- ‘13’ 30 günlük<PaymentCategoryId>int</PaymentCategoryId>- Sipariş kategorisi:- ‘1’ Fiziksel Ürün- ‘2’ Oyun- ‘3’ Dijital İçerik- ‘4’ Servis- ‘5’ Sosyal Ağ/Arkadaşlık


32

- ‘6’ Aidat/Otomat- ‘7’ Bahis- ‘8’ Sigorta- ‘10’ Kamu - bilet - fastfood- ‘11’ Cep Sigorta- ‘12’ Kutu Oyun- ‘14’ Mobil Uygulama / Mobil Market- ‘15’ Eğitim- ‘16’ Bağış- ‘19’ Sağlık- ‘20’ White Label Adult<Pin>string</Pin>- Pinli kurgu kullanılıyorsa kullanıcıya müşteriye gönderilen PIN

değerini belirtir. </input>

4) ReceiveOrderResult metodu çağırıldığında, aşağıdaki gibi bir XML değerini 3pay|Mikro Ödeme’ye response olarak dönmelidir:

<CReceiveOrderResultOutput xmlns="http://cservices.mikro-odeme.com.tr/mapping/generated">

<StatusCode>int</StatusCode>- İşlem Sonuç bilgisi iletim durumunu belirtir- ‘0’ gönderilirse İşlem Sonuç bilgisinin alındığını belirtir- ‘1’ gönderilirse İşlem Sonuç bilgisinin alınmadığını belirtir<ErrorCode>string</ErrorCode>- İşlem Sonuç bilgisi iletiminde hata oluştuğu durumda(StatusCode=1)açıklayıcı bir değer gönderilir.- İşlem Sonuç bilgisi iletimi başarılı olduğunda boş gönderilir.<ErrorMessage>string</ErrorMessage>- İşlem Sonuç bilgisi iletiminin açıklama mesajı- İşlem Sonuç bilgisi iletimi başarılı ise ‘Message ReceivedSuccessfully.’ şeklinde gönderilir.- İşlem Sonuç bilgisi iletimi başarısız ise ilgili exception içeriğiveya açıklayıcı bir hata mesajı gönderilir.

</CReceiveOrderResultOutput>


33

Documents

Giriş - İstanbul Halk Ekmek A.Ş. · Web viewTEKNİK ENTEGRASYON DOKÜMANI [email protected] İçindekiler 1Giriş3 1.1Temel Bilgiler3 1.2Kurgu Seçimi3 1.2.1Basic API3 1.2.2Pro