# Macellan SuperApp API Dokümantasyonu > Macellan SuperApp dijital cüzdan altyapısı sunan bir platformdur. Entegratör firmalar bu API'yi kullanarak ödeme, nakit yükleme, kullanıcı yönetimi ve diğer cüzdan işlemlerini gerçekleştirebilir. Kaynak: https://docs.altpay.dev --- # Tag-QR (https://docs.altpay.dev/tag-qr) Tag-QR; kullanıcı Macellan SuperApp üzerinden ödeme yaparken ek fonksiyonların çalıştırılmasına olanak sağlayan bir teknolojidir. ## Tag-QR Tipleri ### Sabit Fiyat Ödenecek tutar Macellan SuperApp panelinden belirlenir. Örneğin; bir turnikeden geçiş yapan tüm müşteriler 5 TL ödeyecekse bu tip kullanılabilir. Sabit fiyatlı Tag-QR'da `Fiyat Servisi` entegrasyonuna gerek yoktur. Sadece işlemin sonucunda çağrılacak olan `Ping Callback` servisi ile entegre olmak yeterlidir. ### Dinamik Fiyat Ödenecek tutarın kullanıcıya (veya başka bir değişkene) göre belirlenip Macellan SuperApp'e bildirilebileceği Tag-QR tipidir. Örneğin; bir turnikeden geçiş yapan müşteriye göre fiyat belirlenip, ödeme yapılması sağlanabilir. Dinamik fiyatlı Tag-QR hem `Fiyat Servisi` ne hem de `Ping Callback` servisine entegre olunması gerekir. ## Örnek Proje Go ile yazılmış örnek proje için [Tag-QR Example](https://github.com/macellan/tag-qr-example-service) reposunu inceleyebilirsiniz. --- # Dönüş İşlemleri (https://docs.altpay.dev/tag-qr/ping-callback) Macellan SuperApp, Tag-QR ile ödemelerde Ping Callback servisine ihtiyaç duyar. Kullanıcı Tag-QR'ı mobil uygulamadan okuttuğunda, Macellan SuperApp gerekli tüm kontrolleri yapar ve son adım olarak Ping Callback servisine istek atar. Ping Callback servisi, entegre olacak firma tarafından bu dokümanda anlatıldığı gibi hazırlanmalıdır. Macellan SuperApp Paneli üzerinden Tag-QR oluşturulurken doldurulan formda `Ping URL` alanına hazırladığınız servisin URL adresini girebilirsiniz. ![Örnek Form](ping_callback_form.png) ## Akış ### İstek Hazırlanan servise istek, Macellan SuperApp tarafından Tag-QR okutup gerekli kontrolleri yaptıktan sonra tablodaki değerlerle `POST` olarak gönderir. ```json { "price": "0.02", "point": "0.00", "order_id": "3307333742", "user_id": "3b43544b-10b4-45e2-ab81-2b2b3f1917e8", "user_phone": "905555555555", "ref_code": "0781534070", "callback_success_url": "https://api.altpay.dev/tag-qr/3307333742/success", "callback_fail_url": "https://api.altpay.dev/tag-qr/3307333742/fail", "hash": "9fe2ea5ad3f1f5b0289b151521ed1ed2d772dae0" } ``` | Değer | Tip | Açıklama | |------------------------|----------|------------------------------------------------------------------------| | `price` | `string` | Kullanıcının bakiyesinden düşülecek tutar. | | `point` | `string` | Kullanıcının puanından düşülecek tutar. | | `order_id` | `string` | Macellan SuperApp'in ödemeye atadığı sipariş numarası. | | `user_id` | `string` | İşlem yapan müşterinin tekil kullanıcı IDsi. | | `user_phone` | `string` | İşlem yapan müşterinin tekil kullanıcı telefon numarası. | | `ref_code` | `string` | Müşteri tarafından mobil uygulamadan okutulan Tag-QR'ın referans kodu. | | `callback_success_url` | `string` | İşlem sonunda işlemin başarılı olduğunu bildirebileceğiniz adres. | | `callback_fail_url` | `string` | İşlem sonunda işlemin başarısız olduğunu bildirebileceğiniz adres. | | `hash` | `string` | Hash doğrulamasında kullanılacak değer. | İsteğin Macellan SuperApp'den geldiğini doğrulayabilmek için [Hash Doğrulaması](#gelen-istegi-dogrulama) yapabilirsiniz. Eğer isteği doğru bir şekilde aldıysanız yanıt olarak status kodunu `200` olarak göndermelisiniz. ### Gelen İsteği Doğrulama Hash doğrulamanın amacı gelen isteğin Macellan SuperApp tarafından gönderildiğine emin olmaktır. Doğrulama, istek ile beraber gelen bellirli değerleri aşağıdaki sıra ile birleştirilip sonucun `sha1` hashi alınarak yapılır. `salt` değişkeni Macellan SuperApp panelinden Tag-QR oluşturulurken formdaki `Salt Key` değeridir. Eğer `hash` değeri doğru değilse response status kodunu `403` ile yanıt verebilirsiniz. ``` salt + callback_fail_url + callback_success_url + price ``` ### İşlem Sonucunu Bildirme İsteği aldıktan sonra kendi tarafınızdaki yapmanız gereken tüm işlemleri yapınız, daha sonra işlemin durumunu Macellan SuperApp'e bildirmeniz gerekmektedir. İşlem başarılı ise ilk gelen istekteki `callback_success_url` değerindeki adrese `POST` isteği atmalısınız. İşlem başarısız olmuşsa `callback_fail_url` değerindeki adrese `POST` isteği atılmalıdır. #### Dönüş İstekleri İçin Hash Hesaplama Dönüş isteği atılırken Macellan SuperApp'in istekte bulunanın siz olduğunuzu anlayabilmesi için hash değerine ihtiyaç duyar. Dönüş isteklerinde göndereceğiniz hash değerinin hesaplama sırası, size gelen istek doğrulamasından farklıdır. Hash hesaplayabilmek için ilk istekte gönderilen değerleri aşağıdaki sırayla birleştirip `sha1` hashını almalısınız. ``` price + callback_success_url + callback_fail_url + salt ``` #### Dönüş İstekleri Kendi tarafınızdaki kontrolleri ve gerçekleşmesi gereken tüm işlemleri yaptıktan sonra, işlemin durumunu Macellan SuperApp'e bildirmelisiniz. Sonucu bildirebilmek için ilk gelen istekteki `callback_succes_url` veya `callback_fail_url` adreslerini kullanabilirsiniz. Eğer işlem sizin tarafınızda başarısız olmuş, örneğin işlem sonunda kapı açmak istiyorsanız, kapıyı açacak olan cihaz ile iletişim kuramamış olabilirsiniz veya cihaz size hata ile dönmüşse bu durumu bildirmek için `callback_fail_url` deki adrese istek göndermelisiniz. İşlemin kesin olarak başarılı olduğuna eminseniz, örneğin kapı açılacaksa cihazınızdan `kapı açıldı` komutu size ulaştıktan sonra `callback_succes_url` e istek göndermelisiniz. Eğer durum başarılı olarak bildirildiyse, tutar bakiyeden düşülür ve ödeme tamamlanmış olur. --- # Fiyat Servisi (https://docs.altpay.dev/tag-qr/price-service) Dinamik Tutarlı Tag-QR'da ödeme yapılacak tutarı, Macellan SuperApp aşağıda anlatıldığı gibi sizin hazırladığınız servise sorar ve dönen fiyata göre işlem yapar. Macellan SuperApp Paneli üzerinden Tag-QR oluştururken fiyat tipini `Dinamik` seçip, hazırladığınız servisin URL adresini buraya yazabilirsiniz. ![Örnek Form](dynamic_price_form.png) Formda yazılı olan `https://tag-qr.altpay.dev/get-price` değerini kendi hazırladığınız URL ile değiştirmelisiniz. ## Akış ### İstek Kullanıcı Tag-QR'ı okuttuğunda Macellan SuperApp sizin hazırladığınız servise aşağıdaki değerlerle `POST` sorgusu gönderir. İsteğin Macellan SuperApp'den geldiğini doğrulayabilmek için [Hash Doğrulaması](#hash-dogrulama) yapabilirsiniz. ```json { "ref_code": "0757249206", "user_id": "c6e87629-725c-4a1d-bbfc-ebc21cd32ae3", "user_phone": "905555555555", "order_id": "1897607390", "hash": "2228d897082824ca0c385755a30af6d8a692be8e" } ``` | Değer | Tip | Açıklama | |--------------|----------|------------------------------------------------------------------------| | `ref_code` | `string` | Müşteri tarafından mobil uygulamadan okutulan Tag-QR'ın referans kodu. | | `user_id` | `string` | İşlem yapan müşterinin tekil kullanıcı ID'si. | | `user_phone` | `string` | İşlem yapan müşterinin tekil kullanıcı telefon numarası. | | `order_id` | `string` | Macellan SuperApp'in ödemeye atadığı sipariş numarası. | | `hash` | `string` | Hash doğrulamasında kullanılacak değer. | ### Sonuç Gönderilen parametreleri kullanarak tutarı belirleyip yanıt verebilir veya işlemi durdurabilirsiniz. Macellan SuperApp yanıtı JSON olarak aşağıdaki değerleri bekler. ```json { "price": 1.12 } ``` | Değer | Tip | Açıklama | |---------|---------|----------------------------------------------------------| | `price` | `float` | İşlem sonunda kullanıcının bakiyesinden düşülecek tutar. | ### Hata Durumu Eğer servisten hata ile dönmeniz gerekiyorsa, response status `400` göndererek ödemeyi durdurabilirsiniz. Hata durumunda response aşağıdaki gibi olabilir. ```json { "message": "Fail", "user_message": "Lütfen önce bilet alınız." } ``` | Değer | Tip | Açıklama | |----------------|----------|-------------------------------------------------------| | `message` | `string` | Macellan SuperApp Backend'ine göndereceğiniz mesaj. | | `user_message` | `string` | Mobil uygulamada kullanıcıya göstereceğiniz mesaj. | ## Hash Doğrulama Hash doğrulamanın amacı gelen isteğin Macellan SuperApp tarafından gönderildiğine emin olmaktır. Doğrulama, istek ile beraber gelen değerleri aşağıdaki sıra ile birleştirilip sonucun `sha1` hashi alınarak yapılır. `salt` değişkeni Macellan SuperApp panelinden Tag-QR oluşturulurken formdaki `Salt Key` değeridir. Eğer `hash` değeri doğru değilse response status `403` ile yanıt verebilirsiniz. ``` ref_code + user_id + order_id + salt ``` ### Hash Doğrulama Örnek --- # Ödeme (https://docs.altpay.dev/payment) Ödeme servisi Macellan SuperApp kullanıcılarının sahip olduğu dijital cüzdan ile ödeme yapılmasına olanak sağlayan servistir. Ödeme servisi temel olarak 2 akışa sahiptir. Bunlar; ### 1) QR'ın kullanıcı tarafından oluşturulduğu akış Kullanıcı, ödeme yapmak için Macellan SuperApp mobil uygulamasındaki dijital cüzdanıyla birlikte 6 haneli referans kodunu içeren QR Kod oluşturur. Entegratör firma, bu QR kodunu okuyarak veya 6 haneli referans kodunu kullanarak ödeme yapılacak tutarı bu servise iletir. Servis, gerekli kontrolleri yaptıktan sonra mobil uygulamada kullanıcıya ödeme onay ve özet ekranlarını gösterir. Bu sırada entegratör firma, belirli aralıklarla ödemenin durumunu kontrol eder ve ödemenin durumuna bağlı olarak işlemi sonlandırır. ### 2) QR'ın entegratör firma tarafından oluşturulduğu akış Entegratör firma, ödeme yapılacak tutarı servise iletir. Servisten dönen referans kod değeri ile QR kod oluşturur. Kullanıcı Macellan SuperApp mobil uygulamasındaki cüzdanı ile bu QR kodu okur veya 6 haneli referans kodu yazarak servise iletir. Servis gerekli kontrolleri yaptıktan sonra mobil uygulamada kullanıcıya ödeme onay ve özet ekranlarını gösterir. Bu sırada entegratör firma, belirli aralıklarla ödemenin durumunu kontrol eder ve ödemenin durumuna bağlı olarak işlemi sonlandırır. ### Ödeme İşleminin Durumları ve Açıklamaları | **Durum** | **Açıklama** | |:----------:|:----------------------------------------------------------| | create | Ödeme işlemi oluşturuldu. | | approval | Kullanıcı onayı bekleniyor. | | approved | Kullanıcı ödeme işlemini onayladı. | | reject | Kullanıcı ödeme işlemini reddetti. | | no_balance | Kullanıcı ödeme işlemi için yeterli bakiyeye sahip değil. | | expire | Ödeme işleminin süresi doldu. | | complete | Ödeme işlemi başarılı bir şekilde tamamlandı. | --- # Generate QR - Payment Create (https://docs.altpay.dev/payment/(generate-qr)/payment-create) **POST** `/integration/payment/create` - Create Servisi, harcama işlemlerini oluşturmak amacıyla kullanılır. - İşlem sonucunda dönen referans kodu, Macellan SuperApp kullanıcısına iletilir ve bu referans kodu ya da oluşturulan QR kodu kullanılarak işlem devam ettirilebilir. - QR kodun süresi 120 saniyedir. ### Extra Bilgiler - `external_id` alanı opsiyoneldir. Genellikle ödemeye ait sipariş numarası gibi harici sistem ID'si burada gönderilir; işlemleri kolayca takip etmenize yardımcı olur. - Aynı kasa ve tutarla kısa süre içinde tekrar istek atıldığında mevcut QR döner. `external_id` farklı gönderilirse yeni bir QR üretilir. - Mevcut QR'ın tekrar kullanılabilmesi için `external_id` değerlerinin birebir eşleşmesi gerekir; isteklerden birinde `external_id` gönderilip diğerinde gönderilmediğinde de yeni bir QR üretilir. - Mevcut QR döndüğünde, istekle birlikte `product_list` gönderildiyse ürün listesi yeni gönderilen değerle güncellenir. ### Ürün Listesi `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. Bu bilgiler raporlama ve analiz amaçlı kullanılır. Ürün listesi gönderildiğinde: * Her ürün için `price` ve `quantity` alanları birlikte zorunludur * Her ürünün `total_price` değeri, `price * quantity` ile eşleşmelidir * Tüm ürünlerin `total_price` toplamı, harcama tutarı `price` ile eşleşmelidir ### Request Body - `price` (number, zorunlu): Harcama İşlem Tutarı (ornek: 1.23) - `branch_code` (string): Tek Bir Token İle Entegrasyon Sağlandığında Kullanılan Şube Kodu (ornek: "Test-123") - `external_id` (string): Harici sistem ID değeri (ornek: "EXT-12345") - `product_list` (array): Ürün listesi (ornek: [{"item_id":1,"name":"Ayran","category_name":"İçecekler","price":20,"quantity":2,"total_price":40}]) - `item_id` (integer): Ürün ID (ornek: 1) - `name` (string): Ürün adı (ornek: "Ayran") - `category_name` (string): Kategori adı (ornek: "İçecekler") - `price` (number): Birim fiyat (quantity ile birlikte zorunlu) (ornek: 20) - `quantity` (integer): Miktar (price ile birlikte zorunlu) (ornek: 2) - `total_price` (number): Toplam fiyat (price ve quantity varsa zorunlu) (ornek: 40) ### Response 200 - `data` (object): - `hash` (string): Harcama İşlem Hashi (ornek: "hash") - `payment_id` (integer): Harcama İşlem ID (ornek: 1) - `order_id` (integer): Harcama Unique Sipariş ID (ornek: 1405321795) - `reference_code` (integer): 6 Haneli Harcama Referans Kodu (ornek: 123456) - `expires_at` (string): Harcamanın Süresinin Dolacağı Tarih (ornek: "2023-06-12T13:25:45.000000Z") - `server_time` (string): Sunucu Zamanı (ornek: "2023-06-12T13:16:15.833622Z") ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # İade - Direct Refund (https://docs.altpay.dev/payment/(iade)/payment-direct-refund) **POST** `/integration/payment/refund/direct` - Direct Refund servisi, entegratör firmanın kullanıcı tarafından oluşturulan iade isteği olmaksızın harcama işlemini iade etmek için kullanılır. ### Ürün Listesi `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. Bu bilgiler raporlama ve analiz amaçlı kullanılır. Ürün listesi gönderildiğinde: * Her ürün için `price` ve `quantity` alanları birlikte zorunludur * Her ürünün `total_price` değeri, `price * quantity` ile eşleşmelidir * Tüm ürünlerin `total_price` toplamı, ödeme tutarı `price + point` ile eşleşmelidir ### Request Body - `amount` (number, zorunlu): İade Edilmek İstenen Tutar (ornek: 1.23) - `order_id` (integer, zorunlu): Harcama İşlemi Unique Sipariş ID (ornek: 1131347753) - `comment` (string): Şirket Notu (ornek: "Test") - `product_list` (object): ### Response 200 ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # İade - Refund Close (https://docs.altpay.dev/payment/(iade)/payment-refund-close) **POST** `/integration/payment/refund/close` - Refund Close servisi iade isteğini iptal etmek için kullanılır. ### Request Body - `request_id` (integer, zorunlu): İade İşlem ID (ornek: 1) - `comment` (string): Şirket Notu (ornek: "Test") ### Response 200 - `data` (object): - `success` (boolean): ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") ### Response 412 - `message` (string): (ornek: "İade isteği kapatılamaz.") --- # İade - Refund Make (https://docs.altpay.dev/payment/(iade)/payment-refund-make) **POST** `/integration/payment/refund/make` - Refund Make servisi harcama işleminin iadesini gerçekleştirmek için kullanılır. - Bu servis çağrıldıktan sonra iade işlemi sonlanır. ### Request Body - `request_id` (integer, zorunlu): İade İstek ID (ornek: 1) - `amount` (number, zorunlu): İade Edilecek Tutar (ornek: 1) - `comment` (string): Şirket Notu (ornek: "Test") ### Response 200 - `data` (object): - `success` (boolean): ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") ### Response 412 - `message` (string): (ornek: "İade isteği kapatılamaz.") --- # İade - Details (https://docs.altpay.dev/payment/(iade)/payment-refund-request-details) **GET** `/integration/payment/refund/request/{refundRequestId}/details` - Refund Request Details servisi, iade işleminin detaylarını görüntülemek için kullanılır. ### Parametreler - `refundRequestId` (integer, zorunlu, path): İade İşlem ID (ornek: 1) ### Response 200 - `data` (object): - `id` (integer): İade İstek ID (ornek: 1) - `reference_code` (string): İade Referans Numarası (ornek: "123456") - `complete` (boolean): İade Referans Numarası - `user_refunable` (boolean): - `status` (string): İade Durumu [open, refund, close] - `status_translate` (string): [Onay Bekliyor, İade Edildi, Reddedildi] - `reason` (string): [return_product, objection_expense, amount_failure, other, gift_card] - `reason_translate` (string): [Ürün İadesi, Harcama İtirazı, Hatalı Tutar, Diğer Sebepler, Hediye Kartı] - `user_comment` (string): Kullanıcı Notu (ornek: "Test") - `company_comment` (string): Şirket Notu (ornek: "Test") - `amount` (number): İade Edilmek İstenen Tutar (ornek: 1.23) - `amount_show` (string): İade Edilmek İstenen Tutar(Para Birimine Göre Formatlanır) (ornek: "1,23") - `refund_time` (string): İade Tarihi - `created_at` (string): - `updated_at` (string): - `company` (object): - `id` (integer): Şirket ID (ornek: 1) - `name` (string): Şirket Adı (ornek: "Test") - `logo` (string): Şirket Logo URL - `color` (string): Şirket Rengi (ornek: "#A71A1A") - `currency` (string): Şirket Para Birimi [TL, USD, AZN] - `active` (boolean): Şirketin Akiftik Durumunu Belirtir - `region` (string): Şirketin Bulunduğu Bölge [TR, AZ] ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # İade - Payment Refund Request List (https://docs.altpay.dev/payment/(iade)/payment-refund-request-list) **GET** `/integration/payment/refund/request/list` - Payment Refund Request List servisi entegratör firmanın bağlı olduğu şirkete ve kullanıcıya ait bütün iade isteklerinin listelediği servistir. - Mütabakat servisi olarak kullanılabilir. - Eğer bir harcamaya ait iadeleri almak istiyorsanız parametre olarak `order_id` göndererek filtreleme yapabilirsiniz. ### Parametreler - `per_page` (integer, query): Sayfa Başı Listeleme Sayısı (ornek: 30) - `start_date` (string, query): Başlangıç Tarihi - `end_date` (string, query): Bitiş Tarihi - `order_id` (integer, query): Harcama ID numarası ### Response 200 - `data` (array): - `id` (integer): (ornek: 1) - `order_id` (integer): (ornek: 1) - `reference_code` (string): (ornek: "123456") - `complete` (boolean): (ornek: false) - `amount` (number): (ornek: 1.23) - `status` (string): Harcama Durumu [create, approval, approved, no_balance, reject, expire, complete, service_error] (ornek: "approved") - `status_translate` (string): Harcama Durumu(Dile Göre Çevrilmiş) [Oluşturuldu, Onayda, Onaylandı, Limit Yetersiz, Reddedildi, Süresi Doldu, Tamamlandı, Servis Hatası] (ornek: "Onaylandı") - `reason_translate` (string): [Ürün İadesi, Harcama İtirazı, Hatalı Tutar, Diğer Sebepler, Hediye Kartı] - `user` (object): Kullanıcı Bilgileri - `uuid` (string): Kullanıcı Unique UUID (ornek: "eb5b6e88-0ae9-4810-bd18-f9c5b0a77fc7") - `first_name` (string): Kullanıcı Adı (ornek: "AB****") - `last_name` (string): Kullanıcı Soyadı (ornek: "CD****") - `full_name` (string): Kullanıcı Ad Soyadı (ornek: "AB**** D****") - `email` (string): Kullanıcı E-Maili (ornek: "ab*****@macellan.net") - `phone` (string): Kullanıcı Telefon Numarası (ornek: "90***********") - `branch` (object): Şube Bilgileri - `name` (string): Şube Adı (ornek: "Test") - `address` (string): Şube Adresi (ornek: "Test Mh. Test Cd. No:1") - `phone` (string): Şube Telefon Numarası (ornek: "01234567890") - `cashier` (object): Kasiyer Bilgeri - `first_name` (string): Kasiyer Adı (ornek: "Tony") - `last_name` (string): Kasiyer Soyadı (ornek: "Cashier") - `full_name` (string): Kasiyer Ad Soyadı (ornek: "Tony Cashier") - `email` (string): Kasiyer E-Maili - `phone` (string): Kasiyer Telefon Numarası (ornek: "01234567890") - `status` (string): Kasiyer Hesap Durumu [active, passive, block, unverify] - `refund_time` (string): - `created_at` (string): - `meta` (object): Pagination - `paginate` (object): - `per_page` (integer): Sayfa Başı Listeleme Sayısı (ornek: 20) - `current_page` (integer): Şuanki Sayfa Numarası (ornek: 1) - `has_more` (boolean): Bir Sonraki Sayfanın Olup Olmadığını Belirtir. ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # OTP İle Ödeme - Doğrulama (https://docs.altpay.dev/payment/(otp-ile-odeme)/payment-with-otp-complete) **POST** `/integration/payment/otp/complete` - OTP ödeme tamamlama servisi ile müşteriden alınan OTP kodu ve harcama id ile ödeme işlemini tamamlamak için kullanılır. - [Ödeme Başlatma](/payment/payment-with-otp-send) isteğinden sonra çalıştırılması gerekmektedir. ### Request Body - `phone` (string, zorunlu): Kullanıcı telefon bilgisi ([E.164 Format](https://www.twilio.com/docs/glossary/what-e164)) (ornek: "+905231113344") - `code` (string, zorunlu): OTP doğrulama kodu (ornek: "123456") - `payment_id` (integer, zorunlu): Harcama ID (ornek: 1) ### Response 200 - `data` (object): - `payment_id` (integer): Harcama İşlem ID (ornek: 1) - `wallet_id` (integer): Harcama Cüzdan ID (ornek: 1) - `user_id` (integer): Harcama Kullanıcı ID (ornek: 1) - `user_mapping_id` (string): Kullanıcıya ait waas linkleme id değeri. (Iframe açma, harcama gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `company_id` (integer): Harcama Şirket ID (ornek: 1) - `branch_id` (integer): Harcama Şube ID (ornek: 1) - `cashier_id` (integer): Harcama Kasiyer ID (ornek: 1) - `reference_code` (integer): 6 Haneli Harcama Referans Kodu (ornek: 123456) - `order_id` (integer): Harcama Unique Sipariş ID (ornek: 1305549790) - `price` (number): Harcama İşlem Tutarı (ornek: 1) - `paid_price` (number): Harcanan İşlem Tutarı (ornek: 1) - `price_show` (string): Harcama İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `paid_price_show` (string): Harcanan İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `point` (number): Harcama Puan Tutarı (ornek: 1) - `point_show` (string): Harcama Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `final_total` (number): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı) (ornek: 1) - `final_total_show` (string): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı)(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discounted_total_amount` (number): İndirimli Toplam Tutar (ornek: 1) - `discounted_total_amount_show` (string): İndirimli Toplam Tutar(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discount_point` (number): İndirim Puan Tutarı (ornek: 0) - `discount_point_show` (string): İndirim Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `discount_percent` (number): İndirim Yüzdesi (ornek: 0) - `refund_amount` (number): İade Tutarı (ornek: 0) - `status` (string): Harcama Durumu [create, approval, approved, no_balance, reject, expire, complete, service_error] (ornek: "approved") - `status_translate` (string): Harcama Durumu(Dile Göre Çevrilmiş) [Oluşturuldu, Onayda, Onaylandı, Limit Yetersiz, Reddedildi, Süresi Doldu, Tamamlandı, Servis Hatası] (ornek: "Onaylandı") - `gateway` (string): Harcama Geçidi [eftpos, terminal, static_qr, tag_qr, kerzz_pos, tap_card, gizmo, iap] (ornek: "terminal") - `is_shared_wallet` (boolean): Harcamanın Paylaşılan Cüzdan ile Yapılıp Yapılmadığını Belirtir - `wallet_share_id` (integer): Paylaşılan Cüzdan ID - `user_fillable_point` (boolean): Kullanıcı Harcama İşleminde Puan Tutarını Belirleyebilir - `wallet_share` (object): Cüzdan Paylaşımı - `description` (string): Açıklama ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") ### Response 404 - `message` (string): ### Response 406 - `message` (string): --- # OTP İle Ödeme - Gönderim (https://docs.altpay.dev/payment/(otp-ile-odeme)/payment-with-otp-send) **POST** `/integration/payment/otp/send` - OTP ile ödeme başlatma servisi, müşterinin telefon ve ödeme detayları ile ödeme işlemi başlatılması için kullanılır. - Müşterinin telefonuna OTP doğrulama kodu gönderilir ve ödeme kaydını oluşturur. - Ödemeyi tamamlamak için [doğrulama](/payment/payment-with-otp-complete) servisi çağrılmalıdır. - Ödeme bilgileri 2 farklı şekilde kullanılabilir. Puan tutarının manuel belirlenmesi veya kullanıcıya puan kullanma seçeneğinin seçtirilmesi - **Puan Kullanımının Kullanıcı Tarafından Seçtirilmesi(point_usage kullanımı):** İstekte opsiyonel olarak istenen `point_usage` parametresi kullanıldığında, kullanıcı cüzdanındaki puan tutarı önceliklendirilerek, harcama tutarı kadar kullandırılmaya çalışılır. Örn. 100 liralık harcama isteğinde, kullanıcının 500 Bakiye, 200 Puan olduğunu düşünürsek, `point_usage` parametresi `true` gönderdildiğinde harcama, kullanıcının puan tutarından düşürülerek gerçekleştirilir. Ödeme işlemi sonrası kullanıcının cüzdanı 500 Bakiye, 100 Puan olarak güncellenir. - **Puan Tutarının Manuel Belirlenmesi(point kullanımı):** Harcamada kullanıcının cüzdanından düşülecek puanın sizin tarafınızdan belirlenmesidir. İstekte opsiyonel olarak istenen `point` değeri kadar kullanıcı cüzdanından harcama yapılmaya çalışılır. Örn. 100 liralık harcama isteğinde, price: 70, point: 30 gönderildiğinde kullanıcı cüzdanından 70 bakiye ve 30 puan ile harcama yapılmaya çalışılacaktır. Bu yöntem ile harcama isteği yapıldığında, `price` ve `point` değerlerini kullanıcı cüzdan tutarına göre sizin hesaplamanız gerekmektedir. Bu yöntem kullanıldığında `point_usage` parametresi gönderilse bile dikkate alınmayacaktır. ### Extra Bilgiler - `external_id` alanı opsiyoneldir. Genellikle ödemeye ait sipariş numarası gibi harici sistem ID'si burada gönderilir; işlemleri kolayca takip etmenize yardımcı olur. ### Ürün Listesi `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. Bu bilgiler raporlama ve analiz amaçlı kullanılır. Ürün listesi gönderildiğinde: * Her ürün için `price` ve `quantity` alanları birlikte zorunludur * Her ürünün `total_price` değeri, `price * quantity` ile eşleşmelidir ### Request Body - `phone` (string, zorunlu): Kullanıcı telefon bilgisi ([E.164 Format](https://www.twilio.com/docs/glossary/what-e164)) (ornek: "+905231113344") - `price` (number, zorunlu): Harcama İşlem Tutarı (ornek: 1.23) - `point` (number): Harcamada cüzdandan düşülecek puan değeri. Bu parametre null veya gönderilmezse, `point_usage parametresi dikkate alınacatır (ornek: 1) - `point_usage` (boolean): Harcama puan ile yapılmalı mı - `apply_campaigns` (boolean): Harcama sonucunda kullanıcının kampanyadan faydalanıp faydalanmayacağını belirtir. - `external_id` (string): Harici sistem ID değeri (ornek: "EXT-12345") - `branch_code` (string): Tek Bir Token İle Entegrasyon Sağlandığında Kullanılan Şube Kodu (ornek: "Test-123") - `product_list` (object): ### Response 200 - `data` (object): - `verification` (object): - `expires_at` (string): OTP nin geçerlilik süresi - `server_time` (string): Sunucu tarihi - `code` (string): OTP doğrulama kodu. Bu değer sadece development ortamında gönderilmektedir. (ornek: 123456) - `payment` (object): ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") ### Response 404 - `message` (string): ### Response 412 - `message` (string): (ornek: "Bakiye yetersiz.") --- # Payment - Direct Charge (https://docs.altpay.dev/payment/(payment)/payment-direct-charge) **POST** `/integration/payment/direct-charge` - Direct Charge servisi Macellan SuperApp kullanıcısı onayı, QR veya referans kodu olmadan harcama işlemi yapmak için kullanılır. - Bu servisi kullanmak için **Direct Payment Api** modülünün açık olması gerekir. ### Extra Bilgiler - `external_id` alanı opsiyoneldir. Genellikle ödemeye ait sipariş numarası gibi harici sistem ID'si burada gönderilir; işlemleri kolayca takip etmenize yardımcı olur. ### Ürün Listesi `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. Bu bilgiler raporlama ve analiz amaçlı kullanılır. Ürün listesi gönderildiğinde: * Her ürün için `price` ve `quantity` alanları birlikte zorunludur * Her ürünün `total_price` değeri, `price * quantity` ile eşleşmelidir * Tüm ürünlerin `total_price` toplamı, harcama tutarı `price + point` ile eşleşmelidir ### Request Body - `wallet_id` (integer, zorunlu): Harcama Yapılacak Cüzdan ID (ornek: 12) - `price` (number, zorunlu): Harcama İşlem Tutarı (ornek: 1) - `point` (number): Harcama Puan Tutarı (ornek: 0) - `gateway` (string, zorunlu): Harcama Geçidi [eftpos, terminal, static_qr, tag_qr, kerzz_pos, tap_card, gizmo, iap] (ornek: "terminal") - `branch_code` (string): Tek Bir Token İle Entegrasyon Sağlandığında Kullanılan Şube Kodu (ornek: "Test-123") - `external_id` (string): Harici sistem ID değeri (ornek: "EXT-12345") - `product_list` (array): Ürün listesi (ornek: [{"item_id":1,"name":"Ayran","category_name":"İçecekler","price":20,"quantity":2,"total_price":40}]) - `item_id` (integer): Ürün ID (ornek: 1) - `name` (string): Ürün adı (ornek: "Ayran") - `category_name` (string): Kategori adı (ornek: "İçecekler") - `price` (number): Birim fiyat (quantity ile birlikte zorunlu) (ornek: 20) - `quantity` (integer): Miktar (price ile birlikte zorunlu) (ornek: 2) - `total_price` (number): Toplam fiyat (price ve quantity varsa zorunlu) (ornek: 40) - `apply_campaigns` (boolean): Harcama sonucunda kullanıcının kampanyadan faydalanıp faydalanmayacağını belirtir. ### Response 200 - `data` (object): - `payment_id` (integer): Harcama İşlem ID (ornek: 1) - `wallet_id` (integer): Harcama Cüzdan ID (ornek: 1) - `user_id` (integer): Harcama Kullanıcı ID (ornek: 1) - `user_mapping_id` (string): Kullanıcıya ait waas linkleme id değeri. (Iframe açma, harcama gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `company_id` (integer): Harcama Şirket ID (ornek: 1) - `branch_id` (integer): Harcama Şube ID (ornek: 1) - `cashier_id` (integer): Harcama Kasiyer ID (ornek: 1) - `reference_code` (integer): 6 Haneli Harcama Referans Kodu (ornek: 123456) - `order_id` (integer): Harcama Unique Sipariş ID (ornek: 1305549790) - `price` (number): Harcama İşlem Tutarı (ornek: 1) - `paid_price` (number): Harcanan İşlem Tutarı (ornek: 1) - `price_show` (string): Harcama İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `paid_price_show` (string): Harcanan İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `point` (number): Harcama Puan Tutarı (ornek: 1) - `point_show` (string): Harcama Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `final_total` (number): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı) (ornek: 1) - `final_total_show` (string): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı)(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discounted_total_amount` (number): İndirimli Toplam Tutar (ornek: 1) - `discounted_total_amount_show` (string): İndirimli Toplam Tutar(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discount_point` (number): İndirim Puan Tutarı (ornek: 0) - `discount_point_show` (string): İndirim Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `discount_percent` (number): İndirim Yüzdesi (ornek: 0) - `refund_amount` (number): İade Tutarı (ornek: 0) - `status` (string): Harcama Durumu [create, approval, approved, no_balance, reject, expire, complete, service_error] (ornek: "approved") - `status_translate` (string): Harcama Durumu(Dile Göre Çevrilmiş) [Oluşturuldu, Onayda, Onaylandı, Limit Yetersiz, Reddedildi, Süresi Doldu, Tamamlandı, Servis Hatası] (ornek: "Onaylandı") - `gateway` (string): Harcama Geçidi [eftpos, terminal, static_qr, tag_qr, kerzz_pos, tap_card, gizmo, iap] (ornek: "terminal") - `is_shared_wallet` (boolean): Harcamanın Paylaşılan Cüzdan ile Yapılıp Yapılmadığını Belirtir - `wallet_share_id` (integer): Paylaşılan Cüzdan ID - `user_fillable_point` (boolean): Kullanıcı Harcama İşleminde Puan Tutarını Belirleyebilir - `wallet_share` (object): Cüzdan Paylaşımı - `description` (string): Açıklama ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Payment - Payment List (https://docs.altpay.dev/payment/(payment)/payment-list) **GET** `/integration/payment/list` - Payment List servisi entegratör firmanın bağlı olduğu şirkete ve kullanıcıya ait bütün harcama işlemlerinin listelediği servistir. - Mütabakat servisi olarak kullanılabilir. ### Parametreler - `per_page` (integer, query): Sayfa Başı Listeleme Sayısı (ornek: 30) - `start_date` (string, query): Başlangıç Tarihi - `end_date` (string, query): Bitiş Tarihi - `status` (, query): Harcama Durumu - `branch_code` (string, query): Tek Bir Token İle Entegrasyon Sağlandığında Kullanılan Şube Kodu ### Response 200 - `data` (array): - `id` (integer): Harcama İşlem ID (ornek: 1) - `user` (object): Kullanıcı Bilgileri - `uuid` (string): Kullanıcı Unique UUID (ornek: "eb5b6e88-0ae9-4810-bd18-f9c5b0a77fc7") - `first_name` (string): Kullanıcı Adı (ornek: "AB****") - `last_name` (string): Kullanıcı Soyadı (ornek: "CD****") - `full_name` (string): Kullanıcı Ad Soyadı (ornek: "AB**** D****") - `email` (string): Kullanıcı E-Maili (ornek: "ab*****@macellan.net") - `phone` (string): Kullanıcı Telefon Numarası (ornek: "90***********") - `paid_price` (number): Harcama İşlem Tutarı (ornek: 1.23) - `point` (number): Harcama Puan Tutarı (ornek: 0) - `final_total` (number): Harcama Toplam Tutarı (ornek: 1.23) - `refund_amount` (number): Varsa Harcama İşlemine Ait İade Tutarı (ornek: 0) - `transaction_code` (string): Harcama İşlemi Kodu (ornek: "V4SBUQG3PMNLCR0") - `reference_code` (string): Harcama İşlemi Referans Kodu (ornek: "123456") - `order_id` (string): Harcama Unique Sipariş ID (ornek: "3279724498") - `payment_time` (string): Harcama Tarihi - `created_at` (string): Harcama Oluşturulma Tarihi - `branch` (object): Şube Bilgileri - `name` (string): Şube Adı (ornek: "Test") - `address` (string): Şube Adresi (ornek: "Test Mh. Test Cd. No:1") - `phone` (string): Şube Telefon Numarası (ornek: "01234567890") - `cashier` (object): Kasiyer Bilgeri - `first_name` (string): Kasiyer Adı (ornek: "Tony") - `last_name` (string): Kasiyer Soyadı (ornek: "Cashier") - `full_name` (string): Kasiyer Ad Soyadı (ornek: "Tony Cashier") - `email` (string): Kasiyer E-Maili - `phone` (string): Kasiyer Telefon Numarası (ornek: "01234567890") - `status` (string): Kasiyer Hesap Durumu [active, passive, block, unverify] - `wallet_share` (object): Cüzdan Paylaşımı - `description` (string): Açıklama - `meta` (object): Pagination - `paginate` (object): - `per_page` (integer): Sayfa Başı Listeleme Sayısı (ornek: 20) - `current_page` (integer): Şuanki Sayfa Numarası (ornek: 1) - `has_more` (boolean): Bir Sonraki Sayfanın Olup Olmadığını Belirtir. ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Payment - Ödeme Detay Güncelleme (https://docs.altpay.dev/payment/(payment)/payment-update-detail) **PUT** `/integration/payment/update/detail` - Ödeme işlemi tamamlandıktan sonra ödeme detaylarını güncellemek için kullanılır. - Bu servis ile ödeme işlemine ait ek bilgiler external_id, product_list ve extra gibi detaylar güncellenebilir. ### Extra Bilgiler - `external_id` alanı opsiyoneldir. Genellikle ödemeye ait sipariş numarası gibi harici sistem ID'si burada gönderilir; işlemleri kolayca takip etmenize yardımcı olur. - `extra` alanı opsiyoneldir ve ödeme işlemine ait ek bilgileri bu alanda gönderebilirsiniz. - `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. ### Ürün Listesi `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. Bu bilgiler raporlama ve analiz amaçlı kullanılır. Ürün listesi gönderildiğinde: * Her ürün için `price` ve `quantity` alanları birlikte zorunludur * Her ürünün `total_price` değeri, `price * quantity` ile eşleşmelidir * Tüm ürünlerin `total_price` toplamı, ödeme tutarı `price + point` ile eşleşmelidir ### Request Body - `order_id` (integer, zorunlu): Güncellenecek ödeme işleminin unique sipariş ID değeri (ornek: 1131347753) - `external_id` (string): Harici sistem ID değeri (ornek: "EXT-12345") - `extra` (object): Ödeme işlemine ait ek bilgiler (ornek: {"note":"Özel not","source":"mobile_app"}) - `product_list` (object): ### Response 200 - `data` (object): - `success` (boolean): (ornek: true) ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") ### Response 404 - `message` (string): (ornek: "Ödeme işlemi bulunamadı") ### Response 422 - `message` (string): message (ornek: "Gönderdiğiniz Veriler Geçersiz") - `errors` (object): Hata detayları - `property` (array): Hata açıklamaları (ornek: ["Hata açıklaması"]) --- # Read QR - Cancel (https://docs.altpay.dev/payment/(read-qr)/payment-cancel) **POST** `/integration/payment/cancel` - Cancel servisi, harcama işleminin iptal edilmesini sağlar. - Eğer harcama işlemi kullanıcı onayında ise harcama iptal edilir ve harcama işleminin `status` değeri `cancel` olarak değişir. - Eğer harcama işlemi `complete` durumda ise harcama tutarı kullanıcıya iade edilir ve harcama işleminin `status` değeri `complete` olarak kalır. ### Request Body - `payment_id` (integer, zorunlu): Harcama İşlem ID (ornek: 1) ### Response 200 - `data` (object): - `payment_id` (integer): Harcama İşlem ID (ornek: 1) - `wallet_id` (integer): Harcama Cüzdan ID (ornek: 1) - `user_id` (integer): Harcama Kullanıcı ID (ornek: 1) - `user_mapping_id` (string): Kullanıcıya ait waas linkleme id değeri. (Iframe açma, harcama gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `company_id` (integer): Harcama Şirket ID (ornek: 1) - `branch_id` (integer): Harcama Şube ID (ornek: 1) - `cashier_id` (integer): Harcama Kasiyer ID (ornek: 1) - `reference_code` (integer): 6 Haneli Harcama Referans Kodu (ornek: 123456) - `order_id` (integer): Harcama Unique Sipariş ID (ornek: 1305549790) - `price` (number): Harcama İşlem Tutarı (ornek: 1) - `paid_price` (number): Harcanan İşlem Tutarı (ornek: 1) - `price_show` (string): Harcama İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `paid_price_show` (string): Harcanan İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `point` (number): Harcama Puan Tutarı (ornek: 1) - `point_show` (string): Harcama Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `final_total` (number): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı) (ornek: 1) - `final_total_show` (string): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı)(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discounted_total_amount` (number): İndirimli Toplam Tutar (ornek: 1) - `discounted_total_amount_show` (string): İndirimli Toplam Tutar(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discount_point` (number): İndirim Puan Tutarı (ornek: 0) - `discount_point_show` (string): İndirim Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `discount_percent` (number): İndirim Yüzdesi (ornek: 0) - `refund_amount` (number): İade Tutarı (ornek: 0) - `status` (string): Harcama Durumu [create, approval, approved, no_balance, reject, expire, complete, service_error] (ornek: "approved") - `status_translate` (string): Harcama Durumu(Dile Göre Çevrilmiş) [Oluşturuldu, Onayda, Onaylandı, Limit Yetersiz, Reddedildi, Süresi Doldu, Tamamlandı, Servis Hatası] (ornek: "Onaylandı") - `gateway` (string): Harcama Geçidi [eftpos, terminal, static_qr, tag_qr, kerzz_pos, tap_card, gizmo, iap] (ornek: "terminal") - `is_shared_wallet` (boolean): Harcamanın Paylaşılan Cüzdan ile Yapılıp Yapılmadığını Belirtir - `wallet_share_id` (integer): Paylaşılan Cüzdan ID - `user_fillable_point` (boolean): Kullanıcı Harcama İşleminde Puan Tutarını Belirleyebilir - `wallet_share` (object): Cüzdan Paylaşımı - `description` (string): Açıklama ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Read QR - Collect (https://docs.altpay.dev/payment/(read-qr)/payment-collect) **POST** `/integration/payment/collect` - Collect servisi, harcama işlemi tutarının belirlenmesi için kullanılır. - Firma kullanıcının Macellan SuperApp mobil uygulamasından oluşturduğu QR kod veya 6 haneli referans koduyla birlikte harcama tutarını servise ileterek bu servisi kullanır. - Servis başarılı bir şekilde çağrıldıktan sonra kullanıcı harcama özet ve onay ekranına yönlendirilir. ### Extra Bilgiler - `external_id` alanı opsiyoneldir. Genellikle ödemeye ait sipariş numarası gibi harici sistem ID'si burada gönderilir; işlemleri kolayca takip etmenize yardımcı olur. ### Ürün Listesi `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. Bu bilgiler raporlama ve analiz amaçlı kullanılır. Ürün listesi gönderildiğinde: * Her ürün için `price` ve `quantity` alanları birlikte zorunludur * Her ürünün `total_price` değeri, `price * quantity` ile eşleşmelidir * Tüm ürünlerin `total_price` toplamı, harcama tutarı `price` ile eşleşmelidir ### Request Body - `price` (number, zorunlu): Harcama İşlem Tutarı (ornek: 1.23) - `reference_code` (integer, zorunlu): 6 Haneli Harcama Referans Kodu (ornek: 123456) - `branch_code` (string): Tek Bir Token İle Entegrasyon Sağlandığında Kullanılan Şube Kodu (ornek: "Test-123") - `external_id` (string): Harici sistem ID değeri (ornek: "EXT-12345") - `product_list` (array): Ürün listesi (ornek: [{"item_id":1,"name":"Ayran","category_name":"İçecekler","price":20,"quantity":2,"total_price":40}]) - `item_id` (integer): Ürün ID (ornek: 1) - `name` (string): Ürün adı (ornek: "Ayran") - `category_name` (string): Kategori adı (ornek: "İçecekler") - `price` (number): Birim fiyat (quantity ile birlikte zorunlu) (ornek: 20) - `quantity` (integer): Miktar (price ile birlikte zorunlu) (ornek: 2) - `total_price` (number): Toplam fiyat (price ve quantity varsa zorunlu) (ornek: 40) ### Response 200 - `data` (object): - `payment_id` (integer): Harcama İşlem ID (ornek: 1) - `wallet_id` (integer): Harcama Cüzdan ID (ornek: 1) - `user_id` (integer): Harcama Kullanıcı ID (ornek: 1) - `user_mapping_id` (string): Kullanıcıya ait waas linkleme id değeri. (Iframe açma, harcama gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `company_id` (integer): Harcama Şirket ID (ornek: 1) - `branch_id` (integer): Harcama Şube ID (ornek: 1) - `cashier_id` (integer): Harcama Kasiyer ID (ornek: 1) - `reference_code` (integer): 6 Haneli Harcama Referans Kodu (ornek: 123456) - `order_id` (integer): Harcama Unique Sipariş ID (ornek: 1305549790) - `price` (number): Harcama İşlem Tutarı (ornek: 1) - `paid_price` (number): Harcanan İşlem Tutarı (ornek: 1) - `price_show` (string): Harcama İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `paid_price_show` (string): Harcanan İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `point` (number): Harcama Puan Tutarı (ornek: 1) - `point_show` (string): Harcama Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `final_total` (number): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı) (ornek: 1) - `final_total_show` (string): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı)(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discounted_total_amount` (number): İndirimli Toplam Tutar (ornek: 1) - `discounted_total_amount_show` (string): İndirimli Toplam Tutar(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discount_point` (number): İndirim Puan Tutarı (ornek: 0) - `discount_point_show` (string): İndirim Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `discount_percent` (number): İndirim Yüzdesi (ornek: 0) - `refund_amount` (number): İade Tutarı (ornek: 0) - `status` (string): Harcama Durumu [create, approval, approved, no_balance, reject, expire, complete, service_error] (ornek: "approved") - `status_translate` (string): Harcama Durumu(Dile Göre Çevrilmiş) [Oluşturuldu, Onayda, Onaylandı, Limit Yetersiz, Reddedildi, Süresi Doldu, Tamamlandı, Servis Hatası] (ornek: "Onaylandı") - `gateway` (string): Harcama Geçidi [eftpos, terminal, static_qr, tag_qr, kerzz_pos, tap_card, gizmo, iap] (ornek: "terminal") - `is_shared_wallet` (boolean): Harcamanın Paylaşılan Cüzdan ile Yapılıp Yapılmadığını Belirtir - `wallet_share_id` (integer): Paylaşılan Cüzdan ID - `user_fillable_point` (boolean): Kullanıcı Harcama İşleminde Puan Tutarını Belirleyebilir - `wallet_share` (object): Cüzdan Paylaşımı - `description` (string): Açıklama ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Read QR - Complete (https://docs.altpay.dev/payment/(read-qr)/payment-complete) **POST** `/integration/payment/complete` - Complete servisi, harcama işleminin son adımıdır ve işlemi tamamlamak için kullanılır. - Kullanıcı harcama işlemi onayladıktan sonra bu servis çağrılmalıdır. - Bu servis çağrılmadığı takdirde kullanıcının bakiyesinden harcama işlem tutarı düşülmez. ### Request Body - `payment_id` (integer, zorunlu): Harcama İşlem ID (ornek: 1) ### Response 200 - `data` (object): - `payment_id` (integer): Harcama İşlem ID (ornek: 1) - `wallet_id` (integer): Harcama Cüzdan ID (ornek: 1) - `user_id` (integer): Harcama Kullanıcı ID (ornek: 1) - `user_mapping_id` (string): Kullanıcıya ait waas linkleme id değeri. (Iframe açma, harcama gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `company_id` (integer): Harcama Şirket ID (ornek: 1) - `branch_id` (integer): Harcama Şube ID (ornek: 1) - `cashier_id` (integer): Harcama Kasiyer ID (ornek: 1) - `reference_code` (integer): 6 Haneli Harcama Referans Kodu (ornek: 123456) - `order_id` (integer): Harcama Unique Sipariş ID (ornek: 1305549790) - `price` (number): Harcama İşlem Tutarı (ornek: 1) - `paid_price` (number): Harcanan İşlem Tutarı (ornek: 1) - `price_show` (string): Harcama İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `paid_price_show` (string): Harcanan İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `point` (number): Harcama Puan Tutarı (ornek: 1) - `point_show` (string): Harcama Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `final_total` (number): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı) (ornek: 1) - `final_total_show` (string): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı)(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discounted_total_amount` (number): İndirimli Toplam Tutar (ornek: 1) - `discounted_total_amount_show` (string): İndirimli Toplam Tutar(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discount_point` (number): İndirim Puan Tutarı (ornek: 0) - `discount_point_show` (string): İndirim Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `discount_percent` (number): İndirim Yüzdesi (ornek: 0) - `refund_amount` (number): İade Tutarı (ornek: 0) - `status` (string): Harcama Durumu [create, approval, approved, no_balance, reject, expire, complete, service_error] (ornek: "approved") - `status_translate` (string): Harcama Durumu(Dile Göre Çevrilmiş) [Oluşturuldu, Onayda, Onaylandı, Limit Yetersiz, Reddedildi, Süresi Doldu, Tamamlandı, Servis Hatası] (ornek: "Onaylandı") - `gateway` (string): Harcama Geçidi [eftpos, terminal, static_qr, tag_qr, kerzz_pos, tap_card, gizmo, iap] (ornek: "terminal") - `is_shared_wallet` (boolean): Harcamanın Paylaşılan Cüzdan ile Yapılıp Yapılmadığını Belirtir - `wallet_share_id` (integer): Paylaşılan Cüzdan ID - `user_fillable_point` (boolean): Kullanıcı Harcama İşleminde Puan Tutarını Belirleyebilir - `wallet_share` (object): Cüzdan Paylaşımı - `description` (string): Açıklama ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Read QR - Send Again Approval (Optional) (https://docs.altpay.dev/payment/(read-qr)/payment-send-again-approval) **POST** `/integration/payment/send-again-approval` - Send Again Approval servisi, eğer kullanıcı özet ve onay ekranına yönlendirilmezse, bu ekrana tekrar yönlendirmek için kullanılır. ### Request Body - `payment_id` (integer, zorunlu): Harcama İşlem ID (ornek: 1) ### Response 200 - `data` (object): - `success` (boolean): ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Read QR - Status (https://docs.altpay.dev/payment/(read-qr)/payment-status) **GET** `/integration/payment/status` - Status servisi, harcama işleminin durumunu sorgulamak için kullanılır. - Firma, belirli aralıklarla harcama işleminin hangi durumda olduğunu sorgular. - Eğer harcama işlemi `approved` durumunda ise firma, harcama işlemini tamamlamak için [Complete](/payment/payment-complete) servisine istek gönderir. `no_balance`, `reject` ve `expire` durumları için firma, harcama işlemini sonlandırmalıdır. - İsteğe bağlı olarak `payment_id` yada `order_id` ile sorgulama yapabilirsiniz. ### Parametreler - `payment_id` (integer, query): Harcama ID numarası - `order_id` (integer, query): Harcama ID numarası ### Response 200 - `data` (object): - `payment_id` (integer): Harcama İşlem ID (ornek: 1) - `wallet_id` (integer): Harcama Cüzdan ID (ornek: 1) - `user_id` (integer): Harcama Kullanıcı ID (ornek: 1) - `user_mapping_id` (string): Kullanıcıya ait waas linkleme id değeri. (Iframe açma, harcama gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `company_id` (integer): Harcama Şirket ID (ornek: 1) - `branch_id` (integer): Harcama Şube ID (ornek: 1) - `cashier_id` (integer): Harcama Kasiyer ID (ornek: 1) - `reference_code` (integer): 6 Haneli Harcama Referans Kodu (ornek: 123456) - `order_id` (integer): Harcama Unique Sipariş ID (ornek: 1305549790) - `price` (number): Harcama İşlem Tutarı (ornek: 1) - `paid_price` (number): Harcanan İşlem Tutarı (ornek: 1) - `price_show` (string): Harcama İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `paid_price_show` (string): Harcanan İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "1,00") - `point` (number): Harcama Puan Tutarı (ornek: 1) - `point_show` (string): Harcama Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `final_total` (number): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı) (ornek: 1) - `final_total_show` (string): Harcama Toplam Tutarı(Puan Tutarı + Harcama Tutarı)(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discounted_total_amount` (number): İndirimli Toplam Tutar (ornek: 1) - `discounted_total_amount_show` (string): İndirimli Toplam Tutar(Para Birimine Göre Formatlanır) (ornek: "1,00") - `discount_point` (number): İndirim Puan Tutarı (ornek: 0) - `discount_point_show` (string): İndirim Puan Tutarı(Para Birimine Göre Formatlanır) (ornek: "0,00") - `discount_percent` (number): İndirim Yüzdesi (ornek: 0) - `refund_amount` (number): İade Tutarı (ornek: 0) - `status` (string): Harcama Durumu [create, approval, approved, no_balance, reject, expire, complete, service_error] (ornek: "approved") - `status_translate` (string): Harcama Durumu(Dile Göre Çevrilmiş) [Oluşturuldu, Onayda, Onaylandı, Limit Yetersiz, Reddedildi, Süresi Doldu, Tamamlandı, Servis Hatası] (ornek: "Onaylandı") - `gateway` (string): Harcama Geçidi [eftpos, terminal, static_qr, tag_qr, kerzz_pos, tap_card, gizmo, iap] (ornek: "terminal") - `is_shared_wallet` (boolean): Harcamanın Paylaşılan Cüzdan ile Yapılıp Yapılmadığını Belirtir - `wallet_share_id` (integer): Paylaşılan Cüzdan ID - `user_fillable_point` (boolean): Kullanıcı Harcama İşleminde Puan Tutarını Belirleyebilir - `wallet_share` (object): Cüzdan Paylaşımı - `description` (string): Açıklama ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Ödeme İade Servisi (https://docs.altpay.dev/payment/refund) Ödeme iade servisi Macellan SuperApp kullanıcılarının yaptıkları ödeme işleminin iadesine olanak sağlayan servistir. Entegratör firma ödeme iade servisinde firmaya ait bütün iade isteklerini görüntüleyebilir. Kullanıcı, mobil uygulama üzerinden iade talebinde bulunur. Entegratör firma kullanıcıdan aldığı referans koduyla veya listeden seçtiği ID ile iade talebinin detayını görüntüleyebilir ve işlemi onaylayarak ya da reddederek sonuçlandırır. ### İade İşleminin Durumları ve Açıklamaları | **Durum** | **Açıklama** | |:---------:|:---------------------------------------| | open | İade talebi alındı, onay bekliyor. | | refund | İade edildi. | | close | İade talebi reddedildi veya kapatıldı. | --- # Nakit Yükleme (https://docs.altpay.dev/cash-deposit) Nakit Yükleme servisi Macellan SuperApp kullanıcılarının sahip olduğu dijital cüzdana bakiye yüklemeye olanak sağlayan servistir. Nakit Yükleme servisi temel olarak 2 akışa sahiptir. Bunlar; ### 1) QR'ın kullanıcı tarafından oluşturulduğu akış Kullanıcı, nakit yükleme yapmak için Macellan SuperApp mobil uygulamasındaki dijital cüzdanıyla birlikte 6 haneli referans kodunu içeren QR Kod oluşturur. Entegratör firma, bu QR kodunu okuyarak veya 6 haneli referans kodunu kullanarak nakit yükleme yapılacak tutarı bu servise iletir. Servis, gerekli kontrolleri yaptıktan sonra mobil uygulamada kullanıcıya yükleme onay ve özet ekranlarını gösterir. Bu sırada entegratör firma, belirli aralıklarla yükleme işleminin durumunu kontrol eder ve duruma bağlı olarak işlemi sonlandırır. ### 2) QR'ın entegratör firma tarafından oluşturulduğu akış Entegratör firma, nakit yükleme yapılacak tutarı servise iletir. Servisten dönen referans kod değeri ile QR kod oluşturur. Kullanıcı Macellan SuperApp mobil uygulamasındaki cüzdanı ile bu QR kodu okur veya 6 haneli referans kodu yazarak servise iletir. Servis gerekli kontrolleri yaptıktan sonra mobil uygulamada kullanıcıya yükleme onay ve özet ekranlarını gösterir. Bu sırada entegratör firma, belirli aralıklarla yükleme işleminin durumunu kontrol eder ve duruma bağlı olarak işlemi sonlandırır. ### Nakit Yükleme İşleminin Durumları ve Açıklamaları | **Durum** | **Açıklama** | |:---------:|:------------------------------------------------------| | create | Nakit Yükleme işlemi oluşturuldu. | | approval | Kullanıcı onayı bekleniyor. | | reject | Kullanıcı nakit yükleme işlemini reddetti. | | expire | Nakit Yükleme işleminin süresi doldu. | | success | Nakit Yükleme işlemi başarılı bir şekilde tamamlandı. | --- # Generate QR - Generate Qr (https://docs.altpay.dev/cash-deposit/(generate-qr)/cash-deposit-generate-qr) **POST** `/integration/deposit/cash/generate-qr` - Generate Qr Servisi, yükleme işlemlerini oluşturmak amacıyla kullanılır. - İşlem sonucunda dönen referans kodu, Macellan SuperApp kullanıcısına iletilir ve bu referans kodu ya da oluşturulan QR kodu kullanılarak işlem devam ettirilebilir. - QR kodun süresi 120 saniyedir. - İade işlemi için nakit yükleme servisinin kullanılacağı durumlarda `is_apply_campaigns` değeri `false` olarak gönderilmeli ve yapılan nakit yükleme işlemi için kullanıcının kampanyalardan yararlanması engellenmelidir. Eğer hiç bir değer göndermezseniz `true` olarak setlenecektir. ### Request Body - `amount` (number, zorunlu): Yükleme İşlem Tutarı (ornek: 1.23) - `branch_code` (string): Tek Bir Token İle Entegrasyon Sağlandığında Kullanılan Şube Kodu (ornek: "Test-123") - `is_apply_campaigns` (boolean): Bu parametre hiç gönderilmezse default `true` olarak setlenecektir. İade için yapılan nakit yüklemelerde `false` olarak gönderilmelidir. ### Response 200 - `data` (object): - `id` (integer): Yükleme İşlem ID (ornek: 1) - `reference_code` (integer): 6 Haneli Yükleme Referans Kodu (ornek: 123456) - `qr_code` (string): Yükleme İşlemi İçin Oluşturulacak QR Kod Değeri (ornek: "ALT-123456-PAY") - `expires_at` (string): Ödeme İşleminin Süresinin Dolacağı Tarih - `server_time` (string): Sunucu Zamanı ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Read QR - Read QR (https://docs.altpay.dev/cash-deposit/(read-qr)/cash-deposit-read-qr) **POST** `/integration/deposit/cash/read-qr` - Read QR servisi, yükleme işlemi tutarının belirlenmesi için kullanılır. - Firma kullanıcının Macellan SuperApp mobil uygulamasından oluşturduğu QR kod veya 6 haneli referans koduyla birlikte yükleme tutarını servise ileterek bu servisi kullanır. - Servis başarılı bir şekilde çağrıldıktan sonra kullanıcı yükleme özet ve onay ekranına yönlendirilir. - İade işlemi için nakit yükleme servisinin kullanılacağı durumlarda `is_apply_campaigns` değeri `false` olarak gönderilmeli ve yapılan nakit yükleme işlemi için kullanıcının kampanyalardan yararlanması engellenmelidir. Eğer hiç bir değer göndermezseniz `true` olarak setlenecektir. ### Request Body - `amount` (number, zorunlu): Yükleme İşlem Tutarı (ornek: 1.23) - `reference_code` (integer, zorunlu): 6 Haneli Yükleme Referans Kodu (ornek: 123456) - `branch_code` (string): Tek Bir Token İle Entegrasyon Sağlandığında Kullanılan Şube Kodu (ornek: "Test-123") - `is_apply_campaigns` (boolean): Bu parametre hiç gönderilmezse default `true` olarak setlenecektir. İade için yapılan nakit yüklemelerde `false` olarak gönderilmelidir. ### Response 200 - `data` (object): - `id` (integer): Yükleme İşlem ID (ornek: 1) - `wallet_id` (integer): Yükleme Cüzdan ID (ornek: 1) - `reference_code` (integer): 6 Haneli Yükleme Referans Kodu (ornek: 123456) - `qr_code` (string): Yükleme İşlemi İçin Oluşturulacak QR Kod Değeri (ornek: "ALT-123456-PAY") - `status` (string): [create, approval, success, reject, expire] - `status_translate` (string): [Oluşturuldu, Onayda, Başarılı, Reddedildi, Süresi Doldu] - `method` (string): Yükleme metodu [cash, credit_card] (ornek: "cash") - `amount` (number): Ödeme İşlem Tutarı (ornek: 1.23) - `amount_show` (string): Ödeme İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "20,00") - `created_at` (string): Ödeme İşlemi Oluşturulma Tarihi - `completed_at` (string): Ödeme İşlemi Tamamlanma Tarihi - `expires_at` (string): Ödeme İşleminin Süresinin Dolacağı Tarih ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Read QR - Send Again Approval(Opsiyonel) (https://docs.altpay.dev/cash-deposit/(read-qr)/cash-deposit-send-again-approval) **POST** `/integration/deposit/cash/send-again-approval` - Send Again Approval servisi, eğer kullanıcı özet ve onay ekranına yönlendirilmezse, bu ekrana tekrar yönlendirmek için kullanılır. ### Request Body - `id` (integer, zorunlu): (ornek: 1) ### Response 200 - `data` (object): - `success` (boolean): ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Read QR - Status (https://docs.altpay.dev/cash-deposit/(read-qr)/cash-deposit-status) **GET** `/integration/deposit/cash/status` - Status servisi, yükleme işleminin durumunu sorgulamak için kullanılır. - Firma, belirli aralıklarla yükleme işleminin hangi durumda olduğunu sorgular. - Eğer ödeme işlemi `success` durumunda ise firma, ödeme işlemini tamamlanmış olarak kabul etmelidir. - `reject` ve `expire` durumları için firma, yükleme işlemini sonlandırmalıdır. ### Parametreler - `id` (integer, zorunlu, query): Yükleme İşlem ID (ornek: 1) ### Response 200 - `data` (object): - `id` (integer): Yükleme İşlem ID (ornek: 1) - `wallet_id` (integer): Yükleme Cüzdan ID (ornek: 1) - `reference_code` (integer): 6 Haneli Yükleme Referans Kodu (ornek: 123456) - `qr_code` (string): Yükleme İşlemi İçin Oluşturulacak QR Kod Değeri (ornek: "ALT-123456-PAY") - `status` (string): [create, approval, success, reject, expire] - `status_translate` (string): [Oluşturuldu, Onayda, Başarılı, Reddedildi, Süresi Doldu] - `method` (string): Yükleme metodu [cash, credit_card] (ornek: "cash") - `amount` (number): Ödeme İşlem Tutarı (ornek: 1.23) - `amount_show` (string): Ödeme İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "20,00") - `created_at` (string): Ödeme İşlemi Oluşturulma Tarihi - `completed_at` (string): Ödeme İşlemi Tamamlanma Tarihi - `expires_at` (string): Ödeme İşleminin Süresinin Dolacağı Tarih ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Direct (https://docs.altpay.dev/cash-deposit/cash-deposit-direct) **POST** `/integration/deposit/cash/direct` - Direct servisi, entegratör firmanın, kullanıcıdan herhangi bir onay almadan kullanıcının cüzdanına nakit yükleme yapmasını sağlar. - İade işlemi için nakit yükleme servisinin kullanılacağı durumlarda `is_apply_campaigns` değeri `false` olarak gönderilmeli ve yapılan nakit yükleme işlemi için kullanıcının kampanyalardan yararlanması engellenmelidir. Eğer hiç bir değer göndermezseniz `true` olarak setlenecektir. ### Request Body - `wallet_id` (integer, zorunlu): Yükleme Yapılacak Cüzdan ID (ornek: 12) - `amount` (number, zorunlu): Yükleme İşlem Tutarı (ornek: 1.23) - `branch_code` (string): Tek Bir Token İle Entegrasyon Sağlandığında Kullanılan Şube Kodu (ornek: "Test-123") - `is_apply_campaigns` (boolean): Bu parametre hiç gönderilmezse default `true` olarak setlenecektir. İade için yapılan nakit yüklemelerde `false` olarak gönderilmelidir. - `order_id` (string): Bu parametre sipariş numarası atamak için kullanılır gönderilmediği takdirde sistem tarafından otomatik sipariş numarası atanır. (ornek: "1842515611") - `method` (string): Bu parametre yükleme metodunu belirlemek için kullanılır. Nakit için "cash", kredi kartı için "credit_card". Boş gönderildiği takdirde, sistem bu değeri "cash" olarak ele alacaktır. [cash, credit_card] (ornek: "cash") - `point` (number): Puan Tutarı (ornek: 1.23) - `point_expire_date` (string): Puan Son Kullanma Tarihi (ornek: "2025-12-31") ### Response 200 - `data` (object): - `id` (integer): Yükleme İşlem ID (ornek: 1) - `wallet_id` (integer): Yükleme Cüzdan ID (ornek: 1) - `reference_code` (integer): 6 Haneli Yükleme Referans Kodu (ornek: 123456) - `qr_code` (string): Yükleme İşlemi İçin Oluşturulacak QR Kod Değeri (ornek: "ALT-123456-PAY") - `status` (string): [create, approval, success, reject, expire] - `status_translate` (string): [Oluşturuldu, Onayda, Başarılı, Reddedildi, Süresi Doldu] - `method` (string): Yükleme metodu [cash, credit_card] (ornek: "cash") - `amount` (number): Ödeme İşlem Tutarı (ornek: 1.23) - `amount_show` (string): Ödeme İşlem Tutarı(Para Birimine Göre Formatlanır) (ornek: "20,00") - `created_at` (string): Ödeme İşlemi Oluşturulma Tarihi - `completed_at` (string): Ödeme İşlemi Tamamlanma Tarihi - `expires_at` (string): Ödeme İşleminin Süresinin Dolacağı Tarih ### Response 401 - `message` (string): message (ornek: "Unauthenticated") ### Response 403 - `message` (string): message (ornek: "İşlemi yapmak için yetkili değilsiniz.") --- # Status (https://docs.altpay.dev/qr/qr-status) **GET** `/integration/qr/status` --- # Bakiye Geçmişi Listesi (https://docs.altpay.dev/wallet/balance-history-list) **GET** `/integration/wallet/balance-history/list` --- # Telefon Numarasına Göre (https://docs.altpay.dev/wallet/get-by-phone) **GET** `/integration/wallet/by-phone/{phone}` - İlgili telefon numarasına ait cüzdan bilgisi verilir. ### Parametreler - `phone` (string, zorunlu, path): [E.164 Format](https://www.twilio.com/docs/glossary/what-e164) (ornek: "905231113344") ### Response 200 - `data` (object): ### Response 404 - `message` (string): --- # Puan Geçmişi Listesi (https://docs.altpay.dev/wallet/point-history-list) **GET** `/integration/wallet/point-history/list` --- # Detay (https://docs.altpay.dev/wallet/wallet-details) **GET** `/integration/wallet/{walletId}/details` --- # Liste (https://docs.altpay.dev/wallet/wallet-list) **GET** `/integration/wallet/list` --- # Yetkili Kullanıcı - Yetkili Kullanıcı Oluştur (https://docs.altpay.dev/user/(yetkili-kullanici)/user-create) **POST** `/integration/user/create` - Kasiyer ve Şube yetkilisi rolünde kullanıcı oluşturmak için kullanılır. - Kasiyer rolünde `branch_codes` alanı sadece bir şube kodu alabilir. - Şube yetkilisi rolünde `branch_codes` alanı birden fazla şube kodu alabilir. ### Request Body - `phone` (string): [E.164 Format](https://www.twilio.com/docs/glossary/what-e164) (ornek: "+905231113344") - `password` (string, zorunlu): (ornek: "test123") - `branch_codes` (array, zorunlu): (ornek: ["Test-123","Test-124"]) - `role` (string, zorunlu): [Branch Admin, Cashier] (ornek: "Branch Admin") - `last_name` (string, zorunlu): (ornek: "Test") - `email` (string, zorunlu): (ornek: "test1@macellan.net") - `first_name` (string, zorunlu): (ornek: "Test") ### Response 200 - `data` (object): --- # Yetkili Kullanıcı - Detay (https://docs.altpay.dev/user/(yetkili-kullanici)/user-me) **GET** `/integration/user/me` - Token'ın bağlı olduğu kullanıcıya ait detaylar görüntülenir. ### Response 200 - `data` (object): --- # Yetkili Kullanıcı - Güncelle (https://docs.altpay.dev/user/(yetkili-kullanici)/user-update) **PUT** `/integration/user/update` - Önceden oluşturulan kullanıcıları güncellemek için kullanılır. - Kasiyer rolünde `branch_codes` alanı sadece bir şube kodu alabilir. - Şube yetkilisi rolünde `branch_codes` alanı birden fazla şube kodu alabilir. ### Request Body - `phone` (string): [E.164 Format](https://www.twilio.com/docs/glossary/what-e164) (ornek: "+905231113344") - `password` (string): (ornek: "test123") - `branch_codes` (array): (ornek: ["Test-123","Test-124"]) - `id` (integer, zorunlu): (ornek: 1) - `role` (string): (ornek: "Branch Admin") - `last_name` (string): (ornek: "Test") - `email` (string): (ornek: "test1@macellan.net") - `first_name` (string): (ornek: "Test") ### Response 200 - `data` (object): - `success` (boolean): --- # Oluştur (https://docs.altpay.dev/user/personal-user-register) **POST** `/integration/user/personal-user/register` - Bu servis, [OTP](/otp/otp-send) işleminden sonra kullanıcıyı oluşturup cüzdan hesabının açılması için kullanılır. ### Request Body - `phone` (string): Kullanıcı telefon bilgisi ([E.164 Format](https://www.twilio.com/docs/glossary/what-e164)) (ornek: "+905231113344") - `email` (string, zorunlu): (ornek: "dev@macellan.app") - `locale` (string): Kullanıcının dil bilgisi [tr, en] (ornek: "tr") - `first_name` (string, zorunlu): Kullanıcı ad bilgisi (ornek: "Macellan") - `last_name` (string, zorunlu): Kullanıcı soyad bilgisi (ornek: "Superapp") - `verify_id` (integer, zorunlu): Telefona ait [OTP Doğrulama](/otp/otp-verify) id bilgisi (ornek: 1) - `subscribe_sms` (boolean): Sms iletişim izni (ornek: false) - `subscribe_email` (boolean): Email iletişim izni (ornek: false) - `id_number` (string): Kimlik Numarası (ornek: "11111111111") - `gender` (string): Cinsiyet [male, female, prefer_not_respond] (ornek: "male") - `birth_date` (string): Doğum Tarihi (ornek: "2000-12-20") - `register_waas` (boolean): Waas'a kayıt işlemi (ornek: false) ### Response 200 - `data` (object): - `user` (object): - `id` (string): Kullanıcının id numarasını belirtir. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `first_name` (string): Kullanıcı adını belirtir. (ornek: "Test") - `last_name` (string): Kullanıcı soyadını belirtir. (ornek: "Test") - `full_name` (string): Kullanıcı ad ve soyad bilgisini belirtir. (ornek: "Test Test") - `email` (string): Kullanıcının e-mail adresini belirtir. (ornek: "test@example.com") - `phone` (string): Kullanıcının telefon numarasını belirtir. (ornek: 905551112233) - `locale` (string): Kullanıcının dil bilgisi (ornek: "tr") - `waas_user_mapping` (object): ### Response 406 - `message` (string): --- # Şirket Detayları (https://docs.altpay.dev/company/company-details) **GET** `/integration/company/details` --- # Oluştur (https://docs.altpay.dev/branch/branch-create) **POST** `/integration/branch/create` - Şube oluşturmak için kullanılır. - Lokasyon bilgisi enlem ve boylam bilgisi arasına virgül konarak gönderilmelidir ('enlem,boylam'). - Code alanı unique bir değer olarak gönderilmelidir. ### Request Body - `phone` (string, zorunlu): [E.164 Format](https://www.twilio.com/docs/glossary/what-e164) (ornek: "+905231113344") - `active` (boolean, zorunlu): (ornek: true) - `location` (string, zorunlu): (ornek: "41.08447542240944, 28.985638326773866") - `open_address` (string, zorunlu): (ornek: "Test open address") - `code` (string, zorunlu): (ornek: "Test-123") - `allow_point_usage` (boolean, zorunlu): (ornek: true) - `description` (string): (ornek: "Test description") - `name` (string, zorunlu): (ornek: "Test Branch") ### Response 200 - `data` (object): - `success` (boolean): --- # Güncelle (https://docs.altpay.dev/branch/branch-update) **PUT** `/integration/branch/update` - Önceden oluşturulan şubeleri güncellemek için kullanılır. - Code alanı güncellenmek istendiğinde mevcut kullanılan `code` alanı aynen gönderilmeli. Güncellenmek istenen `code` değeri ise `updated_code` olarak gönderilmelidir. ### Request Body - `phone` (string): [E.164 Format](https://www.twilio.com/docs/glossary/what-e164) (ornek: "+905231113344") - `active` (boolean): (ornek: true) - `location` (string): (ornek: "41.08447542240944, 28.985638326773866") - `open_address` (string): (ornek: "Test open address") - `code` (string, zorunlu): (ornek: "Test-123") - `updated_code` (string): (ornek: "New-Code-123") - `allow_point_usage` (boolean): (ornek: true) - `description` (string): (ornek: "Test description") - `name` (string): (ornek: "Test Branch") ### Response 200 - `data` (object): - `success` (boolean): --- # Bakiye Sorgulama (https://docs.altpay.dev/tap-card/balance-inquiry) **POST** `/integration/tap-card/balance-inquiry` --- # Kart ile Ödeme (https://docs.altpay.dev/tap-card/pay) **POST** `/integration/tap-card/pay` --- # Bakiye Sorgulama (https://docs.altpay.dev/box-office/balance-inquiry) **POST** `/integration/box-office/balance-inquiry` --- # Bakiye Yükleme (https://docs.altpay.dev/box-office/top-up) **POST** `/integration/box-office/top-up` --- # Kart Kaydı ve Bakiye Yükleme (https://docs.altpay.dev/box-office/verified-top-up) **POST** `/integration/box-office/verified-top-up` --- # Gönderim (https://docs.altpay.dev/otp/otp-send) **POST** `/integration/otp/send` Belirtilen telefon numarasına, OTP gönderimini sağlar. **Not:** Development ortamında [doğrulamayı](/otp/otp-verify) başarılı şekilde çalıştırmanız için response da code bilgisi gönderilmektedir. ### Request Body - `phone` (string, zorunlu): Kullanıcı telefon bilgisi ([E.164 Format](https://www.twilio.com/docs/glossary/what-e164)) (ornek: "+905231113344") - `gateway` (string, zorunlu): OTP gönderim tipi [sms, whatsapp] (ornek: "sms") - `app_hash` (string): Gönderilecek sms doğrulama koduna mobil uygulamalardan erişebilmek için kullanılabilir. (Mesaj içeriğine app_hash değeri eklenir) (ornek: null) ### Response 200 - `data` (object): - `expires_at` (string): OTP nin geçerlilik süresi - `server_time` (string): Sunucu tarihi - `code` (string): OTP doğrulama kodu. Bu değer sadece development ortamında gönderilmektedir. (ornek: 123456) --- # Doğrulama (https://docs.altpay.dev/otp/otp-verify) **POST** `/integration/otp/verify` Gönderim yapılan OTP yi doğrulama işlemi için kullanılmaktadır. Bu servisten dönen ``verify_id`` değeri, OTP doğrulama isteyen servislerde kullanılabilir. ### Request Body ### Response 200 - `data` (object): - `verify_id` (integer): OTP doğrulamanız için üretilmiş kimliktir. Bu değer, verify_id isteyen servislerde kullanılmalıdır. (ornek: 1) ### Response 403 - `message` (string): ### Response 406 - `message` (string): --- # Wallet As A Service (https://docs.altpay.dev/waas) Macellan WaaS (Wallet As A Service), sistemlerinize cüzdan altyapısı sağlamaktadır. [Başlarken](/) bölümünde belirtildiği gibi tüm istekler size iletilen Token ile yapılmalıdır. ## Wallet As A Service Kullanım Yöntemleri #### 1) iFrame ile Kullanım Bu yöntemde Macellan SuperApp, uygulamanız içerisinde bir web linkinde açılır ve kullanıcının işlemleri gerçekleştirmesi sağlanır. Bu sayede kullanıcılarınız, cüzdan fonksiyonlarını uygulamanızdan çıkmadan kullanabilir. ##### PostMessage İletişimi iFrame içindeki işlemler tamamlandığında, uygulamanıza aşağıdaki olaylar PostMessage olarak iletilir: | DATA | Açıklama | | ---------------------------------------------------------------- | -------------------------------------------------- | | `{ success: false, event: 'CANCEL_PAYMENT_USER' }` | Kullanıcı harcama işlemini iptal ettiğinde | | `{ success: false, event: 'CANCEL_PAYMENT_OPERATOR' }` | Yetkili harcama işlemini iptal ettiğinde | | `{ success: true, event: 'COMPLETE_PAYMENT' }` | Harcama işlemi başarıyla tamamlandığında | | `{ success: true, event: 'COMPLETE_DEPOSIT' }` | Bakiye yükleme işlemi başarıyla tamamlandığında | | `{ success: false, event: 'CANCEL_DEPOSIT_USER' }` | Kullanıcı bakiye yükleme işlemini iptal ettiğinde | | `{ success: false, event: 'FAIL_DEPOSIT' }` | Bakiye yükleme işlemi esnasında hata oluştuğunda | | `{ success: true, event: 'RETURN_TO_SITE' }` | Web'de menüdeki "Siteye Dön" butonuna basıldığında | | `{ success: true, event: 'OPEN_URL', data: { url: value } }` | Web'de kampanya gibi bileşenler tıklandığında | | `{ success: false, event: 'INVALID_QR', data: { message } }` | QR içeriği çözümlenemediğinde veya geçersiz olduğunda | ```javascript // PostMessage dinleyici örneği window.addEventListener('message', function (event) { if (!event.data?.message) return const payload = JSON.parse(event.data.message) switch (payload.event) { case 'CANCEL_PAYMENT_USER': case 'CANCEL_PAYMENT_OPERATOR': // Harcama iptal edildi işlemleri break case 'COMPLETE_PAYMENT': // Harcama tamamlandı işlemleri break case 'COMPLETE_DEPOSIT': // Bakiye yükleme tamamlandı işlemleri break case 'CANCEL_DEPOSIT_USER': case 'FAIL_DEPOSIT': // Bakiye yükleme başarısız işlemleri break case 'INVALID_QR': // payload.data.message ile hata sebebine erişilebilir break } }) ``` #### 2) iFramesiz Kullanım Bu yöntemde, kullanıcı linkleme ve oluşturma gibi cüzdan fonksiyonu adımları sizin tarafınızdan yapılması gereken entegrasyonlarla gerçekleştirilir. Kısacası, WaaS entegrasyonundaki bazı işlemleri kendiniz oluşturmalısınız. ## Cüzdan Uygulamasının Açılması ## Bakiye Yükleme İçin Test Kart Bilgileri | Banka | Kart No | Son K.Tarihi | CVV | 3DS Şifre | Sanal Pos | | ---------- | ------------------- | ------------ | --- | --------- | ----------- | | AKBANK | 4748 5447 4854 4745 | 12/2023 | 000 | a | | | AKBANK | 4355 0843 5508 4358 | 12/2023 | 000 | a | | | AKBANK | 5571 1355 7113 5575 | 12/2023 | 000 | a | | | AKBANK | 4355 0843 5508 4358 | 12/2026 | 000 | a | | | FINANSBANK | 4155 6501 0041 6111 | 01/2050 | 715 | | | | FINANSBANK | 4022 7801 0794 7023 | 01/2041 | 759 | | | | FINANSBANK | 4022 7801 9828 3155 | 01/2050 | 105 | | | | AKBANK | 5571 1355 7113 5575 | 12/2026 | 000 | a | Param | | ISBANK | 4508 0345 0803 4509 | 12/2026 | 000 | a | Param | | KUVEYTTURK | 5188 9619 3919 2544 | 06/2025 | 929 | 123456 | Kuveyt Turk | | PAYTR | 4355 0843 5508 4358 | 12/2030 | 000 | | PayTR | | PAYTR | 5406 6754 0667 5403 | 12/2030 | 000 | | PayTR | | PAYTR | 9792 0303 9444 0796 | 12/2030 | 000 | | PayTR | | SIPAY | 4508 0345 0803 4509 | 12/2026 | 000 | a | SIPAY | | SIPAY | 5406 6754 0667 5403 | 12/2026 | 000 | a | SIPAY | | SIPAY | 4048 0950 1085 7528 | 05/2028 | 000 | 34020 | SIPAY | | SIPAY | 4506 3470 2652 3718 | 12/2025 | 000 | 34020 | SIPAY | | SIPAY | 5400 6170 0000 4909 | 09/2026 | 000 | 34020 | SIPAY | --- # Cüzdan - Sözleşme (https://docs.altpay.dev/waas/(cuzdan)/waas-agreement) **GET** `/waas/integration/wallets/agreement` - Bu servis ile Macellan SuperApp panelinden hazırlanan cüzdan sözleşme bilgilerini alabilirsiniz. - Kullanıcı kayıt aşamasında cüzdan sözleşmenizin onaylatılması gerekmektedir. ### Response 200 - `data` (object): - `id` (integer): Sözleşme id bilgisi (ornek: 1) - `html` (string): Sözleşme içeriği ### Response 404 - `message` (string): --- # Cüzdan - İşlem Geçmişi (https://docs.altpay.dev/waas/(cuzdan)/waas-balance-history) **GET** `/waas/integration/wallets/{userMappingId}/balance-histories` - Bu servis ile cüzdan kullanıcılarınızın işlem geçmişini görüntüleyebilirsiniz. ### Enum Değerleri Ve Açıklamaları #### `type` (İşlem Tipi) | Enum Değeri | Açıklama | |-------------------------|------------------------------| | `top-up` | Bakiye Yükleme | | `capture` | Bakiye Harcama | | `payment_refund` | Harcama İadesi | | `deposit_refund` | Yükleme İadesi | | `cash_deposit_refund` | Nakit Yükleme İadesi |
#### `description` (Bakiye Açıklama) | Enum Değeri | Açıklama | |---------------------------|------------------------------------| | `bkm` | BKM | | `masterpass` | Masterpass | | `masterpass_dp` | Masterpass DP | | `paycell` | Paycell | | `cash` | Nakit | | `turkcell_dcb` | Turkcell DCB | | `united_payment` | United Payment | | `united_payment_dp` | United Payment DP | | `eftpos` | ÖKC (Ödeme Kaydedici) | | `static_qr` | Statik QR | | `tag_qr` | Etiket QR | | `tap_card` | Temassız Kart | | `terminal` | Terminal | | `kerzz_pos` | Kerzz POS | | `simpra_pos` | Simpra POS | | `gizmo` | Gizmo | | `iap` | IAP (In-App Purchase) | | `soft_play` | Soft Play | | `soft_play_time_extension`| Soft Play Süre Uzatma | | `waas` | Waas | | `balance_burn` | Bakiye Yakma | | `order` | Sipariş | | `box_office` | Gişe | ### Parametreler - `userMappingId` (string, zorunlu, path): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `balance_filters[]` (array, query): İşlem tipi filtresi - `description_filters` (array, query): Bakiye açıklama filtresi - `start_date` (string, query): Filtrelemek istenen başlangıç tarihi. - `end_date` (string, query): Filtrelemek istenen bitiş tarihi. - `page` (integer, query): Listelenmek istenen sayfa numarası. ### Response 200 - `data` (array): - `id` (integer): ID (ornek: 1) - `historyable_id` (integer): Geçmiş işlemin id bilgisi (ornek: 1) - `amount` (number): İşlem Tutarı (ornek: 1) - `created_at` (string): - `type` (object): - `description` (object): - `total_earned_points` (number): Kazanılan Puan Tutarı (ornek: 1) - `meta` (object): ### Response 404 - `message` (string): --- # Cüzdan - Puan Özeti (https://docs.altpay.dev/waas/(cuzdan)/waas-point-summary) **GET** `/waas/integration/wallets/{userMappingId}/point-summary` - Bu servis ile cüzdan kullanıcılarınızın toplam puan değerlerini görüntüleyebilirsiniz. - Kullanıcının tüm puan toplarını (amount, balance, spent, expired, revoked) döner. ### Response Alanları | Alan | Açıklama | |-----------------|-------------------------------------------------| | `total_amount` | Toplam kazanılan puan tutarı | | `total_balance` | Toplam kullanılabilir puan tutarı | | `total_spent` | Toplam harcanan puan tutarı | | `total_expired` | Toplam süresi dolmuş puan tutarı | | `total_revoked` | Toplam iptal edilen puan tutarı | ### Parametreler - `userMappingId` (string, zorunlu, path): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") ### Response 200 - `data` (object): Kullanıcının puan özeti bilgisi - `total_amount` (number): Toplam kazanılan puan tutarı (ornek: 150) - `total_balance` (number): Toplam kullanılabilir puan bakiyesi (ornek: 80) - `total_spent` (number): Toplam harcanan puan tutarı (ornek: 50) - `total_expired` (number): Toplam süresi dolmuş puan tutarı (ornek: 15) - `total_revoked` (number): Toplam iptal edilen puan tutarı (ornek: 5) ### Response 404 - `message` (string): (ornek: "Kullanıcı bulunamadı.") --- # Cüzdan - Detay (Toplu) (https://docs.altpay.dev/waas/(cuzdan)/waas-wallet-bulk-details) **POST** `/waas/integration/wallets/bulk` - Bu servis ile birden fazla kullanıcınızın cüzdan bilgilerini tek istekte toplu olarak görüntüleyebilirsiniz. - Tek istekte en fazla **50** adet linkleme id gönderebilirsiniz. - Yanıt, anahtarları gönderdiğiniz linkleme id (`user_mapping_id`) değerleri olan bir nesne olarak döner. - Şirketinize ait olmayan veya bulunamayan linkleme id'ler yanıtta yer almaz. ### Request Body - `user_mapping_ids` (array, zorunlu): Cüzdan bilgisi alınmak istenen kullanıcılara ait linkleme id değerleri. (ornek: ["8b5ac43a-20ce-4987-a739-d8a7ee480eaa","9c6bd54b-31df-5098-b840-e9b8ff591fbb"]) ### Response 200 - `data` (object): --- # Cüzdan - Detay (https://docs.altpay.dev/waas/(cuzdan)/waas-wallet-detail) **GET** `/waas/integration/wallets/{userMappingId}` - Bu servis ile cüzdan uygulaması eşlemesi yapılan kullanıcılarınızın cüzdan bilgilerini görüntüleyebilirsiniz. ### Parametreler - `userMappingId` (string, zorunlu, path): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") ### Response 200 - `data` (object): - `id` (integer): Cüzdan id numarasını gösterir. (ornek: 1) - `visibility` (boolean): Kullanıcının cüzdanı görüntülemek istediğini veya aksini belirtir. - `balance` (number): Cüzdanın kullanılabilir bakiyesini belirtir. (ornek: 1) - `point` (number): Cüzdanın kullanılabilir puanını belirtir. (ornek: 1) - `held_balance` (number): Bloklu bakiye - `held_point` (number): Bloklu puan - `total_held` (number): Toplam bloklu tutar - `company_id` (integer): Cüzdanın bağlı olduğu şirket id numarasını belirtir. (ornek: 1) - `user` (object): Cüzdan sahibinin bilgilerini içerir. - `mapping` (object): - `id` (string): Kullanıcıya ait linkleme id değeri. (Iframe açma, ödeme gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `wallet_id` (integer): Cüzdanın id numarasını belirtir. (ornek: 1) - `is_active` (boolean): Cüzdanın aktif-pasif durumunu belirtir. Pasif cüzdanlar waas uygulamasını kullanamaz. (ornek: true) - `created_at` (string): - `id` (string): Cüzdan sahibinin SuperApp id numarasını belirtir. (ornek: "25809faf-9f21-40c8-bebe-3dd4e343b446") - `first_name` (string): Cüzdan sahibinin adını belirtir. (ornek: "AB****") - `last_name` (string): Cüzdan sahibinin soyadını belirtir. (ornek: "CD****") - `email` (string): Cüzdan sahibinin e-mail adresini belirtir. (ornek: "ab*****@test.com") - `phone` (string): Cüzdan sahibinin telefon numarasını belirtir. (ornek: "90***********") - `locale` (string): Kullanıcının dil bilgisi (ornek: "tr") ### Response 404 - `message` (string): --- # Cüzdan - Puan Geçmişi (https://docs.altpay.dev/waas/(cuzdan)/waas-wallet-point-histories) **GET** `/waas/integration/wallets/{userMappingId}/point-histories` - Bu servis ile cüzdan kullanıcınıza ait puan geçmişini listeleyebilirsiniz. - Opsiyonel tarih filtreleri ile belirli bir dönemdeki puan geçmişi `created_at` alanına göre filtrelenir. - Tarih filtreleri birlikte gönderilmelidir. Sadece `start_date` veya sadece `end_date` gönderilemez. ### Enum Değerleri Ve Açıklamaları #### `point_type` (Puan Tipi) | Enum Değeri | Açıklama | |-------------------------------------|---------------------------------| | `coupon` | Kupon | | `user_coupon` | Kullanıcı Kuponu | | `campaign` | Kampanya | | `payment_discount` | Harcamaya İndirim | | `receivable` | Alacak | | `gift_card` | Hediye Kartı | | `amusement_event` | Eğlence Parkı Etkinliği | | `box_office_predefined_deposit` | Gişe Öntanımlı Yükleme | | `refund` | İade | | `automated_load` | Otomatik Yükleme | | `manual` | Manuel | | `external_point_definition` | Harici Puan Tanımlaması |
#### `point_history_type` (İşlem Tipi) | Enum Değeri | Açıklama | |-----------------|------------------| | `usage` | Harcama | | `load` | Kazanma | | `expire` | Süresi Doldu | | `revoke` | İptal | ### Parametreler - `userMappingId` (string, zorunlu, path): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `start_date` (string, query): Filtrelemek istenen başlangıç tarihi. - `end_date` (string, query): Filtrelemek istenen bitiş tarihi. - `page` (integer, query): Listelenmek istenen sayfa numarası. ### Response 200 - `data` (array): - `id` (integer): ID (ornek: 1) - `user_mapping_id` (string): Kullanıcı mapping ID (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `point_type` (string): Puan Tipi [coupon, user_coupon, campaign, payment_discount, receivable, gift_card, amusement_event, box_office_predefined_deposit, refund, automated_load, manual, external_point_definition] (ornek: "campaign") - `point_history_type` (string): İşlem Tipi [usage, load, expire, revoke] (ornek: "load") - `amount` (number): İşlem Tutarı (ornek: 10) - `external_id` (string): Harici Sistem ID (ornek: "EXT-12345") - `created_at` (string): - `meta` (object): ### Response 404 - `message` (string): (ornek: "Kullanıcı bulunamadı.") --- # Cüzdan - Zamanlanmış Puanlar (https://docs.altpay.dev/waas/(cuzdan)/waas-wallet-scheduled-points) **GET** `/waas/integration/wallets/{userMappingId}/scheduled-points` - Bu servis ile cüzdan kullanıcılarınıza ait zamanlanmış puan tanımlamalarını listeleyebilirsiniz. - Opsiyonel tarih filtreleri ile belirli bir dönemdeki zamanlanmış puanlar `grant_date` alanına göre filtrelenir. - Tarih filtreleri birlikte gönderilmelidir. Sadece `start_date` veya sadece `end_date` gönderilemez. ### Enum Değerleri Ve Açıklamaları #### `status` (Durum) | Enum Değeri | Açıklama | |---------------|------------------| | `waiting` | Beklemede | | `processed` | İşlendi | | `expired` | Süresi Doldu | | `cancelled` | İptal Edildi | ### Parametreler - `userMappingId` (string, zorunlu, path): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `start_date` (string, query): Filtrelemek istenen başlangıç tarihi. - `end_date` (string, query): Filtrelemek istenen bitiş tarihi. - `page` (integer, query): Listelenmek istenen sayfa numarası. ### Response 200 - `data` (array): - `id` (integer): ID (ornek: 1) - `user_mapping_id` (string): Kullanıcı mapping ID (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `title` (string): Zamanlanmış puan başlığı (ornek: "Özel kampanya puanı") - `external_id` (string): Harici sistem ID (ornek: "EXT-12345") - `status` (string): Durum [waiting, processed, expired, cancelled] (ornek: "waiting") - `amount` (number): Puan tutarı (ornek: 100) - `created_at` (string): - `grant_date` (string): Puan verilme tarihi (ornek: "2025-01-15T00:00:00.000000Z") - `expire_date` (string): Puan son kullanma tarihi (ornek: "2025-12-31T00:00:00.000000Z") - `meta` (object): ### Response 404 - `message` (string): (ornek: "Kullanıcı bulunamadı.") --- # Direct Payment - Direct Payment (https://docs.altpay.dev/waas/(direct-payment)/direct-payment) WaaS entegrasyonu ile kullanıcıların cüzdanlarını kullanarak doğrudan ödeme yapma süreci iki aşamada gerçekleştirilir: #### 1) Ödeme Kontrolü: Bu aşamada, kullanıcıların cüzdan bakiyesi ve puan bilgileri kontrol edilir. Sepet veya ödeme aşamalarında, kullanıcı bilgileri ve fiyat bilgisi ile birlikte gönderilen istekler değerlendirilir. Kullanıcının yeterli bakiyesi veya puanı varsa, ödeme yapabileceği bilgisi sağlanır. Eğer kullanıcı Macellan SuperApp ile linklenmemişse, cüzdanı yoksa veya yeterli bakiyesi yoksa, kullanıcı cüzdan uygulamasına yönlendirilir. Kullanıcı eksik olan tutarı yüklediğinde, uygulama `{success: true}` mesajı gönderir ve ödemenin hazır olduğunu belirtir. #### 2) Ödeme Servisi: Bu aşamada, servis kullanılarak kullanıcının cüzdanından belirtilen tutar kadar harcama yapılır. Ödeme işleminin başarılı olması için bu adımın doğru bir şekilde gerçekleştirilmesi gerekmektedir. Bu aşamalar sayesinde, kullanıcılarınızın cüzdan bakiyesi ve ödeme yapma yetkinlikleri kolayca yönetilebilir ve güvenli bir şekilde işlem tamamlanabilir. --- # Direct Payment - Ödeme İade Servisi (https://docs.altpay.dev/waas/(direct-payment)/waas-payment-direct-refund) **POST** `/waas/integration/payments/refunds/direct` - Ödeme yapıldıktan sonra istenilen tutarda iade işlemi yapmak için kullanılır. - [Ödeme Servisi](/waas/waas-payment-make) isteğinden dönen order_id değeri ile işlem gerçekleştirebilir. - İade edilmek istenen tutar en fazla ödeme tutarı + ödeme puan tutarı olabilir. ### Ürün Listesi `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. Bu bilgiler raporlama ve analiz amaçlı kullanılır. Ürün listesi gönderildiğinde: * Her ürün için `price` ve `quantity` alanları birlikte zorunludur * Her ürünün `total_price` değeri, `price * quantity` ile eşleşmelidir * Tüm ürünlerin `total_price` toplamı, ödeme tutarı `price + point` ile eşleşmelidir ### Request Body - `amount` (number, zorunlu): İade Edilmek İstenen Tutar (ornek: 1.23) - `order_id` (integer, zorunlu): Ödeme İşlemi Unique Sipariş ID (ornek: 1131347753) - `comment` (string): Şirket Notu (ornek: "Test") - `product_list` (array): Ürün listesi - `item_id` (integer): Ürün ID (ornek: 1) - `name` (string): Ürün adı (ornek: "Ayran") - `category_name` (string): Kategori adı (ornek: "İçecekler") - `price` (number): Birim fiyat (quantity ile birlikte zorunlu) (ornek: 20) - `quantity` (integer): Miktar (price ile birlikte zorunlu) (ornek: 2) - `total_price` (number): Toplam fiyat (price ve quantity varsa zorunlu) (ornek: 40) ### Response 200 - `data` (object): --- # Direct Payment - Ödeme Servisi (https://docs.altpay.dev/waas/(direct-payment)/waas-payment-make) **POST** `/waas/integration/payments/make` - Ödeme aşamasında kullanıcının cüzdanından belirtilen tutar kadar harcama yapma işlemi için kullanılır. - [Ödeme Kontrolü](/waas/waas-payment-pre-check) isteğinden sonra çalıştırılması gerekmektedir. - Ödeme servisi, 2 farklı şekilde kullanılabilir. Puan tutarının manuel belirlenmesi veya kullanıcıya puan kullanma seçeneğinin seçtirilmesi - **Puan Kullanımının Kullanıcı Tarafından Seçtirilmesi(point_usage kullanımı):** İstekte opsiyonel olarak istenen `point_usage` parametresi kullanıldığında, kullanıcı cüzdanındaki puan tutarı önceliklendirilerek, harcama tutarı kadar kullandırılmaya çalışılır. Örn. 100 liralık harcama isteğinde, kullanıcının 500 Bakiye, 200 Puan olduğunu düşünürsek, `point_usage` parametresi `true` gönderdildiğinde harcama, kullanıcının puan tutarından düşürülerek gerçekleştirilir. Ödeme işlemi sonrası kullanıcının cüzdanı 500 Bakiye, 100 Puan olarak güncellenir. - **Puan Tutarının Manuel Belirlenmesi(point kullanımı):** Harcamada kullanıcının cüzdanından düşülecek puanın sizin tarafınızdan belirlenmesidir. İstekte opsiyonel olarak istenen `point` değeri kadar kullanıcı cüzdanından harcama yapılmaya çalışılır. Örn. 100 liralık harcama isteğinde, price: 70, point: 30 gönderildiğinde kullanıcı cüzdanından 70 bakiye ve 30 puan ile harcama yapılmaya çalışılacaktır. Bu yöntem ile harcama isteği yapıldığında, `price` ve `point` değerlerini kullanıcı cüzdan tutarına göre sizin hesaplamanız gerekmektedir. ([Ödeme Kontrolü](/waas/waas-payment-pre-check) isteğinde kullanıcı cüzdan bilgileri verilmektedir.) Bu yöntem kullanıldığında `point_usage` parametresi gönderilse bile dikkate alınmayacaktır. ### Extra Bilgiler - `external_id` alanı opsiyoneldir. Genellikle ödemeye ait sipariş numarası gibi harici sistem ID'si burada gönderilir; işlemleri kolayca takip etmenize yardımcı olur. ### Ürün Listesi `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. Bu bilgiler raporlama ve analiz amaçlı kullanılır. Ürün listesi gönderildiğinde: * Her ürün için `price` ve `quantity` alanları birlikte zorunludur * Her ürünün `total_price` değeri, `price * quantity` ile eşleşmelidir * Tüm ürünlerin `total_price` toplamı, ödeme tutarı `price + point` ile eşleşmelidir ### Request Body - `user_mapping_id` (string, zorunlu): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `price` (number, zorunlu): Sipariş tutarı (ornek: 10) - `point_usage` (boolean): Harcama puan ile yapılmalı mı - `point` (number): Harcamada cüzdandan düşülecek puan değeri. Bu parametre null veya gönderilmezse, `point_usage parametresi dikkate alınacatır (ornek: 1) - `external_id` (string): Harici sistem ID değeri (ornek: "EXT-12345") - `product_list` (array): Ürün listesi - `item_id` (integer): Ürün ID (ornek: 1) - `name` (string): Ürün adı (ornek: "Ayran") - `category_name` (string): Kategori adı (ornek: "İçecekler") - `price` (number): Birim fiyat (quantity ile birlikte zorunlu) (ornek: 20) - `quantity` (integer): Miktar (price ile birlikte zorunlu) (ornek: 2) - `total_price` (number): Toplam fiyat (price ve quantity varsa zorunlu) (ornek: 40) - `apply_campaigns` (boolean): Harcama sonucunda kullanıcının kampanyadan faydalanıp faydalanmayacağını belirtir. ### Response 200 - `data` (object): - `order_id` (string): Ödeme Unique Sipariş ID (ornek: "3279724498") - `price` (number): Ödeme İşlem Tutarı (ornek: 1) - `paid_price` (number): Ödenen İşlem Tutarı (ornek: 1) - `point` (number): Ödeme Puan Tutarı (ornek: 1) - `final_total` (number): Ödeme Toplam Tutarı(Puan Tutarı + Ödeme Tutarı) (ornek: 1) - `refund_amount` (number): İade Edilen Tutar (ornek: 1) - `refund_point` (number): İade Edilen Puan Tutarı (ornek: 1) - `status` (object): - `status_translate` (object): ### Response 404 - `message` (string): (ornek: "Kullanıcının cüzdanı bulunmamakta.") ### Response 412 - `message` (string): (ornek: "Bakiye yetersiz.") --- # Direct Payment - Ödeme Kontrolü (https://docs.altpay.dev/waas/(direct-payment)/waas-payment-pre-check) **POST** `/waas/integration/payments/pre-check` - Sepet veya ödeme aşamalarında cüzdan ile ödeme seçeneğinde kullanabileceğiniz servistir. Bu servis ile kullanıcının bakiyesi ve puan bilgisi alınıp ödemeyi puan ile yapıp yapamayacağı bilgisi alınır. Eğer ilgili kullanıcının ödeme için yeterli bakiyesi yoksa cüzdan uygulamasına yönlendirip ödemeye hazır hale getirilmesi gerekmektedir. - Macellan SuperApp cüzdan uygulamasında kullanıcı, ödeme için eksik olan tutarı başarıyla yüklediğinde, uygulamamız [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) kullanarak `{success: true, event: 'COMPLETE_DEPOSIT'}` mesajını gönderir. Bu mesaj, ödemenin hazır olduğunu belirtir ve sizin tarafınızdan yakalanması gerekmektedir. ### Request Body - `user_mapping_id` (string, zorunlu): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `price` (number, zorunlu): Sipariş tutarı (ornek: 10) - `round_up_deposit` (boolean): Kullanıcı bakiyesinin harcama işlemi için yetersiz olması durumunda yüklenmesi gereken tutarın şirketin ön tanımlı yükleme tutarlarından en yakın üst tutara yuvarlanmasının belirtildiği parametre ### Response 200 - `message` (string): - `data` (object): - `wallet` (object): - `balance` (number): - `point` (number): - `redirect_url` (string): - `token` (string): - `has_point_usage` (boolean): Kullanıcının bu ödemede puan kullanıp kullanamayacağını bildirir. ### Response 404 - `message` (string): (ornek: "Kullanıcının cüzdanı bulunmamakta.") ### Response 412 - `message` (string): - `data` (object): - `wallet` (object): - `balance` (number): - `point` (number): - `redirect_url` (string): - `token` (string): - `has_point_usage` (boolean): Kullanıcının bu ödemede puan kullanıp kullanamayacağını bildirir. --- # Direct Payment - Ödeme Detay Güncelleme (https://docs.altpay.dev/waas/(direct-payment)/waas-payment-update-detail) **PUT** `/waas/integration/payments/update/detail` - Ödeme işlemi tamamlandıktan sonra ödeme detaylarını güncellemek için kullanılır. - Bu servis ile ödeme işlemine ait ek bilgiler external_id, product_list ve extra gibi detaylar güncellenebilir. ### Extra Bilgiler - `external_id` alanı opsiyoneldir. Genellikle ödemeye ait sipariş numarası gibi harici sistem ID'si burada gönderilir; işlemleri kolayca takip etmenize yardımcı olur. - `extra` alanı opsiyoneldir ve ödeme işlemine ait ek bilgileri bu alanda gönderebilirsiniz. - `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. ### Ürün Listesi `product_list` alanı opsiyoneldir ve satın alınan ürünlerin detaylarını bu alanda gönderebilirsiniz. Bu bilgiler raporlama ve analiz amaçlı kullanılır. Ürün listesi gönderildiğinde: * Her ürün için `price` ve `quantity` alanları birlikte zorunludur * Her ürünün `total_price` değeri, `price * quantity` ile eşleşmelidir * Tüm ürünlerin `total_price` toplamı, ödeme tutarı `price + point` ile eşleşmelidir ### Request Body - `order_id` (integer, zorunlu): Güncellenecek ödeme işleminin unique sipariş ID değeri (ornek: 1131347753) - `external_id` (string): Harici sistem ID değeri (ornek: "EXT-12345") - `extra` (object): Ödeme işlemine ait ek bilgiler (ornek: {"note":"Özel not","source":"mobile_app"}) - `product_list` (array): Ürün listesi - `item_id` (integer): Ürün ID (ornek: 1) - `name` (string): Ürün adı (ornek: "Ayran") - `category_name` (string): Kategori adı (ornek: "İçecekler") - `price` (number): Birim fiyat (quantity ile birlikte zorunlu) (ornek: 20) - `quantity` (integer): Miktar (price ile birlikte zorunlu) (ornek: 2) - `total_price` (number): Toplam fiyat (price ve quantity varsa zorunlu) (ornek: 40) ### Response 200 - `data` (object): - `success` (boolean): (ornek: true) ### Response 404 - `message` (string): (ornek: "Ödeme işlemi bulunamadı") --- # Kampanyalar - Kampanya Listesi (https://docs.altpay.dev/waas/(kampanyalar)/waas-campaigns-list) **GET** `/waas/integration/campaigns/list` - Bu servis ile şirketinizin aktif kampanyalarını görüntüleyebilirsiniz. - `user_mapping_id` parametresi opsiyoneldir. Gönderildiğinde, kullanıcının kampanyaları kullanıp kullanmadığı bilgisi de döner. - `user_mapping_id` parametresi gönderildiğinde, kullanıcının daha önce kullandığı `onboarding` kampanyaları varsa listede görünmez. ### Enum Değerleri Ve Açıklamaları #### `campaign_types` (Kampanya Türü) | Enum Değeri | Açıklama | |---------------------------------|------------------------------| | `deposit_gift` | Yüklemeye Puan | | `payment_count_gift` | Harcama Sayısına Puan | | `cross_marketing_deposit_gift` | Çapraz Satış Yüklemeye Puan | | `payment_discount` | Harcamaya İndirim |
#### `point_earn_type` (Puan Kazanma Türü) | Enum Değeri | Açıklama | |---------------|--------------| | `fixed` | Tutar Bazlı | | `percentage` | Oran Bazlı |
#### `point_earn_type` Alanlarına Göre Sıfır Değerler | point_earn_type | point_amount | point_percent | |-----------------|--------------|---------------| | `fixed` | Değer döner | 0 döner | | `percentage` | 0 döner | Değer döner |
#### Kampanya Türlerine Göre Alan Kullanımı | Kampanya Türü | point_earn_type | amount | point_amount | point_percent | process_count | minimum_amount | maximum_amount | |----------------|------------------|--------|--------------|---------------|---------------|----------------|----------------| | `deposit_gift` | fixed/percentage | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | | `payment_count_gift` | fixed/percentage | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ | | `cross_marketing_deposit_gift` | fixed | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | | `payment_discount` | percentage | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ |
#### Boolean Alanlar | Alan | Açıklama | |------|----------| | `multiple_usage` | Çoklu Kullanım: Aynı kampanya aynı kullanıcı için birden fazla kez kullanılabilir | | `include_multiples` | Katlarını Dahil Et (point_earn_type=fixed olduğunda): Yükleme tutarının katlarına da puan kazanılabilir | | `combined_usage` | Diğer Kampanyalarla Kullanım: Diğer kampanyalarla birlikte kullanılabilir | | `onboarding` | Onboarding Kampanyası: Yeni kayıt olan kullanıcılar için kullanılabilir kampanya |
#### Tarih Alanları | Alan | Açıklama | |------|----------| | `point_expire_date` | Puan son kullanma tarihi (sabit tarih seçildiğinde) | | `expiration_days` | Puan geçerlilik gün sayısı (gün bazlı seçildiğinde) | | `calculated_expiration_date` | Hesaplanan puan son kullanma tarihi (point_expire_date varsa onu, yoksa expiration_days kadar gün ekleyerek hesaplanan tarihi) | ### Parametreler - `user_mapping_id` (string, query): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `campaign_types` (array, query): Kampanya türü filtresi (ornek: ["deposit_gift","cross_marketing_deposit_gift"]) ### Response 200 - `data` (array): - `id` (integer): Kampanya ID (ornek: 1) - `name` (string): Kampanya adı (ornek: "Yaz Tatili Fırsatı") - `description` (string): Kampanya açıklaması (ornek: "Yaz tatiline özel ekstra puan kazanın!") - `type` (string): Kampanya türü [deposit_gift, payment_count_gift, cross_marketing_deposit_gift, payment_discount] (ornek: "deposit_gift") - `point_earn_type` (string): Puan kazanma türü [fixed, percentage] (ornek: "percentage") - `user_used` (boolean): Kullanıcının kampanyayı kullanma durumu (ornek: false) - `amount` (number): Yükleme tutarı (ornek: 100) - `point_amount` (number): Kazanılacak puan tutarı (ornek: 5) - `point_percent` (number): Kazanılacak puan yüzdesi (ornek: 5) - `minimum_amount` (number): Minimum harcama tutarı (ornek: 50) - `maximum_amount` (number): Maksimum harcama tutarı (ornek: 500) - `process_count` (integer): Harcama sayısı (ornek: 5) - `usage_limit` (integer): Kullanım limiti (ornek: 1000) - `total_usage` (integer): Toplam kullanım sayısı (ornek: 150) - `multiple_usage` (boolean): Çoklu Kullanım (ornek: true) - `include_multiples` (boolean): Katlarını Dahil Et (ornek: false) - `combined_usage` (boolean): Diğer Kampanyalarla Kullanım (ornek: true) - `onboarding` (boolean): Onboarding Kampanyası (ornek: false) - `start_date` (string): Kampanya başlangıç tarihi (ornek: "2024-01-01T00:00:00+03:00") - `end_date` (string): Kampanya bitiş tarihi (ornek: "2024-12-31T23:59:59+03:00") - `point_expire_date` (string): Puan son kullanma tarihi (ornek: "2025-01-15T23:59:59+03:00") - `expiration_days` (integer): Puan geçerlilik gün sayısı (ornek: 30) - `calculated_expiration_date` (string): Hesaplanan puan son kullanma tarihi (ornek: "2025-01-15T23:59:59+03:00") - `meta` (object): ### Response 404 - `message` (string): --- # Kullanıcı Detay - Linkleme Id'ye Göre (https://docs.altpay.dev/waas/(kullanici)/(detay)/waas-user-get-by-mapping) **GET** `/waas/integration/users/by-mapping/{userMappingId}` İlgili linkleme id ye ait kullanıcı bilgisi verilir. ### Parametreler - `userMappingId` (string, zorunlu, path): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") ### Response 200 - `data` (object): - `user_mapping_id` (string): Kullanıcıya ait linkleme id değeri (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `user` (object): Cüzdan sahibinin bilgilerini içerir. - `mapping` (object): - `id` (string): Kullanıcıya ait linkleme id değeri. (Iframe açma, ödeme gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `wallet_id` (integer): Cüzdanın id numarasını belirtir. (ornek: 1) - `is_active` (boolean): Cüzdanın aktif-pasif durumunu belirtir. Pasif cüzdanlar waas uygulamasını kullanamaz. (ornek: true) - `created_at` (string): - `id` (string): Cüzdan sahibinin SuperApp id numarasını belirtir. (ornek: "25809faf-9f21-40c8-bebe-3dd4e343b446") - `first_name` (string): Cüzdan sahibinin adını belirtir. (ornek: "AB****") - `last_name` (string): Cüzdan sahibinin soyadını belirtir. (ornek: "CD****") - `email` (string): Cüzdan sahibinin e-mail adresini belirtir. (ornek: "ab*****@test.com") - `phone` (string): Cüzdan sahibinin telefon numarasını belirtir. (ornek: "90***********") - `locale` (string): Kullanıcının dil bilgisi (ornek: "tr") - `wallet` (object): - `id` (integer): Cüzdan id numarasını gösterir. (ornek: 1) - `visibility` (boolean): Kullanıcının cüzdanı görüntülemek istediğini veya aksini belirtir. - `balance` (number): Cüzdanın kullanılabilir bakiyesini belirtir. (ornek: 1) - `point` (number): Cüzdanın kullanılabilir puanını belirtir. (ornek: 1) - `held_balance` (number): Bloklu bakiye - `held_point` (number): Bloklu puan - `total_held` (number): Toplam bloklu tutar - `company_id` (integer): Cüzdanın bağlı olduğu şirket id numarasını belirtir. (ornek: 1) ### Response 404 - `message` (string): --- # Kullanıcı Detay - Linkleme Id'ye Göre (Toplu) (https://docs.altpay.dev/waas/(kullanici)/(detay)/waas-user-get-by-mapping-bulk) **POST** `/waas/integration/users/by-mapping-bulk` İlgili linkleme id'lere ait kullanıcı bilgilerini toplu olarak verir. Maksimum 30 adet linkleme id gönderilebilir. ### Request Body - `user_mapping_ids` (array, zorunlu): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcılara ait linkleme id değerleri. (ornek: ["8b5ac43a-20ce-4987-a739-d8a7ee480eaa","9c6bd54b-31df-5098-b840-e9b8ff591fbb"]) ### Response 200 - `data` (array): - `user_mapping_id` (string): Kullanıcıya ait linkleme id değeri (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `user` (object): Cüzdan sahibinin bilgilerini içerir. - `mapping` (object): - `id` (string): Kullanıcıya ait linkleme id değeri. (Iframe açma, ödeme gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `wallet_id` (integer): Cüzdanın id numarasını belirtir. (ornek: 1) - `is_active` (boolean): Cüzdanın aktif-pasif durumunu belirtir. Pasif cüzdanlar waas uygulamasını kullanamaz. (ornek: true) - `created_at` (string): - `id` (string): Cüzdan sahibinin SuperApp id numarasını belirtir. (ornek: "25809faf-9f21-40c8-bebe-3dd4e343b446") - `first_name` (string): Cüzdan sahibinin adını belirtir. (ornek: "AB****") - `last_name` (string): Cüzdan sahibinin soyadını belirtir. (ornek: "CD****") - `email` (string): Cüzdan sahibinin e-mail adresini belirtir. (ornek: "ab*****@test.com") - `phone` (string): Cüzdan sahibinin telefon numarasını belirtir. (ornek: "90***********") - `locale` (string): Kullanıcının dil bilgisi (ornek: "tr") - `wallet` (object): - `id` (integer): Cüzdan id numarasını gösterir. (ornek: 1) - `visibility` (boolean): Kullanıcının cüzdanı görüntülemek istediğini veya aksini belirtir. - `balance` (number): Cüzdanın kullanılabilir bakiyesini belirtir. (ornek: 1) - `point` (number): Cüzdanın kullanılabilir puanını belirtir. (ornek: 1) - `held_balance` (number): Bloklu bakiye - `held_point` (number): Bloklu puan - `total_held` (number): Toplam bloklu tutar - `company_id` (integer): Cüzdanın bağlı olduğu şirket id numarasını belirtir. (ornek: 1) --- # Kullanıcı Detay - Telefon Numarasına Göre (https://docs.altpay.dev/waas/(kullanici)/(detay)/waas-user-get-by-phone) **GET** `/waas/integration/users/by-phone/{phone}` İlgili telefon numarasına ait kullanıcı bilgisi verilir. Bu servis, kullanıcıya cüzdan hesabı oluşturmak için hangi servisleri çağırmanız gerektiğini belirlemek için de kullanılabilir. Aşağıdaki maddelere göre işlem gerçekleştirilebilir. - 404 response ve response içerisinde `state: "non_registered"` verilmesi durumunda, bu telefon numarasının Macellan SuperApp'te kayıtlı olmadığı belirtilir. [OTP](/otp/otp-send) işlemi gerçekleştirip [Oluştur](/waas/waas-user-register) servisi çağrılmalıdır. - Response datası içerisinde `state: "registered_but_non_linked"`, ise bu telefon numarası Macellan SuperApp'te kayıtlı ancak cüzdan linklemesi yapılmamıştır. [OTP](/otp/otp-send) işlemi gerçekleştirip [Linkleme](/waas/waas-link-existing-user) servisi çağrılmalıdır. - Linklemesi yapılmamış kullanıcının ad-soyad gibi bilgileri maskelenmiş olarak verilmekte. (Response içerisinde verilen user bilgisi) - Response datası içerisinde `state: "linked"` ise, bu telefon numarası linklenmiştir. - Kullanıcı bilgisi maskelenmeden verilir. (Response içerisinde verilen user bilgisi) ### Parametreler - `phone` (string, zorunlu, path): [E.164 Format](https://www.twilio.com/docs/glossary/what-e164) (ornek: "905231113344") ### Response 200 - `data` (object): - `user` (object): Cüzdan sahibinin bilgilerini içerir. - `mapping` (object): - `id` (string): Kullanıcıya ait linkleme id değeri. (Iframe açma, ödeme gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `wallet_id` (integer): Cüzdanın id numarasını belirtir. (ornek: 1) - `is_active` (boolean): Cüzdanın aktif-pasif durumunu belirtir. Pasif cüzdanlar waas uygulamasını kullanamaz. (ornek: true) - `created_at` (string): - `id` (string): Cüzdan sahibinin SuperApp id numarasını belirtir. (ornek: "25809faf-9f21-40c8-bebe-3dd4e343b446") - `first_name` (string): Cüzdan sahibinin adını belirtir. (ornek: "AB****") - `last_name` (string): Cüzdan sahibinin soyadını belirtir. (ornek: "CD****") - `email` (string): Cüzdan sahibinin e-mail adresini belirtir. (ornek: "ab*****@test.com") - `phone` (string): Cüzdan sahibinin telefon numarasını belirtir. (ornek: "90***********") - `locale` (string): Kullanıcının dil bilgisi (ornek: "tr") - `wallet` (object): - `id` (integer): Cüzdan id numarasını gösterir. (ornek: 1) - `visibility` (boolean): Kullanıcının cüzdanı görüntülemek istediğini veya aksini belirtir. - `balance` (number): Cüzdanın kullanılabilir bakiyesini belirtir. (ornek: 1) - `point` (number): Cüzdanın kullanılabilir puanını belirtir. (ornek: 1) - `held_balance` (number): Bloklu bakiye - `held_point` (number): Bloklu puan - `total_held` (number): Toplam bloklu tutar - `company_id` (integer): Cüzdanın bağlı olduğu şirket id numarasını belirtir. (ornek: 1) - `state` (string): Kullanıcı durumu [non_registered, registered_but_non_linked, linked] (ornek: "linked") ### Response 404 - `message` (string): - `state` (string): Kullanıcı durumu (ornek: "non_registered") --- # Kullanıcı Güncelle - Telefon (https://docs.altpay.dev/waas/(kullanici)/(guncelle)/waas-user-phone-update) **PUT** `/waas/integration/users/phone` - Bu servis ile cüzdan uygulaması eşlemesi yapılan kullanıcınızın telefon bilgisini güncelleyebilirsiniz. [OTP](/otp/otp-send) işleminden sonra çalıştırılmaldır. ### Request Body - `user_mapping_id` (string, zorunlu): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `phone` (string, zorunlu): Kullanıcı telefon bilgisi ([E.164 Format](https://www.twilio.com/docs/glossary/what-e164)) (ornek: "+905231113344") - `verify_id` (integer, zorunlu): Telefona ait [OTP Doğrulama](/otp/otp-verify) id bilgisi (ornek: 1) ### Response 200 - `data` (object): - `success` (boolean): ### Response 404 - `message` (string): ### Response 409 - `message` (string): ### Response 412 - `message` (string): --- # Kullanıcı Güncelle - Durum (https://docs.altpay.dev/waas/(kullanici)/(guncelle)/waas-user-status-update) **PUT** `/waas/integration/users/status` - Bu servis ile kullanıcının durumu Aktif-Pasif e ayarlanabilir. Pasif kullanıcılar waas uygulamasını kullanamaz. ### Request Body - `user_mapping_id` (string, zorunlu): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `is_active` (boolean, zorunlu): Kullanıcı durumu (ornek: false) ### Response 200 - `data` (object): - `success` (boolean): ### Response 404 - `message` (string): --- # Kullanıcı Güncelle - Kullanıcı Bilgileri (https://docs.altpay.dev/waas/(kullanici)/(guncelle)/waas-user-update) **PUT** `/waas/integration/users` - Bu servis ile cüzdan uygulaması eşlemesi yapılan kullanıcılarınızın bilgilerini güncelleyebilirsiniz. - Sisteminizde kayıtlı kullanıcının email, ad soyad gibi bilgileri değiştiğinde bu servis çalıştırılmalıdır. ### Request Body - `user_mapping_id` (string, zorunlu): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `email` (string): (ornek: "dev@macellan.app") - `locale` (string): Kullanıcının dil bilgisi [tr, en] (ornek: "tr") - `first_name` (string): Kullanıcı ad bilgisi (ornek: "Macellan") - `last_name` (string): Kullanıcı soyad bilgisi (ornek: "Superapp") - `details` (object): Kullanıcı detay bilgisi - `id_number` (string): Kullanıcı kimlik numarası (ornek: "111111111111") - `birth_date` (string): Doğum Tarihi (ornek: "2000-12-20") - `subscribe_sms` (boolean): Sms iletişim izni (ornek: false) - `subscribe_email` (boolean): Email iletişim izni (ornek: false) - `verifies` (object): Kullanıcı doğrulama bilgileri - `email` (boolean): Email doğrulama durumu (ornek: false) ### Response 200 - `data` (object): - `success` (boolean): ### Response 404 - `message` (string): ### Response 409 - `message` (string): --- # Kullanıcı Kayıt - Kullanıcı Kayıt İşlemleri (https://docs.altpay.dev/waas/(kullanici)/(kayit)/register-intro) Cüzdan uygulamanıza kullanıcı kaydetme işlemini aşağıdaki adımları takip ederek yapabilirsiniz. 1. Kaydedilmek istenen kullanıcının telefon bilgisiyle durumu sorgulanır. 2. Eğer durum `non_registered` ise OTP işlemi gerçekleştirip Oluştur servisi çağrılmalıdır. 3. Eğer durum `registered_but_non_linked` ise OTP işlemi gerçekleştirip Linkleme servisi çağrılmalıdır. --- # Kullanıcı Kayıt - Linkleme (https://docs.altpay.dev/waas/(kullanici)/(kayit)/waas-link-existing-user) **POST** `/waas/integration/users/register/link-existing-user` - Bu servis ile Macellan SuperApp'te kayıtlı ancak cüzdanınızda kayıtlı olmayan kullanıcıyı linkleme işlemi için kullanabilirsiniz. [OTP](/otp/otp-send) işleminden sonra çağrılmalıdır. ### Request Body - `phone` (string, zorunlu): Kullanıcı telefon bilgisi ([E.164 Format](https://www.twilio.com/docs/glossary/what-e164)) (ornek: "+905231113344") - `verify_id` (integer, zorunlu): Telefona ait [OTP Doğrulama](/otp/otp-verify) id bilgisi (ornek: 1) ### Response 200 - `data` (object): Cüzdan sahibinin bilgilerini içerir. - `mapping` (object): - `id` (string): Kullanıcıya ait linkleme id değeri. (Iframe açma, ödeme gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `wallet_id` (integer): Cüzdanın id numarasını belirtir. (ornek: 1) - `is_active` (boolean): Cüzdanın aktif-pasif durumunu belirtir. Pasif cüzdanlar waas uygulamasını kullanamaz. (ornek: true) - `created_at` (string): - `id` (string): Cüzdan sahibinin SuperApp id numarasını belirtir. (ornek: "25809faf-9f21-40c8-bebe-3dd4e343b446") - `first_name` (string): Cüzdan sahibinin adını belirtir. (ornek: "AB****") - `last_name` (string): Cüzdan sahibinin soyadını belirtir. (ornek: "CD****") - `email` (string): Cüzdan sahibinin e-mail adresini belirtir. (ornek: "ab*****@test.com") - `phone` (string): Cüzdan sahibinin telefon numarasını belirtir. (ornek: "90***********") - `locale` (string): Kullanıcının dil bilgisi (ornek: "tr") ### Response 404 - `message` (string): ### Response 409 - `message` (string): --- # Kullanıcı Kayıt - Oluştur (https://docs.altpay.dev/waas/(kullanici)/(kayit)/waas-user-register) **POST** `/waas/integration/users/register` - Bu servis, [OTP](/otp/otp-send) işleminden sonra kullanıcıyı oluşturup cüzdan hesabının açılması için kullanılır. ### Request Body ### Response 200 - `data` (object): Cüzdan sahibinin bilgilerini içerir. - `mapping` (object): - `id` (string): Kullanıcıya ait linkleme id değeri. (Iframe açma, ödeme gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `wallet_id` (integer): Cüzdanın id numarasını belirtir. (ornek: 1) - `is_active` (boolean): Cüzdanın aktif-pasif durumunu belirtir. Pasif cüzdanlar waas uygulamasını kullanamaz. (ornek: true) - `created_at` (string): - `id` (string): Cüzdan sahibinin SuperApp id numarasını belirtir. (ornek: "25809faf-9f21-40c8-bebe-3dd4e343b446") - `first_name` (string): Cüzdan sahibinin adını belirtir. (ornek: "AB****") - `last_name` (string): Cüzdan sahibinin soyadını belirtir. (ornek: "CD****") - `email` (string): Cüzdan sahibinin e-mail adresini belirtir. (ornek: "ab*****@test.com") - `phone` (string): Cüzdan sahibinin telefon numarasını belirtir. (ornek: "90***********") - `locale` (string): Kullanıcının dil bilgisi (ornek: "tr") ### Response 404 - `message` (string): ### Response 406 - `message` (string): --- # Kullanıcı - Kullanıcı (https://docs.altpay.dev/waas/(kullanici)/user) WaaS entegrasyonu, kullanıcı yönetimini kolaylaştırmak için çeşitli servisler sunar. Kullanıcıların cüzdan hesaplarını oluşturmak, linklemek ve güncellemek için farklı yöntemler bulunmaktadır. Genel olarak, kullanıcı servisleri üç ana aşamada ele alınır: #### 1) Detay: Belirli bir telefon numarasına ait kullanıcı bilgisi, kullanıcıya cüzdan hesabı oluşturmak için gerekli servislerin belirlenmesi amacıyla sorgulanabilir. Eğer kullanıcı kayıtlı değilse oluşturulur, kayıtlı ancak linklenmemişse linkleme servisi çağrılır, eğer kullanıcı linklenmişse bilgileri doğrudan verilir. #### 2) Güncelleme: Eşlemesi yapılmış kullanıcıların kişisel bilgilerini ve telefon numaralarını güncellemek için kullanılır. #### 3) Kullanıcı Kayıt İşlemleri: Yeni kullanıcıları cüzdan uygulamanıza kaydetmek için kullanılır. Kullanıcının mevcut durumuna göre OTP işlemleri ve servis çağrıları gerçekleştirilir. Bu aşamalar sayesinde, kullanıcılarınızın cüzdan fonksiyonlarını sorunsuz bir şekilde kullanmalarını sağlayabilirsiniz. --- # Müşteri Grupları - Müşteri Grupları (https://docs.altpay.dev/waas/(musteri-gruplari)/user-groups) Müşteri grupları kampanyalarda hedefleme ve hariç tutma için kullanılır. Gruplar Macellan SuperApp panelinden oluşturulur. Bu servislerle şirketinize ait grupları listeleyebilir, gruplara üye ekleyip çıkarabilirsiniz. ## Üye Türleri Gruplara temassız kart veya telefon numarası eklenebilir. Üye türü `type` alanında, değerler `values` alanında gönderilir: | Tür | `type` | `values` | | -------- | ---------- | ----------------- | | Temassız kart | `tap_card` | Kart numaraları | | Telefon | `phone` | Telefon numaraları | Her istekte yalnızca bir tür gönderilir. ```json { "type": "phone", "values": ["+905321234567", "05551112233"] } ``` Yanıtta gönderilen tür ve sonuç döner. İşlenemeyen üyeler, gönderdiğiniz değerle birlikte `fails` listesinde yer alır: ```json { "data": { "type": "phone", "success_count": 1, "fails": [ { "value": "05551112233", "message": "'05551112233' numaralı telefona ait, bu şirkette cüzdanı olan bir kullanıcı bulunamadı." } ] } } ``` ## Temassız Kart Üyeliği Gruba kartın sahibi değil, kartın kendisi eklenir. Aynı kişiye ait birden fazla kart varsa, yalnızca gruba eklenen kart grubun üyesi sayılır. - Eklenecek kart şirketinize ait ve aktif olmalıdır. - İptal edilen kart artık grubun üyesi sayılmaz. - Kart daha sonra yeniden tanımlanırsa gruba tekrar eklenmelidir. ## Telefon Üyeliği Gruba telefon numarasıyla kullanıcının kendisi eklenir. Kullanıcı grubun üyesi olduğunda, kullanıcıya ait bütün kartlar ve mobil uygulama işlemleri grubun kapsamına girer. - Telefon numarası, şirketinizde cüzdanı olan bir kullanıcıya ait olmalıdır. ## Kısmi Başarı Ekleme ve çıkarma servisleri üyeleri tek tek işler. İşlenemeyen bir üye isteği başarısız yapmaz, `fails` listesinde sebebiyle birlikte döner, diğer üyeler işlenmeye devam eder. --- # Müşteri Grupları - Gruba Üye Ekleme (https://docs.altpay.dev/waas/(musteri-gruplari)/waas-user-group-add-members) **POST** `/waas/integration/user-groups/{id}/members` Bu servis ile bir müşteri grubuna **temassız kart** veya **telefon numarası** ekleyebilirsiniz. **Genel** - `type` alanında üye türünü (`tap_card` veya `phone`), `values` alanında kart veya telefon numaralarını gönderin. - Her istekte yalnızca bir tür gönderilir, en fazla **1000** değer gönderilebilir. - Eklenemeyen üyeler `fails` listesinde, gönderdiğiniz değer ve sebebiyle birlikte döner. Listedeki diğer üyeler eklenmeye devam eder. **Temassız kart** (`tap_card`) - Kart, grubun şirketine ait ve aktif olmalıdır. - İptal edilen kart artık grubun üyesi sayılmaz. Kart daha sonra yeniden tanımlanırsa gruba tekrar eklenmelidir. **Telefon** (`phone`) - Telefon numarası, şirketinizde cüzdanı olan bir kullanıcıya ait olmalıdır. - Numara `+90 532 123 45 67`, `05321234567` gibi farklı biçimlerde gönderilebilir. ### Parametreler - `id` (integer, zorunlu, path): Müşteri grubu listesinde dönen grup id değeri. ### Request Body - `type` (string, zorunlu): Üye türü. `tap_card` için kart numaraları, `phone` için telefon numaraları gönderilir. [tap_card, phone] (ornek: "phone") - `values` (array, zorunlu): Kart veya telefon numaraları. Aynı değer bir istekte iki kez gönderilemez. (ornek: ["+905321234567","05551112233"]) ### Response 200 - `data` (object): - `type` (string): İstekte gönderilen üye türü. [tap_card, phone] (ornek: "phone") - `success_count` (integer): İşlenen üye adedi. (ornek: 1) - `fails` (array): İşlenemeyen üyeler ve sebepleri. - `value` (string): Gönderdiğiniz değer. (ornek: "05551112233") - `message` (string): ### Response 404 - `message` (string): (ornek: "Müşteri grubu bulunamadı.") --- # Müşteri Grupları - Müşteri Grubu Listesi (https://docs.altpay.dev/waas/(musteri-gruplari)/waas-user-group-list) **GET** `/waas/integration/user-groups` - Bu servis ile şirketinize ait müşteri gruplarını listeleyebilirsiniz. - Müşteri grupları Macellan SuperApp panelinden oluşturulur. Bu servis yalnızca var olan grupları listeler. - Gruplar en yeniden eskiye doğru sıralanır. ### Parametreler - `page` (integer, query): Listelenmek istenen sayfa numarası. ### Response 200 - `data` (array): - `id` (integer): Müşteri grubu id değeri. Üye ekleme ve çıkarma servislerinde kullanılır. (ornek: 32) - `name` (string): Grup adı. (ornek: "Lise Öğrencileri") - `description` (string): Grup açıklaması. (ornek: "Sadece öğle yemeği hakkı olan kartlar") - `meta` (object): --- # Müşteri Grupları - Gruptan Üye Çıkarma (https://docs.altpay.dev/waas/(musteri-gruplari)/waas-user-group-remove-members) **DELETE** `/waas/integration/user-groups/{id}/members` Bu servis ile bir müşteri grubundan **temassız kart** veya **telefon numarası** çıkarabilirsiniz. **Genel** - `type` alanında üye türünü (`tap_card` veya `phone`), `values` alanında kart veya telefon numaralarını gönderin. - Her istekte yalnızca bir tür gönderilir, en fazla **1000** değer gönderilebilir. - Grupta bulunmayan üyeler `fails` listesinde, gönderdiğiniz değerle birlikte döner. Listedeki diğer üyeler çıkarılmaya devam eder. **Temassız kart** (`tap_card`) - Kart numarası, kartın durumuna bakılmadan eşleştirilir. İptal edilmiş bir kart da gruptan çıkarılabilir. **Telefon** (`phone`) - Numara `+90 532 123 45 67`, `05321234567` gibi farklı biçimlerde gönderilebilir. ### Parametreler - `id` (integer, zorunlu, path): Müşteri grubu listesinde dönen grup id değeri. ### Request Body - `type` (string, zorunlu): Üye türü. `tap_card` için kart numaraları, `phone` için telefon numaraları gönderilir. [tap_card, phone] (ornek: "phone") - `values` (array, zorunlu): Kart veya telefon numaraları. Aynı değer bir istekte iki kez gönderilemez. (ornek: ["+905321234567","05551112233"]) ### Response 200 - `data` (object): - `type` (string): İstekte gönderilen üye türü. [tap_card, phone] (ornek: "phone") - `success_count` (integer): İşlenen üye adedi. (ornek: 1) - `fails` (array): İşlenemeyen üyeler ve sebepleri. - `value` (string): Gönderdiğiniz değer. (ornek: "05551112233") - `message` (string): ### Response 404 - `message` (string): (ornek: "Müşteri grubu bulunamadı.") --- # Nakit Yükleme - Yükleme Servisi (https://docs.altpay.dev/waas/(nakit-yukleme)/waas-cash-deposit-direct) **POST** `/waas/integration/cash-deposits/make` - Nakit yükleme servisi, entegratör firmanın, kullanıcıdan herhangi bir onay almadan kullanıcının cüzdanına nakit yükleme yapmasını sağlar. - İade işlemi için nakit yükleme servisinin kullanılacağı durumlarda `is_apply_campaigns` değeri `false` olarak gönderilmeli ve yapılan nakit yükleme işlemi için kullanıcının kampanyalardan yararlanması engellenmelidir. Eğer hiç bir değer göndermezseniz `true` olarak setlenecektir. ### Request Body - `user_mapping_id` (string, zorunlu): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `amount` (number, zorunlu): Yükleme İşlem Tutarı (ornek: 1.23) - `is_apply_campaigns` (boolean): Bu parametre hiç gönderilmezse default `true` olarak setlenecektir. İade için yapılan nakit yüklemelerde `false` olarak gönderilmelidir. - `order_id` (string): Bu parametre sipariş numarası atamak için kullanılır gönderilmediği takdirde sistem tarafından otomatik sipariş numarası atanır. (ornek: "1842515611") - `method` (string): Bu parametre yükleme metodunu belirlemek için kullanılır. Nakit için "cash", kredi kartı için "credit_card". Boş gönderildiği takdirde, sistem bu değeri "cash" olarak ele alacaktır. [cash, credit_card] (ornek: "cash") - `point` (number): Puan Tutarı (ornek: 1.23) - `point_expire_date` (string): Puan Son Kullanma Tarihi (ornek: "2025-12-31") ### Response 200 - `data` (object): - `id` (integer): ID (ornek: 1) - `user_mapping_id` (string): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "i9c4859e8-5e97-47ca-b65c-4aaa5ae50cab") - `reference_code` (integer): Referans Kodu (ornek: 831677) - `order_id` (string): Sipariş Numarası (ornek: "2226203566") - `status` (object): - `status_translate` (object): - `method` (string): Yükleme metodu [cash, credit_card] (ornek: "cash") - `amount` (number): Yükleme İşlem Tutarı (ornek: 1.23) - `created_at` (string): Nakit Yükleme Oluşturulma Tarihi ### Response 404 - `message` (string): --- # Nakit Yükleme - İşlem Geçmişi (https://docs.altpay.dev/waas/(nakit-yukleme)/waas-cash-deposit-list) **GET** `/waas/integration/cash-deposits/list` - Bu servis ile cüzdan kullanıcılarınızın ve şirketinizin nakit yükleme geçmişini görüntüleyebilirsiniz. ### Parametreler - `start_date` (string, zorunlu, query): Filtrelemek istenen başlangıç tarihi. - `end_date` (string, zorunlu, query): Filtrelemek istenen bitiş tarihi. - `user_mapping_id` (string, query): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. - `page` (integer, query): Listelenmek istenen sayfa numarası. ### Response 200 - `data` (array): - `id` (integer): ID (ornek: 1) - `user_mapping_id` (string): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "i9c4859e8-5e97-47ca-b65c-4aaa5ae50cab") - `reference_code` (integer): Referans Kodu (ornek: 831677) - `order_id` (string): Sipariş Numarası (ornek: "2226203566") - `status` (object): - `status_translate` (object): - `method` (string): Yükleme metodu [cash, credit_card] (ornek: "cash") - `amount` (number): Yükleme İşlem Tutarı (ornek: 1.23) - `created_at` (string): Nakit Yükleme Oluşturulma Tarihi - `meta` (object): --- # Paketler ve Abonelikler - Satın Alınan Kullanılabilir Paketler (https://docs.altpay.dev/waas/(paketler-ve-abonelikler)/waas-purchased-packages) **GET** `/waas/integration/purchased-packages/{userMappingId}` - Belirtilen linkleme id'ye ait kullanıcının satın aldığı ve kullanılabilir paket ve aboneliklerin listesini döner. ### Parametreler - `userMappingId` (string, zorunlu, path): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `page` (integer, query): Listelenmek istenen sayfa numarası. ### Response 200 - `data` (array): - `id` (integer): ID (ornek: 188) - `usage_limit` (integer): Kullanım limiti (ornek: null) - `balance` (integer): Kalan kullanım hakkı (ornek: null) - `used` (integer): Kullanılan kullanım hakkı (ornek: 0) - `total_earned_discount` (number): Toplam kazanılan indirim (ornek: 1.23) - `expired_at` (string): Son kullanma tarihi (ornek: null) - `start_date` (string): Başlangıç tarihi (ornek: "2025-08-18T21:00:00.000000Z") - `end_date` (string): Bitiş tarihi (ornek: "2028-02-19T20:59:59.000000Z") - `quantity` (integer): Satın alınan adet (ornek: 1) - `package_price` (number): Paket birim fiyatı (ornek: 20) - `total_package_price` (number): Satış tutarı (quantity * package_price) (ornek: 20) - `package` (object): - `id` (integer): Paket ID (ornek: 1) - `name` (string): Paket adı (ornek: "Premium Paket") - `description` (string): Paket açıklaması (ornek: "Detaylı paket açıklaması") - `short_description` (string): Kısa paket açıklaması (ornek: "Kısa açıklama") - `category` (string): Paket kategorisi [package, subscription] (ornek: "subscription") - `schedule_available` (boolean): Özel zamanlı paket ise paketin kullanılabilir olup olmadığı bilgisi - `schedule_message` (boolean): Özel zamanlı paket ise açıklama bilgisi - `meta` (object): ### Response 404 - `message` (string): --- # Puan - Puan Geçmişi (https://docs.altpay.dev/waas/(puan)/waas-point-history) **GET** `/waas/integration/points/histories` - Bu servis ile şirketinize ait tüm cüzdan kullanıcılarının puan geçmişini görüntüleyebilirsiniz. - Tarih filtreleri ile belirli bir dönemdeki tüm kullanıcıların puan geçmişi listelenir. ### Enum Değerleri Ve Açıklamaları #### `point_type` (Puan Tipi) | Enum Değeri | Açıklama | |-------------------------------------|---------------------------------| | `coupon` | Kupon | | `user_coupon` | Kullanıcı Kuponu | | `campaign` | Kampanya | | `payment_discount` | Harcamaya İndirim | | `receivable` | Alacak | | `gift_card` | Hediye Kartı | | `amusement_event` | Eğlence Parkı Etkinliği | | `box_office_predefined_deposit` | Gişe Öntanımlı Yükleme | | `refund` | İade | | `automated_load` | Otomatik Yükleme | | `manual` | Manuel | | `external_point_definition` | Harici Puan Tanımlaması |
#### `point_history_type` (İşlem Tipi) | Enum Değeri | Açıklama | |-----------------|------------------| | `usage` | Harcama | | `load` | Kazanma | | `expire` | Süresi Doldu | | `revoke` | İptal | ### Parametreler - `start_date` (string, query): Filtrelemek istenen başlangıç tarihi. - `end_date` (string, query): Filtrelemek istenen bitiş tarihi. - `page` (integer, query): Listelenmek istenen sayfa numarası. ### Response 200 - `data` (array): - `id` (integer): ID (ornek: 1) - `user_mapping_id` (string): Kullanıcı mapping ID (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `point_type` (string): Puan Tipi [coupon, user_coupon, campaign, payment_discount, receivable, gift_card, amusement_event, box_office_predefined_deposit, refund, automated_load, manual, external_point_definition] (ornek: "campaign") - `point_history_type` (string): İşlem Tipi [usage, load, expire, revoke] (ornek: "load") - `amount` (number): İşlem Tutarı (ornek: 10) - `external_id` (string): Harici Sistem ID (ornek: "EXT-12345") - `created_at` (string): - `meta` (object): --- # QR - QR Oluştur (https://docs.altpay.dev/waas/(qr)/waas-qr-generate) **GET** `/waas/integration/qr/generate` - Bu servis, kullanıcının işlem yapabilmesi için bir qr kodu oluşturur. - QR kodun süresi 120 saniyedir. ### Parametreler - `user_mapping_id` (string, zorunlu, query): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. ### Response 200 - `data` (object): - `id` (integer): Qr ID (ornek: 1) - `reference_code` (string): Qr Kodu (ornek: "ABC123") - `expires_at` (string): Qr Kodunun Sona Erme Tarihi (ornek: "2024-01-18T09:00:00+03:00") - `server_time` (string): Sunucu Zamanı (ornek: "2024-01-15T09:00:00+03:00") ### Response 404 - `message` (string): (ornek: "Kullanıcı Bulunamadı") --- # Temassız Kart - Temassız Kart (https://docs.altpay.dev/waas/(tap-card)/tap-card) Temassız kart, cüzdan kullanıcılarınızın fiziksel bir kartla ödeme ve geçiş yapabilmesini sağlar. Kart bir cüzdan kullanıcısına, yani `user_mapping_id` değerine tanımlanır. Kartla yapılan harcamalar o kullanıcının cüzdanından düşer. Bir kullanıcıya birden fazla kart tanımlanabilir, kartları ayırt etmek için `name` alanı kullanılabilir. Üç servis bulunur: kart tanımlama, kart listeleme ve kart iptali. ## Tipik Akış #### 1) Kart tanımlama Kullanıcı kartın üzerindeki numarayı uygulamanıza girer. Uygulamanızın sunucusu kart tanımlama servisini çağırır ve kart numarasını, kullanıcı linkleme id değerini, isterse kart etiketini gönderir. #### 2) Kart değişimi Kart kaybolduğunda veya yenilendiğinde önce eski kart iptal edilir, ardından yeni kart tanımlanır. Kullanıcının hangi kartlarının aktif olduğunu kart listeleme servisiyle görebilirsiniz. #### 3) Toplu iptal Kartların topluca toplandığı durumlarda tek istekte en fazla 50 kart iptal edilebilir. ## Kısmi Başarı Tanımlama ve iptal servisleri listedeki kartları tek tek işler. Bir kart işlenemezse istek başarısız olmaz, o kart `fails` listesinde sebebiyle birlikte döner, diğer kartlar işlenmeye devam eder. Yanıttaki `success_count` kaç kartın işlendiğini, `fails` hangi kartların neden işlenemediğini gösterir. ```json { "data": { "success_count": 48, "fails": [ { "card_no": "5E6F7G8H", "message": "Kart bulunamadı." }, { "card_no": "9I0J1K2L", "message": "Kart zaten tanımlı, lütfen başka kart deneyiniz." } ] } } ``` ## İptalin Etkisi Kart iptal edildiğinde yalnızca kart pasife alınır. - Kullanıcının cüzdan bakiyesine dokunulmaz. - Kartın depozitosu varsa iade edildi olarak kapatılır, tutar cüzdana yüklenmez. İptal sebebi `lost` ise depozito iade edilmez. - Karta tanımlı harcama limiti varsa kaldırılır. İptal edilen kart bir daha kullanılamaz. Aynı kart numarası daha sonra yeni bir kayıt olarak yeniden tanımlanabilir. --- # Temassız Kart - Kart Tanımlama (https://docs.altpay.dev/waas/(tap-card)/waas-tap-card-bulk-create) **POST** `/waas/integration/tap-card/bulk/create` - Bu servis ile cüzdan kullanıcılarınıza temassız kart tanımlayabilirsiniz. - Tek bir kart tanımlamak için de bu servis kullanılır, `cards` dizisine tek eleman göndermeniz yeterlidir. - Her istekte en fazla **50** kart gönderilebilir. - `name` alanı karta yazılan etikettir. Kartı fiilen kullanan kişiyi ayırt etmek için kullanılabilir. - Kart numarası halihazırda aktif bir karta aitse veya kullanıcı bulunamazsa, o kart `fails` listesinde döner. Listedeki diğer kartlar tanımlanmaya devam eder. - Aynı kart numarası bir istekte iki kez gönderilemez. ### Request Body - `cards` (array, zorunlu): (ornek: [{"card_no":"1A2B3C4D","user_mapping_id":"8b5ac43a-20ce-4987-a739-d8a7ee480eaa","name":"Ayşe Yılmaz"}]) - `card_no` (string, zorunlu): Kart üzerinde yer alan kart numarası. (ornek: "1A2B3C4D") - `user_mapping_id` (string, zorunlu): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `name` (string): Karta yazılacak etiket. Zorunlu değildir. (ornek: "Ayşe Yılmaz") ### Response 200 - `data` (object): - `success_count` (integer): Tanımlanan kart adedi. (ornek: 1) - `fails` (array): Tanımlanamayan kartlar ve sebepleri. (ornek: []) - `card_no` (string): (ornek: "1A2B3C4D") - `user_mapping_id` (string): (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `message` (string): (ornek: "Kart zaten tanımlı, lütfen başka kart deneyiniz.") --- # Temassız Kart - Kart İptali (https://docs.altpay.dev/waas/(tap-card)/waas-tap-card-bulk-reset) **POST** `/waas/integration/tap-card/bulk/reset` - Bu servis ile cüzdan kullanıcılarınıza tanımlı temassız kartları iptal edebilirsiniz. - Tek bir kart iptal etmek için de bu servis kullanılır, `cards` dizisine tek eleman göndermeniz yeterlidir. - Her istekte en fazla **50** kart gönderilebilir. - İptal edilemeyen kartlar `fails` listesinde sebebiyle birlikte döner. Listedeki diğer kartlar iptal edilmeye devam eder. - Aynı kart numarası bir istekte iki kez gönderilemez. - Kart iptali kullanıcının cüzdan bakiyesine dokunmaz. Kartın depozitosu varsa iade edildi olarak kapatılır, tutar cüzdana yüklenmez. İptal sebebi `lost` ise depozito iade edilmez. İptal geri alınamaz. Aynı kart numarası daha sonra yeniden tanımlanabilir, ancak iptal edilen kayıt tekrar aktif edilemez. ### Request Body - `cards` (array, zorunlu): İptal edilecek kart numaraları. (ornek: ["1A2B3C4D","5E6F7G8H"]) - `reason` (string): İptal sebebi. Gönderilmezse `refund` kabul edilir. | Değer | Açıklama | | --- | --- | | `refund` | Kart iade edildi | | `lost` | Kart kayıp | [refund, lost] (ornek: "refund") ### Response 200 - `data` (object): - `success_count` (integer): İptal edilen kart adedi. (ornek: 1) - `fails` (array): İptal edilemeyen kartlar ve sebepleri. (ornek: [{"card_no":"5E6F7G8H","message":"Kart bulunamadı."}]) - `card_no` (string): (ornek: "5E6F7G8H") - `message` (string): (ornek: "Kart bulunamadı.") --- # Temassız Kart - Kart Listesi (https://docs.altpay.dev/waas/(tap-card)/waas-tap-card-list) **GET** `/waas/integration/tap-card/list` - Bu servis ile bir cüzdan kullanıcısına tanımlı **aktif** kartları listeleyebilirsiniz. - İptal edilmiş kartlar listede yer almaz. - Kartlar en yeniden eskiye doğru sıralanır. ### Parametreler - `user_mapping_id` (string, zorunlu, query): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. ### Response 200 - `data` (array): - `card_no` (string): Kart üzerinde yer alan kart numarası. (ornek: "1A2B3C4D") - `name` (string): Karta yazılan etiket. (ornek: "Ayşe Yılmaz") - `type` (string): Kart tipi. [magnetic, bracelet] (ornek: "magnetic") - `last_used_at` (string): Kartın son kullanıldığı tarih. (ornek: "2026-01-15T10:30:00.000000Z") - `created_at` (string): Kartın tanımlandığı tarih. (ornek: "2026-01-01T09:00:00.000000Z") ### Response 404 - `message` (string): (ornek: "Kullanıcı bulunamadı") --- # Zamanlanmış Puan - Toplu Oluşturma (https://docs.altpay.dev/waas/(zamanlanmis-puan)/waas-scheduled-point-bulk-create) **POST** `/waas/integration/points/scheduled-points/create-bulk` - Bu servis ile kullanıcılarınıza zamanlanmış puan tanımlamaları toplu olarak oluşturabilirsiniz. - Maksimum 50 adet zamanlanmış puan tanımlaması gönderilebilir. - İstek içerisindeki her bir zamanlanmış puan tanımlaması için aşağıdaki kontroller yapılır: - `user_mapping_id` değerinin geçerliliği kontrol edilir - `external_id` değerinin daha önce kullanılmamış olması kontrol edilir - Geçersiz `user_mapping_id` değerleri için işlem yapılmaz ve `failed_user_mapping_ids` içinde döner. - Daha önce kullanılmış `external_id` değerleri için işlem yapılmaz ve `failed_external_ids` içinde döner. - Geçerli `user_mapping_id` ve benzersiz `external_id` değerleri için işlem asenkron olarak gerçekleştirilir. - Response içerisinde: - `queued_user_mapping_ids`: Kuyruğa alınan kullanıcı mapping id'leri - `queued_external_ids`: Kuyruğa alınan external id'leri - `failed_user_mapping_ids`: Geçersiz kullanıcı mapping id'leri - `failed_external_ids`: Daha önce kullanılmış veya duplicate olan external id'leri ### Önemli Notlar - `grant_date` bugünden önce olamaz ve `expire_date`'den önce olmalıdır - `expire_date` bugünden sonra olmalıdır - `external_id` değeri benzersiz olmalıdır. Aynı `external_id` ile daha önce oluşturulmuş bir zamanlanmış puan tanımlaması varsa, bu istek reddedilir ### Request Body - `scheduled_points` (array, zorunlu): (ornek: [{"user_mapping_id":"8b5ac43a-20ce-4987-a739-d8a7ee480eaa","expire_date":"2025-12-31","grant_date":"2025-01-15","amount":100,"name":"Özel kampanya puanı","external_id":"EXT-12345"}]) - `user_mapping_id` (string, zorunlu): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `expire_date` (string, zorunlu): Puan son kullanma tarihi (ornek: "2025-12-31") - `grant_date` (string, zorunlu): Puan verilme tarihi (ornek: "2025-01-15") - `amount` (number, zorunlu): Puan tutarı (ornek: 100) - `name` (string): Zamanlanmış puan tanımlaması adı (ornek: "Özel kampanya puanı") - `external_id` (string, zorunlu): Harici sistem ID. (ornek: "EXT-12345") ### Response 200 - `data` (object): - `queued_user_mapping_ids` (array): Kuyruğa alınan kullanıcı mapping id'leri. Bu id'lere ait zamanlanmış puan tanımlamaları asenkron olarak işleme alınacaktır. (ornek: ["8b5ac43a-20ce-4987-a739-d8a7ee480eaa","9c6bd54b-31df-5098-b840-e9b8ff591fbb"]) - `queued_external_ids` (array): Kuyruğa alınan external id'leri. Bu id'lere ait zamanlanmış puan tanımlamaları asenkron olarak işleme alınacaktır. (ornek: ["EXT-12345","EXT-12346"]) - `failed_user_mapping_ids` (array): Geçersiz kullanıcı mapping id'leri. Bu id'lere ait zamanlanmış puan tanımlamaları oluşturulmayacaktır. (ornek: []) - `failed_external_ids` (array): Daha önce kullanılmış veya duplicate olan external id'leri. Bu id'lere ait zamanlanmış puan tanımlamaları oluşturulmayacaktır. (ornek: []) --- # Zamanlanmış Puan - Zamanlanmış Puan Listesi (https://docs.altpay.dev/waas/(zamanlanmis-puan)/waas-scheduled-point-list) **GET** `/waas/integration/points/scheduled-points/list` - Bu servis ile şirketinize ait tüm zamanlanmış puan tanımlamalarını listeleyebilirsiniz. - Tarih filtreleri ile belirli bir dönemdeki zamanlanmış puanlar `grant_date` alanına göre filtrelenir. ### Enum Değerleri Ve Açıklamaları #### `status` (Durum) | Enum Değeri | Açıklama | |---------------|------------------| | `waiting` | Beklemede | | `processed` | İşlendi | | `expired` | Süresi Doldu | | `cancelled` | İptal Edildi | ### Parametreler - `start_date` (string, zorunlu, query): Filtrelemek istenen başlangıç tarihi. - `end_date` (string, zorunlu, query): Filtrelemek istenen bitiş tarihi. - `page` (integer, query): Listelenmek istenen sayfa numarası. ### Response 200 - `data` (array): - `id` (integer): ID (ornek: 1) - `user_mapping_id` (string): Kullanıcı mapping ID (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `title` (string): Zamanlanmış puan başlığı (ornek: "Özel kampanya puanı") - `external_id` (string): Harici sistem ID (ornek: "EXT-12345") - `status` (string): Durum [waiting, processed, expired, cancelled] (ornek: "waiting") - `amount` (number): Puan tutarı (ornek: 100) - `created_at` (string): - `grant_date` (string): Puan verilme tarihi (ornek: "2025-01-15T00:00:00.000000Z") - `expire_date` (string): Puan son kullanma tarihi (ornek: "2025-12-31T00:00:00.000000Z") - `meta` (object): --- # Zamanlanmış Puan - Güncelleme (https://docs.altpay.dev/waas/(zamanlanmis-puan)/waas-scheduled-point-update) **PUT** `/waas/integration/points/scheduled-points/update` - Bu servis ile daha önce oluşturulmuş zamanlanmış puan tanımlamasını güncelleyebilirsiniz. - Sadece gönderilen alanlar güncellenir, gönderilmeyen alanlar değişmez. - `amount` değeri ile zamanlanmış puan tutarı eksiltilebilir: - **Negatif değer:** Mevcut puan tutarından çıkarılır. Sonuç 0'a ulaşırsa zamanlanmış puan iptal edilir. - Çıkarılmak istenen tutar mevcut tutardan fazla olamaz. ### Önemli Notlar - `grant_date` bugünden önce olamaz ve `expire_date`'den önce olmalıdır - `expire_date` bugünden sonra olmalıdır - `external_id` ile zamanlanmış puan bulunur - Zamanlanmış puan sadece `WAITING` durumundayken güncellenebilir - `amount` sadece negatif değer veya 0 kabul eder, pozitif değer gönderilemez ### Request Body - `external_id` (string, zorunlu): Harici sistem ID (ornek: "EXT-12345") - `amount` (number): Eksiltilecek puan tutarı. Negatif değer gönderilir, mevcut tutardan çıkarılır. Sonuç 0'a ulaşırsa zamanlanmış puan iptal edilir. (ornek: -50) - `grant_date` (string): Puan verilme tarihi (ornek: "2025-01-20") - `expire_date` (string): Puan son kullanma tarihi (ornek: "2025-12-31") - `name` (string): Zamanlanmış puan tanımlaması adı (ornek: "Güncellenmiş kampanya puanı") ### Response 200 - `data` (object): - `success` (boolean): (ornek: true) ### Response 400 - `message` (string): (ornek: "Eksiltmek istediğiniz puan mevcut puan tutarından fazla.") ### Response 404 - `message` (string): (ornek: "Zamanlanmış puan bulunamadı") --- # iFramesiz Kullanım (https://docs.altpay.dev/waas/open-without-iframe) iFramesiz Kullanım, WaaS entegrasyonunun bir parçası olarak kullanıcılara sunulan bir seçenektir. Bu yöntem, kullanıcıların cüzdan fonksiyonlarını doğrudan uygulamalarında gerçekleştirmelerine olanak tanır. ### Nasıl Kullanılır? Bu yöntemde, cüzdan entegrasyonu için gerekli adımlar sizin tarafınızdan yapılmalıdır. - Öncelikle [Başlarken](/) bölümünde belirtildiği gibi tüm istekler size iletilen Token ile yapılmalıdır. - Kullanıcı linkleme ve oluşturma gibi cüzdan işlemleri doğrudan sizin uygulamanızda gerçekleştirilir. - [Doğrudan ödeme](/waas/direct-payment) için önce ödeme kontrolü adımları uygulanır, ardından ödeme servisiyle işlem tamamlanır. - Kullanıcı servisleri ile kullanıcıların cüzdan hesapları oluşturulur ve yönetilir. - Kullanıcılarınızın cüzdan bilgileri cüzdan işlemleri servisleri ile yönetilir. --- # Token Kontrolü (https://docs.altpay.dev/waas/waas-check-token) **GET** `/waas/integration/tokens/check/{token}` - [Iframe ile Kullanım](/waas/waas-open-iframe) isteği cevabında verilen "token", ilgili kullanıcıya tanımlanmış ve belirli sürelidir. - Bu servis ile token'ın hangi kullanıcıya ait olduğu, geçerliliği veya kalan süresini kontrol etmek için kullanılabilir. ### Parametreler - `token` (string, zorunlu, path): open-iframe isteği sonucunda verilen token bilgisi (ornek: "eyJpdiI6Imx0QW10cjc1T01aOVh0UURzQzRYaUE9PSIsInZhbHVlIjoiUldiYzN4QlFNZzhjdnpzVElHeXVHVUgxOWlHMm44a1R5TmY0bzBFSGV6SGFGelR4ck93aXRmRzRXRGplcFZxbEM5R1BHaHlUWWNqcktPTTJDTTZrS1Z6N0NGVVp3S2pHL05DV04xTVZBRkptZE9LOVhkL0MzR2drT1VaOUlVSWwiLCJtYWMiOiI5NGJlMDlmYmExNTA1NjY2MjAzYTg2MzIzMjI5ZjFiNGU1ZTI4YjQxZTBhOTM4OTkwMTFhM2RiYWQ4MjQwZjI3IiwidGFnIjoiIn0=") ### Response 200 - `data` (object): - `app_url` (string): Cüzdan uygulamasını iframe de göstermek için girilecek url bilgisi (ornek: "https://waas.altpay.dev/init?token=eyJpdiI6Imx0QW10cjc1T01aOVh0UURzQzRYaUE9PSIsInZhbHVlIjoiUldiYzN4QlFNZzhjdnpzVElHeXVHVUgxOWlHMm44a1R5TmY0bzBFSGV6SGFGelR4ck93aXRmRzRXRGplcFZxbEM5R1BHaHlUWWNqcktPTTJDTTZrS1Z6N0NGVVp3S2pHL05DV04xTVZBRkptZE9LOVhkL0MzR2drT1VaOUlVSWwiLCJtYWMiOiI5NGJlMDlmYmExNTA1NjY2MjAzYTg2MzIzMjI5ZjFiNGU1ZTI4YjQxZTBhOTM4OTkwMTFhM2RiYWQ4MjQwZjI3IiwidGFnIjoiIn0=") - `token` (string): (ornek: "eyJpdiI6Imx0QW10cjc1T01aOVh0UURzQzRYaUE9PSIsInZhbHVlIjoiUldiYzN4QlFNZzhjdnpzVElHeXVHVUgxOWlHMm44a1R5TmY0bzBFSGV6SGFGelR4ck93aXRmRzRXRGplcFZxbEM5R1BHaHlUWWNqcktPTTJDTTZrS1Z6N0NGVVp3S2pHL05DV04xTVZBRkptZE9LOVhkL0MzR2drT1VaOUlVSWwiLCJtYWMiOiI5NGJlMDlmYmExNTA1NjY2MjAzYTg2MzIzMjI5ZjFiNGU1ZTI4YjQxZTBhOTM4OTkwMTFhM2RiYWQ4MjQwZjI3IiwidGFnIjoiIn0=") - `created_at` (string): Token'ın oluşturulma tarihi (ornek: "2025-01-15T06:00:00.000Z") - `expires_at` (string): Token'ın sona erme tarihi (ornek: "2025-01-18T06:00:00.000Z") - `platform` (string): Token'ın hangi platform için oluşturulduğu bilgisi [mobile_waas, web_waas] (ornek: "mobile_waas") - `user` (object): Cüzdan sahibinin bilgilerini içerir. - `mapping` (object): - `id` (string): Kullanıcıya ait linkleme id değeri. (Iframe açma, ödeme gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `wallet_id` (integer): Cüzdanın id numarasını belirtir. (ornek: 1) - `is_active` (boolean): Cüzdanın aktif-pasif durumunu belirtir. Pasif cüzdanlar waas uygulamasını kullanamaz. (ornek: true) - `created_at` (string): - `id` (string): Cüzdan sahibinin SuperApp id numarasını belirtir. (ornek: "25809faf-9f21-40c8-bebe-3dd4e343b446") - `first_name` (string): Cüzdan sahibinin adını belirtir. (ornek: "AB****") - `last_name` (string): Cüzdan sahibinin soyadını belirtir. (ornek: "CD****") - `email` (string): Cüzdan sahibinin e-mail adresini belirtir. (ornek: "ab*****@test.com") - `phone` (string): Cüzdan sahibinin telefon numarasını belirtir. (ornek: "90***********") - `locale` (string): Kullanıcının dil bilgisi (ornek: "tr") ### Response 401 - `message` (string): --- # iFrame ile Kullanım (https://docs.altpay.dev/waas/waas-open-iframe) **POST** `/waas/integration/open-iframe` - Mobil uygulamanızda belirttiğiniz kullanıcı ile cüzdan uygulamasını açmak için kullanılır. - Servis başarılı bir şekilde çağrıldıktan sonra, üretilen url **3 gün** süre ile geçerli olacaktır. - Bu sebepten üretilen url için backend servisinizde 3 gün kontrolü yapabilir ve 3 gün süre geçmeden yeni link alınabilir. ### Parametreler - `X-Waas-Platform` (string, zorunlu, header): Waas platform bilgisi. Geçerli değerler: mobile_waas, web_waas ### Request Body - `user_mapping_id` (string, zorunlu): Kullanıcı oluşturma veya linkleme aşamasında size iletilen ilgili kullanıcıya ait linkleme id değeri. (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `locale` (string): Iframe ve kullanıcının dil değeri [tr, en] (ornek: "tr") - `redirect_page` (string): Kullanıcıyı cüzdan uygulamasında yönlendirmek istediğiniz sayfa [home, deposit, products, orders, address, gift_card, payment, balance_history, qr_content] (ornek: "home") - `redirect_data` (object): - `amount` (number): deposit sayfasına yönlendirmek istediğinizde yüklenmek istenen tutar datası (ornek: 10) - `qr_content` (string): qr_content sayfasına yönlendirmek istediğinizde otomatik olarak çözümlenecek QR içeriği veya referans kodu datası. Çözümleme başarısız olursa uygulama `INVALID_QR` PostMessage olayını iletir. (ornek: "123456") ### Response 200 - `data` (object): - `app_url` (string): Cüzdan uygulamasını iframe de göstermek için girilecek url bilgisi (ornek: "https://waas.altpay.dev/init?token=eyJpdiI6IjZJR3J0YkgzblNsbDRBdTBEbUZjckE9PSIsInZhbHVlIjoiUnprWXRxMDJsSFFRMExZTTVQWXptNnE4N1Y2QTlIVVk3Z0ZyTThVaElCRTkzM1ZJWDQ0K3ZHMDVpQThqT2tmc2RTeXlLeWZMUG9kYU1Ib2VpU3JFVUQrTkhzWW95NDRxQW40Njh6QkEzK1U9IiwibWFjIjoiYzQ5NmFjODU0MDRjNWFiNmRlMTNiMjMwMTRhNDg2Nzc3Y2I5ZWNkNTcyNWVlZGRkZjhmMjNmNmNiMWIwNDU0NSIsInRhZyI6IiJ9") - `token` (string): (ornek: "eyJpdiI6IjZJR3J0YkgzblNsbDRBdTBEbUZjckE9PSIsInZhbHVlIjoiUnprWXRxMDJsSFFRMExZTTVQWXptNnE4N1Y2QTlIVVk3Z0ZyTThVaElCRTkzM1ZJWDQ0K3ZHMDVpQThqT2tmc2RTeXlLeWZMUG9kYU1Ib2VpU3JFVUQrTkhzWW95NDRxQW40Njh6QkEzK1U9IiwibWFjIjoiYzQ5NmFjODU0MDRjNWFiNmRlMTNiMjMwMTRhNDg2Nzc3Y2I5ZWNkNTcyNWVlZGRkZjhmMjNmNmNiMWIwNDU0NSIsInRhZyI6IiJ9") - `expires_at` (string): Token'ın sona erme tarihi (ornek: "2025-01-18T06:00:00.000Z") - `user` (object): Cüzdan sahibinin bilgilerini içerir. - `mapping` (object): - `id` (string): Kullanıcıya ait linkleme id değeri. (Iframe açma, ödeme gibi waas ile ilgili işlemlerde kullanılmaktadır) (ornek: "8b5ac43a-20ce-4987-a739-d8a7ee480eaa") - `wallet_id` (integer): Cüzdanın id numarasını belirtir. (ornek: 1) - `is_active` (boolean): Cüzdanın aktif-pasif durumunu belirtir. Pasif cüzdanlar waas uygulamasını kullanamaz. (ornek: true) - `created_at` (string): - `id` (string): Cüzdan sahibinin SuperApp id numarasını belirtir. (ornek: "25809faf-9f21-40c8-bebe-3dd4e343b446") - `first_name` (string): Cüzdan sahibinin adını belirtir. (ornek: "AB****") - `last_name` (string): Cüzdan sahibinin soyadını belirtir. (ornek: "CD****") - `email` (string): Cüzdan sahibinin e-mail adresini belirtir. (ornek: "ab*****@test.com") - `phone` (string): Cüzdan sahibinin telefon numarasını belirtir. (ornek: "90***********") - `locale` (string): Kullanıcının dil bilgisi (ornek: "tr") ### Response 404 - `message` (string): --- # Webhook (https://docs.altpay.dev/webhooks) Webhook, bir sistemde gerçekleşen bir olayın ardından, belirlenen bir URL'ye otomatik olarak HTTP isteği gönderilmesiyle başka bir sistemi bilgilendiren bir mekanizmadır. ## Webhook URL Webhook'lar, belirli bir URL üzerinden gelen POST istekleri ile kabul edilir. Örneğin, webhook URL'iniz şu şekilde olabilir: https://example.com/webhooks/receive Bu URL, Macellan SuperApp'te belirli olaylar tetiklendiğinde sisteminize veri göndermek için kullanılacaktır. ### Webhook Request Formatı Macellan SuperApp webhook isteklerini (request body) aşağıdaki formatta göndermektedir. ```json { "event": "payment_complete", "user": { "id": 1, "uuid": "a08a39ed-78c5-43dc-ae5c-161e50a634fd", "region": "TR", "locale": "tr", "first_name": "Macellan", "last_name": "Superapp", "full_name": "Macellan SuperApp", "email": "altdev@macellan.net", "phone": 905231113344, "details": { "subscribe_sms": false, "subscribe_email": false, "gender": "male", "id_number": 11111111111 } }, "waas_user_mapping": null, "data": {} } ``` ## Webhook İmza Doğrulaması Tarafımıza bildirdiğiniz webhook URL'inizin güvenliğini sağlamak için, gelen isteğin gerçekten Macellan SuperApp tarafından gönderildiğini doğrulamanız gerekir. Macellan SuperApp, webhook isteklerinde `Signature` header'ında SHA-256 ile HMAC'lenmiş bir değer gönderir. Bu değer, request body'nin bize ilettiğiniz `Secret Key` ile imzalanmasıyla elde edilir. Örnek request doğrulaması: ## Webhook Başarı ve Başarısız Durumları Macellan SuperApp, webhook isteği işlendiğinde sisteminizin `200` HTTP durumu döndürmesini bekler. `200` dönülmezse aynı istek en fazla 3 kez daha yeniden gönderilir. --- # Nakit Yükleme İadesi (https://docs.altpay.dev/webhooks/cash-deposit-refund) **WEBHOOK** `cashDepositRefund` Şirketinize ait cüzdanlarda nakit yükleme iadesi işlemi sonrası tetiklenir. ### Webhook Body - `event` (string): - `user` (object): - `id` (integer): Kullanıcı id bilgisi (ornek: 1) - `uuid` (string): Kullanıcı uuid bilgisi (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `region` (string): Kullanıcı bölgesi [TR, AZ] (ornek: "TR") - `locale` (string): Kullanıcı bölgesi [tr, en, az, ru] (ornek: "tr") - `first_name` (string): Kullanıcı ad bilgisi (ornek: "Macellan") - `last_name` (string): Kullanıcı soyad bilgisi (ornek: "Superapp") - `full_name` (string): Kullanıcı ad-soyad bilgisi (ornek: "Macellan SuperApp") - `email` (string): (ornek: "altdev@macellan.net") - `phone` (string): Kullanıcı telefon bilgisi (ornek: 905231113344) - `details` (object): - `subscribe_sms` (boolean): Sms iletişim izni (ornek: false) - `subscribe_email` (boolean): Email iletişim izni (ornek: false) - `gender` (string): Cinsiyet [male, female, prefer_not_respond] (ornek: "male") - `id_number` (string): Kimlik Numarası (ornek: 11111111111) - `waas_user_mapping` (object): - `id` (string): (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `is_active` (boolean): (ornek: true) - `created_at` (string): Tarih - `data` (object): - `id` (integer): (ornek: 1) - `status` (string): (ornek: "refund") - `instant_wallet_balance` (number): Kullanıcının iade aşamasında cüzdan bakiyesi (ornek: 1) - `instant_wallet_point` (number): Kullanıcının iade aşamasında puan bakiyesi (ornek: 1) - `balance` (number): İade yapılan cüzdanın bakiyesinden düşülecek toplam bakiye (ornek: 1) - `point` (number): Yüklemeye istinaden geri alınması gereken puan miktarı (ornek: 1) - `point_spent` (number): Kazanılan puan harcanmışsa, toplam harcadığı puan (ornek: 1) - `deposit_amount` (number): Toplam nakit yükleme tutarı (ornek: 1) - `earned_point_amount` (number): Nakit yüklemelerden toplam kazandığı puan (ornek: 1) - `refund_amount` (number): Kullanıcıya iade edilecek toplam tutar (ornek: 1) - `cash_deposits` (array): - `id` (integer): (ornek: 1) - `gateway` (string): Yükleme Geçidi [terminal, static_qr, box_office, kiosk] (ornek: "terminal") - `method` (string): Yükleme metodu [cash, credit_card] (ornek: "cash") - `amount` (number): Yükleme tutarı (ornek: 1) - `reference_code` (integer): Referans Kodu (ornek: 952340) - `order_id` (integer): (ornek: 95234) - `created_at` (string): Yükleme Oluşturulma Tarihi - `branch` (object): - `id` (integer): Id bilgisi (ornek: 1) - `name` (string): Şube adı (ornek: "İstanbul") - `allow_point_usage` (boolean): - `phone` (string): [E.164 Format](https://www.twilio.com/docs/glossary/what-e164) (ornek: "+905231113344") - `code` (string): Şube kodu (ornek: 12345) - `description` (string): Şube açıklaması (ornek: "İstanbul şubesi") - `refund_amount` (number): İade tutarı (ornek: 0) - `rest_amount` (number): (Yükleme Tutarı - İade tutarı) (ornek: 0) - `completed_at` (string): Yükleme Tarihi - `created_at` (string): İade Oluşturulma Tarihi - `reason` (string): İade sebebi (ornek: "wrong_deposit") - `description` (string): --- # Nakit Yükleme İşlemi (https://docs.altpay.dev/webhooks/cash-deposit-success) **WEBHOOK** `cashDepositSuccess` Şirketinize ait cüzdanlara başarılı nakit yükleme işlemi sonrası tetiklenir. ### Webhook Body - `event` (string): - `user` (object): - `id` (integer): Kullanıcı id bilgisi (ornek: 1) - `uuid` (string): Kullanıcı uuid bilgisi (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `region` (string): Kullanıcı bölgesi [TR, AZ] (ornek: "TR") - `locale` (string): Kullanıcı bölgesi [tr, en, az, ru] (ornek: "tr") - `first_name` (string): Kullanıcı ad bilgisi (ornek: "Macellan") - `last_name` (string): Kullanıcı soyad bilgisi (ornek: "Superapp") - `full_name` (string): Kullanıcı ad-soyad bilgisi (ornek: "Macellan SuperApp") - `email` (string): (ornek: "altdev@macellan.net") - `phone` (string): Kullanıcı telefon bilgisi (ornek: 905231113344) - `details` (object): - `subscribe_sms` (boolean): Sms iletişim izni (ornek: false) - `subscribe_email` (boolean): Email iletişim izni (ornek: false) - `gender` (string): Cinsiyet [male, female, prefer_not_respond] (ornek: "male") - `id_number` (string): Kimlik Numarası (ornek: 11111111111) - `waas_user_mapping` (object): - `id` (string): (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `is_active` (boolean): (ornek: true) - `created_at` (string): Tarih - `data` (object): - `id` (integer): (ornek: 1) - `gateway` (string): Yükleme Geçidi [terminal, static_qr, box_office, kiosk] (ornek: "terminal") - `method` (string): Yükleme metodu [cash, credit_card] (ornek: "cash") - `amount` (number): Yükleme tutarı (ornek: 1) - `reference_code` (integer): Referans Kodu (ornek: 952340) - `order_id` (integer): (ornek: 95234) - `created_at` (string): Yükleme Oluşturulma Tarihi - `branch` (object): - `id` (integer): Id bilgisi (ornek: 1) - `name` (string): Şube adı (ornek: "İstanbul") - `allow_point_usage` (boolean): - `phone` (string): [E.164 Format](https://www.twilio.com/docs/glossary/what-e164) (ornek: "+905231113344") - `code` (string): Şube kodu (ornek: 12345) - `description` (string): Şube açıklaması (ornek: "İstanbul şubesi") - `refund_amount` (number): İade tutarı (ornek: 0) - `rest_amount` (number): (Yükleme Tutarı - İade tutarı) (ornek: 0) - `completed_at` (string): Yükleme Tarihi --- # Yükleme İadesi (https://docs.altpay.dev/webhooks/deposit-refund) **WEBHOOK** `depositRefund` Şirketinize ait cüzdanlarda yükleme iadesi işlemi sonrası tetiklenir. ### Webhook Body - `event` (string): - `user` (object): - `id` (integer): Kullanıcı id bilgisi (ornek: 1) - `uuid` (string): Kullanıcı uuid bilgisi (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `region` (string): Kullanıcı bölgesi [TR, AZ] (ornek: "TR") - `locale` (string): Kullanıcı bölgesi [tr, en, az, ru] (ornek: "tr") - `first_name` (string): Kullanıcı ad bilgisi (ornek: "Macellan") - `last_name` (string): Kullanıcı soyad bilgisi (ornek: "Superapp") - `full_name` (string): Kullanıcı ad-soyad bilgisi (ornek: "Macellan SuperApp") - `email` (string): (ornek: "altdev@macellan.net") - `phone` (string): Kullanıcı telefon bilgisi (ornek: 905231113344) - `details` (object): - `subscribe_sms` (boolean): Sms iletişim izni (ornek: false) - `subscribe_email` (boolean): Email iletişim izni (ornek: false) - `gender` (string): Cinsiyet [male, female, prefer_not_respond] (ornek: "male") - `id_number` (string): Kimlik Numarası (ornek: 11111111111) - `waas_user_mapping` (object): - `id` (string): (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `is_active` (boolean): (ornek: true) - `created_at` (string): Tarih - `data` (object): - `id` (integer): (ornek: 1) - `bank_amount` (number): Deposit yapılan karta geri ödenecek tutar. Kullanıcıya iade edilecek tutar (ornek: 1) - `balance` (number): İade yapılan cüzdanın bakiyesinden düşülecek toplam bakiye (ornek: 1) - `point` (number): Yüklemeye istinaden geri alınması gereken puan miktarı (ornek: 1) - `point_deducted_balance` (number): Kazanılan puan harcanmışsa, toplam harcadığı puan (ornek: 1) - `earned_point` (number): Yükleme ile kazanılan toplam puan (ornek: 1) - `instant_wallet_balance` (number): İade anında kullanıcının cüzdan bakiyesi (ornek: 1) - `reference_code` (integer): Referans Kodu (ornek: 952340) - `gateway` (string): Yükleme Geçidi [bkm, masterpass, masterpass_dp, paycell, turkcell_dcb, united_payment, united_payment_dp] (ornek: "masterpass") - `reason` (string): İade sebebi (ornek: "wrong_deposit") - `deposit` (object): - `id` (integer): (ornek: 1) - `gateway` (string): Yükleme Geçidi [bkm, masterpass, masterpass_dp, paycell, turkcell_dcb, united_payment, united_payment_dp] (ornek: "masterpass") - `status` (string): (ornek: "success") - `reference_code` (string): Referans Kodu (ornek: "95234-111523") - `amount` (number): Yükleme tutarı (ornek: 1) - `final_total` (number): Yükleme toplam tutarı (ornek: 1) - `refund_amount` (number): İade tutarı (ornek: 0) - `three_d` (boolean): Ödemenin 3D ile gerçekleştiği bilgisi (ornek: false) - `created_at` (string): Ödeme Oluşturulma Tarihi - `order_id` (string): Order ID - `deposit_time` (string): Ödeme Tarihi - `installment_count` (integer): Taksit sayısı (ornek: 2) - `card_holder` (string): - `card_bin` (string): - `pos_bank_no` (integer): Ödemenin yapıldığı posun banka numarası (ornek: 12) - `message` (string): - `created_at` (string): İade Oluşturulma Tarihi - `refunded_date` (string): İade Tarihi - `user_message` (string): - `bank_message` (string): - `user_comment` (string): --- # Yükleme İşlemi (https://docs.altpay.dev/webhooks/deposit-success) **WEBHOOK** `depositSuccess` Şirketinize ait cüzdanlara başarılı yükleme işlemi sonrası tetiklenir. ### Webhook Body - `event` (string): - `user` (object): - `id` (integer): Kullanıcı id bilgisi (ornek: 1) - `uuid` (string): Kullanıcı uuid bilgisi (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `region` (string): Kullanıcı bölgesi [TR, AZ] (ornek: "TR") - `locale` (string): Kullanıcı bölgesi [tr, en, az, ru] (ornek: "tr") - `first_name` (string): Kullanıcı ad bilgisi (ornek: "Macellan") - `last_name` (string): Kullanıcı soyad bilgisi (ornek: "Superapp") - `full_name` (string): Kullanıcı ad-soyad bilgisi (ornek: "Macellan SuperApp") - `email` (string): (ornek: "altdev@macellan.net") - `phone` (string): Kullanıcı telefon bilgisi (ornek: 905231113344) - `details` (object): - `subscribe_sms` (boolean): Sms iletişim izni (ornek: false) - `subscribe_email` (boolean): Email iletişim izni (ornek: false) - `gender` (string): Cinsiyet [male, female, prefer_not_respond] (ornek: "male") - `id_number` (string): Kimlik Numarası (ornek: 11111111111) - `waas_user_mapping` (object): - `id` (string): (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `is_active` (boolean): (ornek: true) - `created_at` (string): Tarih - `data` (object): - `id` (integer): (ornek: 1) - `gateway` (string): Yükleme Geçidi [bkm, masterpass, masterpass_dp, paycell, turkcell_dcb, united_payment, united_payment_dp] (ornek: "masterpass") - `status` (string): (ornek: "success") - `reference_code` (string): Referans Kodu (ornek: "95234-111523") - `amount` (number): Yükleme tutarı (ornek: 1) - `final_total` (number): Yükleme toplam tutarı (ornek: 1) - `refund_amount` (number): İade tutarı (ornek: 0) - `three_d` (boolean): Ödemenin 3D ile gerçekleştiği bilgisi (ornek: false) - `created_at` (string): Ödeme Oluşturulma Tarihi - `order_id` (string): Order ID - `deposit_time` (string): Ödeme Tarihi - `installment_count` (integer): Taksit sayısı (ornek: 2) - `card_holder` (string): - `card_bin` (string): - `pos_bank_no` (integer): Ödemenin yapıldığı posun banka numarası (ornek: 12) - `message` (string): --- # Webhook Çağrı Logları (https://docs.altpay.dev/webhooks/logs) **GET** `/integration/webhook-logs` Bu endpoint, uygulamanıza gönderilen webhook çağrılarının geçmişini görüntüleyebilmeniz için sunulur. Hangi webhook olaylarının ne zaman tetiklendiğini, gönderilen verileri ve çağrının başarılı olup olmadığını inceleyebilir, entegrasyonlarınızı doğrulamak ve olası sorunları tespit etmek için kullanabilirsiniz. - Log kayıtları son 15 güne ait verileri kapsar. `start_date` parametresi en fazla 15 gün öncesine kadar olan tarihleri kabul eder. - `start_date` parametresi belirtilmediğinde, varsayılan olarak son 1 güne ait kayıtlar listelenir. - Bir webhook çağrısına ait tüm gönderim denemeleri aynı `uuid` ile kaydedilir. `uuid` parametresi ile filtreleme yaparak, ilgili webhook çağrısının kaç kez denendiğini ve her denemeye ait kayıtları görüntüleyebilirsiniz. ### Parametreler - `event` (string, query): Olay (ornek: "deposit_success") - `start_date` (string, query): Başlangıç Tarihi. (ornek: "2026-01-25 13:00:00") - `end_date` (string, query): Bitiş Tarihi (ornek: "2026-01-25 23:59:59") - `uuid` (string, query): Uuid (ornek: "b8dd8e93-d29b-4594-9a7d-d01d6bf89833") - `page` (integer, query): Sayfa (ornek: 1) ### Response 200 - `data` (array): - `id` (string): Benzersiz kimlik bilgisi (ornek: "6942557cbc578eb99eb57902") - `uuid` (string): Uuid bilgisi (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `company_id` (integer): Cüzdanın bağlı olduğu şirket id numarasını belirtir. (ornek: 1) - `event` (string): Olay Bilgisi [deposit_success, deposit_refund, cash_deposit_success, cash_deposit_refund, payment_complete, payment_refund, point_history, waas_user_registered] (ornek: "deposit_success") - `payload` (object): Webhook çağırımında uygulamanıza gönderilen request body içeriği - `is_success` (boolean): Webhook çağırımının başarı durumu (ornek: true) - `attempt` (integer): Webhook çağırımının deneme sayısı (ornek: 1) - `created_at` (string): Webhook çağırımının tarih bilgisi (ornek: "2025-12-17T09:17:35.000Z") - `meta` (object): ### Response 502 - `message` (string): message (ornek: "İşlem başarısız, lütfen tekrar deneyin.") --- # Harcama İşlemi (https://docs.altpay.dev/webhooks/payment-complete) **WEBHOOK** `paymentComplete` Şirketinize ait cüzdanlardan başarılı harcama işlemi sonrası tetiklenir. ### Webhook Body - `event` (string): - `user` (object): - `id` (integer): Kullanıcı id bilgisi (ornek: 1) - `uuid` (string): Kullanıcı uuid bilgisi (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `region` (string): Kullanıcı bölgesi [TR, AZ] (ornek: "TR") - `locale` (string): Kullanıcı bölgesi [tr, en, az, ru] (ornek: "tr") - `first_name` (string): Kullanıcı ad bilgisi (ornek: "Macellan") - `last_name` (string): Kullanıcı soyad bilgisi (ornek: "Superapp") - `full_name` (string): Kullanıcı ad-soyad bilgisi (ornek: "Macellan SuperApp") - `email` (string): (ornek: "altdev@macellan.net") - `phone` (string): Kullanıcı telefon bilgisi (ornek: 905231113344) - `details` (object): - `subscribe_sms` (boolean): Sms iletişim izni (ornek: false) - `subscribe_email` (boolean): Email iletişim izni (ornek: false) - `gender` (string): Cinsiyet [male, female, prefer_not_respond] (ornek: "male") - `id_number` (string): Kimlik Numarası (ornek: 11111111111) - `waas_user_mapping` (object): - `id` (string): (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `is_active` (boolean): (ornek: true) - `created_at` (string): Tarih - `data` (object): - `id` (integer): (ornek: 1) - `paid_price` (number): Ödenen İşlem Tutarı (ornek: 1) - `point` (number): Ödeme Puan Tutarı (ornek: 1) - `final_total` (number): Ödeme Toplam Tutarı(Puan Tutarı + Ödeme Tutarı) (ornek: 1) - `discounted_total_amount` (number): İndirimli toplam tutar (ornek: 1) - `discount_point` (number): İndirim tutarı (ornek: 0) - `refund_amount` (number): İade tutarı (ornek: 0) - `reference_code` (integer): 6 Haneli Ödeme Referans Kodu (ornek: 123456) - `order_id` (integer): Ödeme Unique Sipariş ID (ornek: 1405321795) - `created_at` (string): Ödeme Oluşturulma Tarihi - `gateway` (object): - `branch` (object): - `id` (integer): Id bilgisi (ornek: 1) - `name` (string): Şube adı (ornek: "İstanbul") - `allow_point_usage` (boolean): - `phone` (string): [E.164 Format](https://www.twilio.com/docs/glossary/what-e164) (ornek: "+905231113344") - `code` (string): Şube kodu (ornek: 12345) - `description` (string): Şube açıklaması (ornek: "İstanbul şubesi") - `transaction_code` (string): Ödeme İşlemi Kodu (ornek: "V4SBUQG3PMNLCR0") - `extra` (array): - `external_id` (string): - `payment_time` (string): Ödeme Tarihi - `point_histories` (array): Harcamada kullanılan puan detayları - `id` (integer): (ornek: 1) - `type` (string): Puan işlem tipi [usage, load, expire, revoke] (ornek: "usage") - `amount` (number): Harcanan puan tutarı (ornek: 1) - `payment_id` (integer): İlişkili ödeme ID (ornek: 1) - `created_at` (string): Puan işlemi oluşturulma tarihi - `point` (object): - `id` (integer): (ornek: 1) - `type` (string): Puan tipi. campaign olduğunda campaign alanı dolar. [coupon, user_coupon, campaign, payment_discount, receivable, gift_card, amusement_event, box_office_predefined_deposit, refund, automated_load, manual, external_point_definition] (ornek: "campaign") - `created_at` (string): Puan kaydı oluşturulma tarihi - `campaign` (object): type alanı campaign olduğunda kampanya bilgisi döner, diğer tiplerde null gelir. - `id` (integer): (ornek: 1) - `name` (string): (ornek: "Yaz Kampanyası") - `type` (string): [deposit_gift, payment_count_gift, cross_marketing_deposit_gift, payment_discount] (ornek: "deposit_gift") - `code` (string): (ornek: "SUMMER2026") --- # Harcama İadesi (https://docs.altpay.dev/webhooks/payment-refund) **WEBHOOK** `paymentRefund` Şirketinize ait cüzdanlardan harcama iadesi işlemi sonrası tetiklenir. ### Webhook Body - `event` (string): - `user` (object): - `id` (integer): Kullanıcı id bilgisi (ornek: 1) - `uuid` (string): Kullanıcı uuid bilgisi (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `region` (string): Kullanıcı bölgesi [TR, AZ] (ornek: "TR") - `locale` (string): Kullanıcı bölgesi [tr, en, az, ru] (ornek: "tr") - `first_name` (string): Kullanıcı ad bilgisi (ornek: "Macellan") - `last_name` (string): Kullanıcı soyad bilgisi (ornek: "Superapp") - `full_name` (string): Kullanıcı ad-soyad bilgisi (ornek: "Macellan SuperApp") - `email` (string): (ornek: "altdev@macellan.net") - `phone` (string): Kullanıcı telefon bilgisi (ornek: 905231113344) - `details` (object): - `subscribe_sms` (boolean): Sms iletişim izni (ornek: false) - `subscribe_email` (boolean): Email iletişim izni (ornek: false) - `gender` (string): Cinsiyet [male, female, prefer_not_respond] (ornek: "male") - `id_number` (string): Kimlik Numarası (ornek: 11111111111) - `waas_user_mapping` (object): - `id` (string): (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `is_active` (boolean): (ornek: true) - `created_at` (string): Tarih - `data` (object): - `id` (integer): (ornek: 1) - `type` (string): [full_refund, partial_refund] (ornek: "full_refund") - `amount` (number): Bakiye İade tutarı (ornek: 1) - `point` (number): Puan İade Tutarı (ornek: 1) - `final_total` (number): Toplam İade Tutarı (ornek: 1) - `payment` (object): - `id` (integer): (ornek: 1) - `paid_price` (number): Ödenen İşlem Tutarı (ornek: 1) - `point` (number): Ödeme Puan Tutarı (ornek: 1) - `final_total` (number): Ödeme Toplam Tutarı(Puan Tutarı + Ödeme Tutarı) (ornek: 1) - `discounted_total_amount` (number): İndirimli toplam tutar (ornek: 1) - `discount_point` (number): İndirim tutarı (ornek: 0) - `refund_amount` (number): İade tutarı (ornek: 0) - `reference_code` (integer): 6 Haneli Ödeme Referans Kodu (ornek: 123456) - `order_id` (integer): Ödeme Unique Sipariş ID (ornek: 1405321795) - `created_at` (string): Ödeme Oluşturulma Tarihi - `gateway` (object): - `branch` (object): - `id` (integer): Id bilgisi (ornek: 1) - `name` (string): Şube adı (ornek: "İstanbul") - `allow_point_usage` (boolean): - `phone` (string): [E.164 Format](https://www.twilio.com/docs/glossary/what-e164) (ornek: "+905231113344") - `code` (string): Şube kodu (ornek: 12345) - `description` (string): Şube açıklaması (ornek: "İstanbul şubesi") - `transaction_code` (string): Ödeme İşlemi Kodu (ornek: "V4SBUQG3PMNLCR0") - `extra` (array): - `external_id` (string): - `payment_time` (string): Ödeme Tarihi - `point_histories` (array): Harcamada kullanılan puan detayları - `id` (integer): (ornek: 1) - `type` (string): Puan işlem tipi [usage, load, expire, revoke] (ornek: "usage") - `amount` (number): Harcanan puan tutarı (ornek: 1) - `payment_id` (integer): İlişkili ödeme ID (ornek: 1) - `created_at` (string): Puan işlemi oluşturulma tarihi - `point` (object): - `id` (integer): (ornek: 1) - `type` (string): Puan tipi. campaign olduğunda campaign alanı dolar. [coupon, user_coupon, campaign, payment_discount, receivable, gift_card, amusement_event, box_office_predefined_deposit, refund, automated_load, manual, external_point_definition] (ornek: "campaign") - `created_at` (string): Puan kaydı oluşturulma tarihi - `campaign` (object): type alanı campaign olduğunda kampanya bilgisi döner, diğer tiplerde null gelir. - `id` (integer): (ornek: 1) - `name` (string): (ornek: "Yaz Kampanyası") - `type` (string): [deposit_gift, payment_count_gift, cross_marketing_deposit_gift, payment_discount] (ornek: "deposit_gift") - `code` (string): (ornek: "SUMMER2026") - `created_at` (string): İade Oluşturulma Tarihi --- # Puan Kaydı İşlemi (https://docs.altpay.dev/webhooks/point-history) **WEBHOOK** `pointHistory` Şirketinize ait cüzdanlarda puan işlemi gerçekleştiğinde tetiklenir. ### Webhook Body - `event` (string): - `user` (object): - `id` (integer): Kullanıcı id bilgisi (ornek: 1) - `uuid` (string): Kullanıcı uuid bilgisi (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `region` (string): Kullanıcı bölgesi [TR, AZ] (ornek: "TR") - `locale` (string): Kullanıcı bölgesi [tr, en, az, ru] (ornek: "tr") - `first_name` (string): Kullanıcı ad bilgisi (ornek: "Macellan") - `last_name` (string): Kullanıcı soyad bilgisi (ornek: "Superapp") - `full_name` (string): Kullanıcı ad-soyad bilgisi (ornek: "Macellan SuperApp") - `email` (string): (ornek: "altdev@macellan.net") - `phone` (string): Kullanıcı telefon bilgisi (ornek: 905231113344) - `details` (object): - `subscribe_sms` (boolean): Sms iletişim izni (ornek: false) - `subscribe_email` (boolean): Email iletişim izni (ornek: false) - `gender` (string): Cinsiyet [male, female, prefer_not_respond] (ornek: "male") - `id_number` (string): Kimlik Numarası (ornek: 11111111111) - `waas_user_mapping` (object): - `id` (string): (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `is_active` (boolean): (ornek: true) - `created_at` (string): Tarih - `data` (object): - `id` (integer): (ornek: 1) - `type` (string): Puan işlem tipi [usage, load, expire, revoke] (ornek: "usage") - `payment_id` (integer): İlişkili ödeme ID (ornek: 1) - `amount` (number): İşlem tutarı (ornek: 1) - `point` (object): - `id` (integer): (ornek: 1) - `type` (string): Puan tipi. campaign olduğunda campaign alanı dolar. [coupon, user_coupon, campaign, payment_discount, receivable, gift_card, amusement_event, box_office_predefined_deposit, refund, automated_load, manual, external_point_definition] (ornek: "campaign") - `created_at` (string): Puan kaydı oluşturulma tarihi - `campaign` (object): type alanı campaign olduğunda kampanya bilgisi döner, diğer tiplerde null gelir. - `id` (integer): (ornek: 1) - `name` (string): (ornek: "Yaz Kampanyası") - `type` (string): [deposit_gift, payment_count_gift, cross_marketing_deposit_gift, payment_discount] (ornek: "deposit_gift") - `code` (string): (ornek: "SUMMER2026") - `created_at` (string): Puan işlemi oluşturulma tarihi --- # Waas Kullanıcı Kaydı (https://docs.altpay.dev/webhooks/waas-user-registered) **WEBHOOK** `waasUserRegistered` Waas entegrasyon servisi ile kullanıcı kaydı gerçekleştirildikten sonra tetiklenir. ### Webhook Body - `event` (string): - `user` (object): - `id` (integer): Kullanıcı id bilgisi (ornek: 1) - `uuid` (string): Kullanıcı uuid bilgisi (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `region` (string): Kullanıcı bölgesi [TR, AZ] (ornek: "TR") - `locale` (string): Kullanıcı bölgesi [tr, en, az, ru] (ornek: "tr") - `first_name` (string): Kullanıcı ad bilgisi (ornek: "Macellan") - `last_name` (string): Kullanıcı soyad bilgisi (ornek: "Superapp") - `full_name` (string): Kullanıcı ad-soyad bilgisi (ornek: "Macellan SuperApp") - `email` (string): (ornek: "altdev@macellan.net") - `phone` (string): Kullanıcı telefon bilgisi (ornek: 905231113344) - `details` (object): - `subscribe_sms` (boolean): Sms iletişim izni (ornek: false) - `subscribe_email` (boolean): Email iletişim izni (ornek: false) - `gender` (string): Cinsiyet [male, female, prefer_not_respond] (ornek: "male") - `id_number` (string): Kimlik Numarası (ornek: 11111111111) - `waas_user_mapping` (object): - `id` (string): (ornek: "a08a39ed-78c5-43dc-ae5c-161e50a634fd") - `is_active` (boolean): (ornek: true) - `created_at` (string): Tarih - `data` (object): --- # Event Log Ekleme (https://docs.altpay.dev/event-log/add-event-log) **POST** `/integration/event-log/add` Sistem event loglarını kaydetmek için kullanılır. ### Request Body - `identity` (string, zorunlu): Kimlik bilgisi (ornek: "user123") - `source` (string, zorunlu): Kaynak [device-ops, super-device, mobile, main, mobile-masterpass, mobile-ble, admin-panel, kioks] (ornek: "kioks") - `transaction_id` (string): İşlem ID'si (ornek: "TRX123456") - `event` (string, zorunlu): Olay adı (ornek: "card_read") - `message` (string, zorunlu): Olay mesajı (ornek: "Kart başarıyla okundu") - `extra` (object): Ek bilgiler (ornek: {"card_no":"1234567890"}) ### Response 200 - `data` (object): - `success` (boolean): --- # Başlarken (https://docs.altpay.dev/introduction) Bu doküman, Macellan SuperApp API'sine entegre olmanızı kolaylaştırmak için hazırlanmıştır. Entegrasyon sırasında ihtiyacınız olacak terimsel ve teknik ifadelerin tanımları, parametrelerin alabilecekleri değerler ve akış şemaları bu dokümanda yer almaktadır. ## Kimlik Doğrulama ## Hızlı Başlangıç Katkı ve önerileriniz için [support@macellan.app](mailto:support@macellan.app) adresinden bize ulaşabilirsiniz.