iyzico Pazaryeri (Marketplace) Entegrasyonu

E-Ticaret dünyasında Pazaryeri (B2B-Marketplace) altyapıları için sanal POS entegrasyonu son dönemlerde oldukça merak edilen konular arasında yer alıyor. Bu yazımızda sizler için iyzico’ nun Pazaryeri Entegrasyonu’ nu örnek kodlar ile birlikte inceleyeceğiz.

Pazaryeri Nedir? Nasıl Çalışır?

iyzico Pazaryeri çözümünün detaylı açıklaması için 100 TL lik bir alışveriş örneği inceleyelim;

Pazaryeri sistemi altında satış yapan 3 adet Alt Üye İşyeri (satıcı=submerchant) olduğunu varsayalım. Bu alt üye işyerleri bireysel (C2C), şahıs şirketi (B2C) veya tüzel kişilik (B2C) olabilirler. Bir alıcı 100 TL’ lik bir sepet oluşturup 3 farklı satıcıdan, örneğin;

  • A satıcısından 30 TL’lik,
  • B satıcısından 50 TL’lik,
  • C satıcısından 20 TL’lik

3 farklı ürün alabilir. Bilindiği üzere escrow ürün bazındadır; her ürünün satıcısı farklı olabileceği için sepette yer alan her bir ürünün durumu da farklılık gösterebilir. Örneğin A satıcısı ürünü kargolamış, alıcının eline ulaşmış ve ürüne onay verilmiş olabilir. B satıcısının ürünü iade edilmiş/işlem iptal edilmiş; C satıcısının ürünü ise henüz kargo yapılmak üzere bekliyor olabilir.

iyzico, satıcı ve alıcı arasındaki escrow’a müdahil olmaz; ödemenin tahsilatına aracılık eder ve sepetteki ilgili ürün için üye işyerinden para transferine onay verilmesini bekler. Bu süre zarfında alıcının parası bankada korumalı havuz hesapta beklemektedir.

iyzico Pazaryeri çözümü genel olarak para toplama(collection) ve dağıtma(settlement) süreçlerini kapsamaktadır. Entegrasyonda 3 ana adım bulunmaktadır; adımlar sırasıyla şu şekildedir:

  • Alt Üye İşyeri Kaydı
  • Ödeme (API veya Ödeme Formu entegrasyonu tercih edilebilir.)
  • Para Transferi İçin Ürüne Onay Verme

Para transferinin satıcılara (alt üye işyerlerine) yapılabilmesi için bu satıcıların iyzico’ya tek seferlik kaydının yapılması gerekmektedir. Bu da onboarding API ile sağlanır; üye işyeri satıcıyı iyzico’ya kaydettiği anda, istek dönüşünde o satıcı için subMerchantKey alır.

Ödeme esnasında da sepetteki her bir ürünün satıcısı için ilgili subMerchantKey ve bu işlemde satıcıya kaç para gönderilecek ise bu tutar (subMerchantPrice) iletilmelidir.

Alıcı ve Satıcı Sözleşmeleri

Pazaryerinizde ödeme akışı iyzico tarafından kontrol edileceği için, alıcılarınızın ve satıcılarınızın, bir kereye mahsus olmak üzere iyzico sözleşmelerini onaylamaları gerekmektedir. Bunun için iyzico’ nun kendi sayfasında yer alan “Pazaryeri Alıcı” ve “Pazaryeri Satıcı” sözleşmelerini web sitenize ekleyerek en az bir kere alıcı ve satıcıya onaylatmalısınız.

Üyelerinize web siteniz üzerinden iyzico hizmet şartlarını iki ayrı şekilde onaylatabilirsiniz:

  • Üyelik sırasında
  • Ürün listeleme ya da ürün ödeme sayfasında

Her bir üyeniz için bu işlem tek bir defaya mahsustur. iyzico hizmet şartlarını bir önceki listelemesinde ya da ürün ödemesinde kabul etmiş olan üyenizin, sonraki listeleme ya da ödeme aşamalarında sözleşmeyi tekrardan onaylaması gerekmeyecektir.

Sandbox (Test) Hesabı Oluşturma (Pazaryeri için)

Entegrasyon işleminde kullanacağımız API ve Güvenlik anahtarları için iyzico’ nun sağlamış olduğu sandbox ortamda bir hesap oluşturuyoruz. Burada altını çizmek istediğim önemli bir konu var;

