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 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.
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 |
Parametre Adı | Tipi | Zorunlu | Açıklama |
---|---|---|---|
apmType |
string |
Evet | bkz: Alternatif Ödeme Yöntemleri Ödeme alınmak istenen alternatif ödeme yöntemi |
merchantApmId |
number |
Hayır | Ödeme alınmak istenen APM Id değeri. Merchant panelinde APM tanımlaması yapıldığında verilen ID değeridir. Birden fazla aynı tipte APM olduğu durumda gönderilmelidir. |
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 | APM'den dönen sonucu üye işyerine iletmek için kullanılacak callback adresi |
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 |
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 Aksiyonlar |
redirectUrl |
string |
Hayır | APM tarafından dönülen, ödeme işleminin devam edeceği URL bilgisi |
paymentError |
PaymentError |
Hayır | APM tarafından bir hata oluşursa hataya ait detayları içerir |
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. |
hash |
string |
Evet | Ödeme sonucu dönülen parametrelerin Sha-256 Hex algoritması ile şifrelenmesi sonucu oluşan değerdir. Detaylı açıklama aşağıda, "Hash Değerinin Oluşurulması" başlığında mevcuttur. |
Response içerisinde bulunan hash değeri, dönülen parametrelerin doğrulamasını sağlamak amacıyla Sha-256 Hex algoritması ile hashlenerek oluşturulur.
threedSecureCallbackKey###status###paymentId###conversationId###callbackStatus
Örnek olarak aşağıdaki response'u hash algoritmasına sokalım ve Üye İşyeri 3DSecure Callback Key değerinin " merchantThreeDsCallbackKeySndbox" olduğunu varsayalım.
{
"status": "SUCCESS",
"conversationId": "456d1297-908e-4bd6-a13b-4be31a6e47d5",
"paymentId": 1,
"callbackStatus": null,
"hash": "520c04646748d344fa5541aacaf56cb0d727c5b3020e09c554604f81b9015d0a"
}
Hash algoritmasına sokulacak değer şu şekilde oluşmalı:
merchantThreeDsCallbackKeySndbox###SUCCESS###1###456d1297-908e-4bd6-a13b-4be31a6e47d5###
Oluşturulan değerin "Üye İşyeri 3DSecure Callback Key" ile Sha-256 Hex algoritamsına sokularak hashlenmesi ile response'da bulunan "hash" parametresinin eşitliği karşılaştılarak validasyon sağlanabilir.
Açık kaynak kodlu Craftgate API client'larındaki örnek kodları inceleyebilirsiniz.
APM Ödeme Başlatma isteğinin cevabında yer alan paymentStatus
parametresinin WAITING
, additionalAction
parametresinin de NONE
olmadığı durumlarda APM ödemesinin tamamlanması için bu servis kullanılmalıdır.
APM ile ödeme tamamlama işlemi için kullanılan endpoint ve http metod bilgisi aşağıda verilmiştir.
HTTP Metod | URL |
---|---|
POST |
/payment/v1/apm-payments/complete |
Parametre Adı | Tipi | Zorunlu | Açıklama |
---|---|---|---|
paymentId |
number |
Evet | APM Ödeme başlatma isteğinin cevabında yer alan ödeme ID değeri |
additionalParams |
map |
Evet | 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 |
APM ile ödeme tamamlama 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 | Ödemenin id bilgisi. |
paymentStatus |
PaymentStatus |
Evet | Ödeme durumunu ifade eder. SUCCESS veya FAILURE olabilir. |
paymentError |
PaymentError |
Hayır | APM tarafından bir hata oluşursa hataya ait detayları içerir. |
Açık kaynak kodlu Craftgate API client'larındaki örnek kodları inceleyebilirsiniz.