Alternatif Ödeme Yöntemi ile Ödeme Alma

Alternatif Ödeme Yöntemi(APM) ile ödeme almak için ilk adım olarak Craftgate'de ödeme başlatılması gerekir. Sonrasında seçilen Alternatif ödeme yöntemine göre değişiklik gösterebilen, yöntemin ödeme adımları izlenerek ödeme tamamlanır. Akabinde ödeme başlatma isteği içerisinde verilmiş olan üye işyeri callback URL adresi ödeme durum bilgisi ile tetiklenir.

APM Ödeme Başlatma

APM Ödeme Başlatma isteğinin cevabında yer alan additionalAction ve paymentStatus alanlarındaki değerlere göre kullanıcınıza ek aksiyon aldırmanız gerekebilir. additionalAction parametresinin NONE ve paymentStatus parametresinin SUCCESS geldiği durumlarda APM ödemeniz başarıyla tamamlanmış demektir.

URL

APM ile ödeme işlemi için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.

HTTP Metod URL
POST /payment/v1/apm-payments/init

Ödeme Başlatma İsteği Parametreleri

Parametre Adı Tipi Zorunlu Açıklama
apmType string Evet bkz: Alternatif Ödeme Yöntemleri Ödeme alınmak istenen alternatif ödeme yöntemi
conversationId string Hayır İstekle beraber gönderilip, cevapla birlikte alınabilecek, "bumerang" değer. Farklı istekleri birbirleriyle ilişkilendirmek için kullanılabilir. Genellikle üye işyerinin ödemeye ilişkin sipariş numarası kullanılır. Sipariş numarası ile kullanmanız sonradan işlemleri incelemenize yardımcı olacaktır.
externalId string Hayır Üye işyeri tarafından ödeme isteği içerisinde gönderilen externalId değeri
price decimal Evet Toplam ödeme tutarı. Sepetteki ürün/hizmet tutarları toplamının bu tutara eşit olması gerekmektedir
paidPrice decimal Evet Komisyon ve indirim gibi farklar dahil edilerek hesaplanan, karttan çekilecek nihai tutar. Tamamı ya da bir kısmı cüzdandan tahsil edilen ödemelerde cüzdandan tahsil edilecek tutar da bu tutara dahildir. İşlemde vade farkı var ise vade farkı eklenmiş tutar bu parametreye girilmelidir.
buyerMemberId number Hayır Ödemenin ilişkilendirildiği alıcı ID'si. Üye işyerinin kendi sistemlerindeki ID değerini değil, Craftgate sistemlerindeki ID değerini ifade eder
currency Currency Evet bkz: Para Birimleri Ödemenin tahsil edileceği para birimi
paymentGroup PaymentGroup Evet bkz: Ödeme Grupları
paymentChannel string Hayır Genellikle üye işyeri tarafındaki, ödemenin alındığı kanal veya ödemeye özel bir bilgi tutmak için kullanılır. Daha sonradan sorgulama servislerini kullanarak bu değer ile sorgulama yapabilirsiniz.
callbackUrl string Evet APN den dönen sonucu üye işyerine iletmek için kullanılacak adres)
apmOrderId string Hayır Ödeme alınırken APM'e iletilecek orderId parametresi. Opsiyonel olduğu için gönderilmemesi ve orderId değerinin Craftgate tarafından üretilmesi önerilir.
apmUserIdentity string Hayır Ödeme yapacak olan kullanıcının APM sistemindeki eşsiz değeri.
additionalParams map Hayır Gerekli olan ekstra parametreler burada gönderilebilir. Ilgili APM tipine göre gönderilecek parametreler değilebilir. Detay için bkz. Alternatif Ödeme Yöntemleri
clientIp string Hayır Ödeme yapan alıcının IP adresi.
items PaymentItem[] Evet (bkz. Ödeme Kırılım Bilgileri) Ödemeye ilişkin kırılım bilgileri. En az bir kırılım gönderilmesi ve gönderilen kırılımların tutarlarının toplamının price alanına eşit olması zorunludur

Dönüş Parametreleri

APM ile ödeme işleminin sonucunda dönen parametreler API dokümantasyonu giriş sayfasındaki Dönüş Formatları bölümünde belirtilen kurallara tabidir. Sistemsel ya da kurgusal bir hata bulunmadığı durumda data parametresinde dönen objenin alt parametreleri aşağıdaki gibidir:

Parametre Adı Tipi Her Zaman Mevcut Açıklama
paymentId number Evet Bekleme durumunda oluşturulan ödemenin id bilgisi
paymentStatus PaymentStatus Evet Ödeme durumunu ifade eder. WAITING olduğu durumlarda yönlendirme bekleniyordur, SUCCESS ise ödeme tamamlanmış demektir.
additionalAction AdditionalAction Evet Bazı APM entegrasyonlarında ekstra yapılması gereken işlemler olabildiği gibi bazılarında ise bu işleme gerek yoktur. NONE dönüldüğü durumlarda APM ödemesi için ekstra bir işlem yapılmasına gerek yoktur. Bkz. APM Ek Aksiyomlar
redirectUrl string Hayır APM tarafından dönülen, ödeme işleminin devam edeceği URL bilgisi

Callback URL'e İletilen Parametreler

Aşağıdaki parametreler form variable olarak HTTP POST metodu kullanılarak iletilir. Doğrulama sonrası Craftgate tarafından callbackUrl'e yapılacak istekte yer alan parametreler aşağıdaki gibidir:

Parametre Adı Tipi Her Zaman Mevcut Açıklama
status string Evet APM ödemenin doğrulamasının durumunu ifade eden değer. Doğrulama başarılıysa SUCCESS, değilse FAILURE değerini alacaktır
conversationId string Hayır Ödeme başlatma isteğinde gönderilen conversationId parametresinin değeri
paymentId number Hayır Doğrulama başarılı olduğu durumda gönderilir. Ödemeye ilişkin Craftgate API tarafından türetilen ID değeridir
callbackStatus string Hayır APM'in veya son kullanıcının APM doğrulama adımını tekrar tetiklemesi durumunda, ödeme daha önceden doğrulanmış ise gönderilir. Status alanı FAILURE değerini alırken, callbackStatus değeri ALREADY_RETURNED olarak gönderilecektir. Bu alan ALREADY_RETURNED değeriyle geldiği durumda, sisteminizde ödemenin durumu kontrol edilmeli ve tamamlanmışsa bir aksiyon alınmamalıdır.

Örnek Kodlar

Açık kaynak kodlu Craftgate API client'larındaki örnek kodları inceleyebilirsiniz.

APM ile Ödeme Başlatma