Sandbox hesapları varsayılan olarak standart e-ticaret için oluşturuluyor. Oluşturduğumuz iyzico hesabının tipini Pazaryeri olarak güncellemek için hesabımızla herhangi bir başarılı ödeme işlemi yapmadan önce entegrasyon@iyzico.com adresine üye iş yeri id numaramızı veya hesap oluştururken kullandığımız e-posta adresini içeren bir e-posta gönderiyoruz. Bu e-postada hesap tipimin Pazaryeri olarak güncellenmesini istiyorum yazmamız yeterli.

https://sandbox-merchant.iyzipay.com/auth adresi üzerinden entegrasyon sırasında kullanacağımız sandbox hesabımızı oluşturabiliriz. (Sandbox paneline giriş sırasında SMS şifresi olarak 123456 kullanabiliriz, cep telefonumuza SMS gelmesini beklememize gerek bulunmuyor.)

PHP Kütüphanesi

iyzico tarafından hazırlanmış olan PHP kütüphanesini https://github.com/iyzico/iyzipay-php bağlantısı üzerinden indirebilirsiniz. Farklı bir yazılım dili kullanmak isterseniz https://github.com/iyzico bağlantısına tıklayarak iyzico tarafından farklı yazılım dilleri için hazırlanan kütüphanelere de ulaşabilirsiniz. İndirdiğimiz PHP kütüphanesinde yer alan dosyaları MAMP’ ın kurulu olduğu dizinde htdocs klasörü içerisine taşıyoruz.

Kod Düzenlemeleri

Entegrasyonun kod seviyesindeki ilk adımı olarak config.php içerisinde yer alan ApiKey ve SecretKey parametrelerini set ediyoruz. Bu iki parametre için kullanacağımız değerlere iyzico sandbox panelimize https://sandbox-merchant.iyzipay.com/auth/login adresinden giriş yaparak sırasıyla Ayarlar > Firma Ayarları menüsünden ulaşabiliriz. BaseUrl parametresi kütüphane içerisinde set edilmiş olarak gelmekte, gelmemesi ihtimaline karşı https://sandbox-api.iyzipay.com değerini set edebilirsiniz.

config.php dosyasının düzenlenmesi

Alt Üye İş Yeri (SubMerchant) Kaydı

Pazaryeri çözümünde işlem onaylandıktan sonra satıcılara para transferi yapılabilmesi için bu satıcıların iyzico’ da kaydının bulunması gerekir. Pazaryeri; zaten bu satıcı bilgilerine sahip olduğu için, iyzico Onboarding API’sine satıcı bilgilerini göndererek satıcı kaydını oluşturduktan sonra bu bilgileri çekip güncelleyebilir. Pazaryeri altındaki alt üye işyerleri 3 tipte olabilir; bireysel, şahıs şirketi veya limited/anonim şirket. Her tip için alt üye işyeri kaydında gönderilen parametreler farklılık gösterebilir. Alt üye işyeri kaydı yapıldığında response alanında dönen subMerchantKey, o satıcı için tekil değerdir, bu değeri sisteminizde saklamalısınız, ödeme esnasında satıcıyı belirtmek için subMerchantKey’i göndermeniz gerekecektir.

Bireysel alt üye iş yeri oluşturmak için aşağıdaki sorguyu gerçekleştirdim;

Alt üe iş yeri kaydı – create_sub_merchant.php dosyasının düzenlenmesi

Not: Kütüphane içerisinde fonksiyon çağırılmamış ise aşağıdaki kod satırını ekliyoruz.

$func = create_personal_sub_merchant();

Gönderdiğimiz alt üye iş yeri kaydı isteği için iyzico servisinden aldığım sonuç aşağıdaki şekilde. Görebileceğiniz gibi iyzico servisinnden subMerchantKey parametresinde kaydettiğimiz alt üye iş yerine ait değeri aldık. Bu değeri ödeme isteği sırasında subMerchantKey parametresinde iyzico’ ya göndereceğiz.

Alt üye iş yeri kaydı cevabı

Pazaryeri Ödeme Oluşturma

Pazaryeri çalışma mantığında son kullanıcı sepetine çok sayıda alt üye iş yeri/satıcı’ ya ait ürünü eklemiş olabilir. Bu nedenle sepet detayında her ürün için subMerchantKey ve o ürün için alt üye iş yerine gönderilecek tutarı ifade eden subMerchantPrice parametrelerini giriyoruz.

Bu işlem için create_marketplace_payment içerisinde gerekli düzenlemeleri yaparak aşağıdaki sorguyu gerçekleştirdim. Ben 3 farklı ürün için aynı alt üye iş yerini kullandım, siz farklı alt üye iş yerleri oluşturarak her bir ürün için farklı subMerchantKey gönderebilirsiniz.

subMerchantPrice parametresinde ise; sepetteki 3 TL lik ilk ürün için subMerchantPrice’ ı 1 TL gönderdim, yani bu ürün için alt üye iş yerine/satıcıya 1 TL gönderilecek.

Onay Verme (approve)

iyzico Pazaryeri entegrasyonun en önemli noktalarından biri onay verme işlemidir. Yazımın başında da bahsettiğim gibi; iyzico, satıcı ve alıcı arasındaki escrow’a müdahil olmaz; ödemenin tahsilatına aracılık eder ve sepetteki ilgili ürün için üye işyerinden para transferine onay verilmesini bekler. Bu süre zarfında alıcının parası bankada korumalı havuz hesapta beklemektedir.

Ürün onaylama sorgusu yapılmadığı sürece tahsil edilen para alt üye iş yerinize/satıcıya aktarılmaz, iyzico tarafından üye iş yeri onay verene dek bekletilir. Üye işyeri bu sürede ödemeyi iptal edebilir, ödemenin kırılımını iade edebilir ya da ürün alıcıya ulaştı ve işlem sorunsuz tamamlandıysa para transferi için ürüne onay verebilir veya verdiği ürün onayını geri çekebilir.

iyzico servisinden ödeme sorgumuz için dönen response içerisinde, sepetteki her bir ürün için paymentTransactionId yer almakta. Onay verme işlemi için paymentTranscactionId (zorunlu), conversationId (optional), locale (optional) parametrelerini içeren bir sorgu gerçekleştiriyoruz.

Ödeme işlemimizde sepette yer alan 3. ürün (4 TL lik ürün) için dönen paymentTransactionId değeri ile aşağıdaki onay sorgusunu gerçekleştirdim.

Onay işlemi için approve.php dosyasının düzenlemesi

İptal Etme (disapprove)

Onay verdiğimiz bir ürünü/ödemeyi disapprove servisi ile iptal edebiliyoruz. Onayı iptal etmek için paymentTransactionId yi kullanarak bir sorgu gerçekleştiriyoruz. Disapprove sonrası ürüne/ödemeye onay verilmediği sürece iyzico işleme konu olan tutarı korumalı hesapta tutmaya devam edecektir.

İptal etme işlemi için disapprove.php dosyasının düzenlenmesi

Alt Üye İş Yeri Sorgulama/Çağırma (retrieve sub merchant)

iyzico’ ya alt üye iş yeri kaydettikten sonra bize dönen subMerchantKey değerini sorgulayabilmemiz/çağırabilmemiz için retrieve sub merchant servisini kullanıyoruz. subMerchantExternalId (alt üye iş yerinin kendi sisteminizdeki id’ si) kullanarak aşağıdaki sorguyu gerçekleştiriyoruz.

Alt üye iş yeri sorgulama işlemi için retrieve_sub_merchant dosyasının düzenlenmesi

Alt Üye İş Yeri Güncelleme (update submerchant)

iyzico’ ya altyapısında tanımlı olan bir alt üye iş yeri güncellenebilir. Para aktarımı sağlanmadı ise IBAN bilgisi de güncellenebilmektedir. Alt üye iş yerimiz için iyzico’ da kayıtlı isim/iban ile banka tarafındaki isim/iban uyuşmazlığı nedeniyle iban güncellendiğinde ertesi iş günü iyzico para aktarımızı tekrar deneyecektir.

Alt üye iş yeri güncelleme işlemi için update_sub_merchant dosyasının düzenlenmesi

Raporlama

Raporlama için retrieve payout transactions sorgusunu belirli bir gün ve saat için çalıştırarak, o gün içerisinde o zamana kadar olan alt üye iş yerlerinize aktarılan ödemeleri kontrol edebilirsiniz.

One thought on “iyzico Pazaryeri (Marketplace) Entegrasyonu

Bir Cevap Yazın