Ana içeriğe geç

API

Dönüş Formatları

Craftgate API'nin dönüş parametreleri, işlemin başarılı gerçekleşip gerçekleşmemesine ve tekil ya da çoğul sonuç değeri dönmesine göre farklılıklar içerse de, bunlar kendi içlerinde ortak birer çatı kullanır.

Hatalı İşlemler

Sistemsel ya da kurgusal bir hata gerçekleştiğinde kullanılan dönüş formatıdır. Sadece içerisinde hata bilgilerini barındıran errors isimli bir alan içerir.

errors
Error

Gerçekleşen hataya ilişkin bilgiler içerir. Detaylı bilgi için Bkz. Ödeme Hata Bilgisi

errorCode
string

Hataya ilişkin ayrıştırıcı kod numarası

errorDescription
string

Hatanın niteliğini ifade eden açıklayıcı mesaj

errorGroup
string

(Bkz: Ödeme Hata Grupları) Ödemeye ilişkin bir hata gerçekleştiği durumda gönderilen hata grubu, aksi durumda bu değer boş olacaktır.

Başarılı İşlemler

Başarılı işlemler sonucunda dönen cevaplar, işlem sonucunun tekil ya da çoğul olmasına göre farklı parametreler içerir.

Tekil Sonuçlu İşlemler

Ödeme alma, bir ödemeyi iade etme, alıcı oluşturma, üye işyeri detayı görüntüleme gibi tekil sonuç üreten işlem ya da sorgular için kullanılan dönüş formatıdır. Sadece içerisinde işlem sonucunu barındıran data isimli bir alan içerir.

data
any

Gerçekleştirilen işlem ya da sorgu sonucu. Nitelik ve içeriği ilgili işlem ya da sorguya ilişkin dokümantasyon sayfasında detaylandırılmıştır.

Örnek: Bir ödemenin detayı için iletilen cevap örneği:

{
"data": {
"id": 5,
"createdDate": "2021-11-15T14:07:18",
"price": 100.00000000,
"paidPrice": 100.00000000,
...
}
}

Çoğul Sonuçlu İşlemler

Arama ya da listeleme gibi çoğul sonuç üretme potansiyeline sahip işlem ya da sorgular sonucunda dönülen cevap formatıdır.

items
any[]

İşlem ya da sorgu sonucunda ulaşılan sonuçları içerir. Sonuçların nitelik ve içerikleri ilgili işlem ya da sorguya ilişkin dokümantasyon sayfasında detaylandırılmıştır.

totalSize
number

Arama ya da listeleme gibi sayfalama niteliğine sahip işlemler sonucunda döner. Sorgu sonucunda ulaşılan toplam sonuç sayısını ifade eder. Hatalı işlemlerin dönüşlerinde bu alan yer almaz.

size
number

Arama ya da listeleme gibi sayfalama niteliğine sahip işlemler sonucunda döner. Sorgulamada sayfa başına dönmesi istenen sonuç sayısını ifade eder. Hatalı işlemlerin dönüşlerinde bu alan yer almaz.

page
number

Arama ya da listeleme gibi sayfalama niteliğine sahip işlemler sonucunda döner. Sorgulamada sayfa sayısını ifade eder. Hatalı işlemlerin dönüşlerinde bu alan yer almaz.

Örnek: Ödemelerin listesi istendiğinde iletilen cevap örneği:

{
"data": {
"items": [
{
"id": 5,
"createdDate": "2021-11-15T14:07:18",
...
},
{
"id": 4,
"createdDate": "2021-11-15T14:07:18",
...
},
{
"id": 3,
"createdDate": "2021-11-15T14:07:18",
...
}
],
"page": 0,
"size": 25,
"totalSize": 3
}
}

Sonuçsuz İşlemler

Saklı kart silme gibi sonuç üretmeyen işlemler sonucunda boş cevap dönülebilir. Bu gibi işlemler oldukça nadir olmakla beraber, silme işlemlerinde bir cevap dönülmeyeceği beklentisiyle hareket edilmesi önerilir. Öte yandan, bu cevaplar 204 No Content HTTP koduyla dönülebileceği ve bu kod da başarılı işlemleri ifade ettiği için, isteğin başarılı olup olmadığı kontrolü yapılırken statü kodunun sadece 200 OK olmasına bakılması önerilmez.

Sabitler ve Enum Değerleri

Farklı işlemlerin istek ve dönüş parametreleri olarak kullanılan birtakım sabitler ve enum değerleri bu başlık altında listelenmiştir.

Genel

Durum

Craftgate API ile işlem yaparken kullanılabilecek durumlar:

DeğerAçıklama
ACTIVEAktif, kullanılabilir bir kaydı temsil eder
PASSIVEPasif, kullanılamaz kayıtları temsil eder

Para Birimleri

Craftgate API ile işlem yaparken kullanılabilecek para birimleri:

DeğerAçıklama
TRYTürk Lirası
USDABD Doları
EUREuro
GBPİngiliz Sterlini
CNYÇin Yuanı
ARSArjantin Pesosu
BRLBrezilya Reali
AEDBirleşik Arap Emirlikleri Dirhemi
IQDIrak Dinarı
AZNAzerbaycan Manatı
KZTKazakistan Tengesi

Kart Tipleri

Kartın kullanım niteliğini ifade eden tipler:

DeğerAçıklama
CREDIT_CARDKredi kartı
DEBIT_CARDDebit kart
PREPAID_CARDPrepaid kart

Üye

Üye Tipleri

DeğerAçıklama
PERSONALBireysel
PRIVATE_COMPANYŞahıs Şirketi
LIMITED_OR_JOINT_STOCK_COMPANYLimited ya da Anonim Şirket

Üye Kazancı Hakediş Yerleri

DeğerAçıklama
IBANIBAN
WALLETCüzdan

Para Gönderimi Geri Dönme Durumları

DeğerAçıklama
NOT_BOUNCEDPara gönderimi yapıldığında oluşan ilk değerdir. Para gönderiminin ilk denemede gönderildiğini ifade eder.
BOUNCEDPara gönderimininin, geri döndü olarak işaretlenmesi ile oluşan durumdur.
UPDATEDPara gönderimine konu olan Ad/Soyad/Iban bilgileri ile birlikte satıcı bilgileri güncellendiğinde oluşan durumdur.
PAYOUT_STARTEDParası geri dönen bir işlem için tekrar para gönderimi yapılma esnasında oluşan durumdur.
PAYOUT_COMPLETEDParası geri dönen bir işlem için para gönderimin tekrar yapılmasından sonra oluşan durumdur

Ödemeler

Ödeme Tipleri

Bir ödemenin tahsilat biçimini ifade eden değerler:

DeğerAçıklama
CARD_PAYMENTTamamı karttan tahsil edilen ödeme
DEPOSIT_PAYMENTKarttan para yükleme ödemesi
WALLET_PAYMENTTamamı cüzdandan tahsil edilen ödeme
CARD_AND_WALLET_PAYMENTBir kısmı karttan, bir kısmı cüzdandan tahsil edilen ödeme
APMAlternatif Ödeme Yöntemi ile ödeme

Ödeme Grupları

Ödemenin konu olduğu ürün ya da hizmeti ifade eden grup adları:

DeğerAçıklama
PRODUCTÜrün
LISTING_OR_SUBSCRIPTIONİlan, listeleme, hizmet ya da abonelik

Ödeme Durumları

Ödemenin durumunu ifade eden değerler:

DeğerAçıklama
FAILUREÖdeme başarısız
SUCCESSÖdeme başarılı
INIT_THREEDS3D Secure başlatıldı
CALLBACK_THREEDSBankanın 3D Secure SMS sayfasında sms kodu girildikten sonra işlem Craftgate tarafında bekliyor. Craftgate bu durumda üye işyerinin callback adresine dönmüş olup ödemeyi tamamlamasını bekliyor.

Ödeme Kırılım Onay Durumu

Bir ödeme kırılımına ilişkin onay durumunu ifade eden değerlerdir

DeğerAçıklama
WAITING_FOR_APPROVALOnay bekleniyor
APPROVEDOnaylanmış

Ödeme Fazları

Ödemenin bankadaki işlem tipi/fazı:

DeğerAçıklama
AUTHNormal Provizyon işleminde ödeme fazı bu değeri alır.
PRE_AUTHÖn Provizyon işlemi yapılırsa ödeme fazı bu değeri alır. Ön provizyon işleminde, ödeme doğrudan çekilmez, ilgili tutar kadar banka tarafında kullanıcının kartına provizyon süresince bloke konur.
POST_AUTHÖn Provizyon yapılmış bir işlem için provizyon kapama yapılması durumunda ödeme fazı bu değeri alır.

Ödeme Yöntemleri

Bir ödemenin nasıl tahsil edileceğini ifade eden değerler:

DeğerAçıklama
CARDKullanıcı ödemeyi kart bilgisi ile yapar
MASTERPASSKullanıcı ödemeyi Masterpass hesabı ile yapar
PAPARAKullanıcı ödemeyi Papara hesabı ile yapar
PAYONEERKullanıcı ödemeyi Payoneer hesabı ile yapar
PLUXEEKullanıcı ödemeyi Pluxee kartı ile yapar
EDENREDKullanıcı ödemeyi Edenred kartı ile yapar
EDENRED_GIFTKullanıcı ödemeyi Edenred hediye kartı ile yapar
PAYPALKullanıcı ödemeyi PayPal hesabı ile yapar
AFTERPAYKullanıcı ödemeyi Afterpay hesabı ile yapar
STRIPEKullanıcı ödemeyi Stripe hesabı ile yapar

Para Gönderim Durumları

Para Gönderim durumunu ifade eden değerler:

DeğerAçıklama
NO_PAYOUTPara gönderimi yapılmayacak
WAITING_FOR_PAYOUTPara gönderimi için bekleniyor
PAYOUT_STARTEDPara gönderimi başlatıldı
PAYOUT_COMPLETEDPara gönderimi tamamlandı

Para Gönderimi Tipi

Para Gönderimi Tiplerini ifade eden değerler:

DeğerAçıklama
SETTLEMENTÖdeme/İptal/İade işlemlerinden dolayı oluşan para gönderimlerini temsil eder
BOUNCED_SETTLEMENTParası gönderildikten sonra bazı nedenlerden dolayı parası geri dönen işlemleri tekrar göndermek için yapılan para gönderimini temsil eder
WITHDRAWSatıcılarınızın cüzdan bakiyelerinden para çekme taleplerine istinaden yapılan para gönderimlerini temsil eder

Para Gönderimi Kaynağı

Para Gönderimi Kaynağını ifade eden değerler:

DeğerAçıklama
COLLECTIONÖdeme/İptal/İade işlemlerinden dolayı oluşan para gönderimlerini temsil eder
BOUNCEDParası gönderildikten sonra bazı nedenlerden dolayı parası geri dönen işlemleri tekrar göndermek için yapılan para gönderimini temsil eder
WITHDRAWSatıcılarınızın cüzdan bakiyelerinden para çekme taleplerine istinaden yapılan para gönderimlerini temsil eder

MD Status

3D Secure ile yapılan ödemelerde doğrulama sonrası banka tarafından Craftgate'ye iletilen sayısal değerlerdir. Bankalar ve ödeme kuruluşları kimi zaman kendilerine özgü MD Status değerleri dönse de aşağıdaki tabloda yer alan değerler standart kabul edilebilir.

MD StatusAçıklama
03D Secure doğrulama veya imzası geçersiz
1Tam Doğrulama, işleme devam edilebilir
2Kart sahibi veya bankası sisteme kayıtlı değil
3Kartın bankası sisteme kayıtlı değil
4Doğrulama denemesi, kart sahibi sisteme daha sonra kayıt olmayı seçmiş
5Doğrulama yapılamıyor
63D Secure hatası
7Sistem hatası

Ödeme Kaynakları

Bir ödemenin hangi entegrasyon çeşidi üzerinden geldiğini belirtir.

DeğerAçıklama
APIAPI üzerinden
MASTERPASSMasterpass üzerinden
CHECKOUT_FORMÖdeme formu üzerinden

Alternatif Ödeme Yöntemleri

Craftgate tarafından desteklenen Alternatif Ödeme Yöntemleri

DeğerAçıklama
PAPARAPapara
PAYONEERPayoneer
PLUXEEPluxee
EDENREDEdenred
EDENRED_GIFTEdenred Hediye Kartı
PAYPALPayPal
KLARNAKlarna
AFTERPAYAfterpay
STRIPEStripe

Direkt Alternatif Ödeme Yöntemleri

Craftgate tarafından desteklenen Direkt Alternatif Ödeme Yöntemleri

DeğerAçıklama
FUND_TRANSFEREFT/Havale ile Ödeme
CASH_ON_DELIVERYKapıda Nakit Ödeme

Alternatif Ödeme Yöntemleri Ek Aksiyonlar

Craftgate tarafından desteklenen Alternatif Ödeme Yöntemleri için alınacak ek aksiyonları ifade eder

DeğerAçıklama
REDIRECT_TO_URLKullanıcı, cevap içerisinde yer alan redirectUrl adresine yönlendirilmelidir.
OTP_REQUIREDKullanıcıdan OTP doğrulama kodu alınmalıdır.
SHOW_HTML_CONTENTCevap içerisinde dönen HTML bilgisinin ekranda gösterilmesi gerekmektedir.
WAIT_FOR_WEBHOOKCraftgate sisteminden gelecek Webhook mesajı beklenmelidir.
APPROVAL_REQUIREDÜye işyeri tarafından sürecin tamamlanması için onay beklenmektedir.
NONEEk bir aksiyon alınmasına gerek bulunmamaktadır.

Alışveriş Kredisi Ödeme Yöntemleri Ek Aksiyonlar

Craftgate tarafından desteklenen Alternatif Ödeme Yöntemleri için alınacak ek aksiyonları ifade eder

DeğerAçıklama
REDIRECT_TO_URLKullanıcı, cevap içerisinde yer alan redirectUrl adresine yönlendirilmelidir.
WAIT_FOR_WEBHOOKCraftgate sisteminden gelecek Webhook mesajı beklenmelidir.
APPROVAL_REQUIREDÜye işyeri tarafından sürecin tamamlanması için onay beklenmektedir.
VERIFY_REQUIREDKredi kullanım durumu sorgulanamadı ya da belirsiz. Üye işyeri tarafından Alışveriş Kredisi Doğrulama servis çağrısı yapılarak tekrar sorgulanması gereklidir.
NONEEk bir aksiyon alınmasına gerek bulunmamaktadır.

Kategori Kodları

DeğerAçıklama
MOBILE_PHONE_PRICE_ABOVE_REGULATION_LIMITFiyatı regülasyon limitinin üzerindeki cep telefonu
MOBILE_PHONE_PRICE_BELOW_REGULATION_LIMITFiyatı regülasyon limitinin altındaki cep telefonu
TABLETTablet
COMPUTERBilgisayar
CONSTRUCTION_MARKETYapı Market
GOLDAltın
DIGITAL_PRODUCTSDijital Ürünler
SUPERMARKETSüpermarket
WHITE_GOODSBeyaz Eşya
WEARABLE_TECHNOLOGYGiyilebilir Teknoloji
SMALL_HOME_APPLIANCESKüçük Ev Aletleri
TVTV
GAMES_CONSOLESOyun & Oyun Konsolları
AIR_CONDITIONER_AND_HEATERKlima & Isıtıcı
ELECTRONICSElektronik
ACCESSORIESAksesuar
MOM_AND_BABY_AND_KIDSAnne & Bebek & Çocuk
SHOESAyakkabı
CLOTHINGGiyim
COSMETICS_AND_PERSONAL_CAREKozmetik & Kişisel Bakım
FURNITUREMobilya
HOME_LIVINGEv & Yaşam
AUTOMOBILE_MOTORCYCLEOtomobil & Motosiklet
OTHERDiğer

Ödül Tipleri

Banka tarafından sağlanan ödüllerin tipini belirtir.

DeğerAçıklama
REWARD_MONEYPuan Kullanımı
ADDITIONAL_INSTALLMENTEk Taksit
POSTPONING_INSTALLMENTTaksit Atlatma
EXTRA_POINTSEkstra Puan
GAINING_MINUTESKontör Kazanım
POSTPONING_STATEMENTEkstre Erteleme

İadeler

İade Durumları

Bir iadenin durumunu ifade eden değerlerdir.

DeğerAçıklama
SUCCESSBaşarılı
FAILUREBaşarısız

İade Durumları

Bir ödemenin iade edilme durumunu ifade eden değerlerdir.

DeğerAçıklama
NO_REFUNDÖdeme başarılı değil
NOT_REFUNDEDİadesi bulunmuyor
PARTIAL_REFUNDEDParçalı iade edilmiş
FULLY_REFUNDEDİade edilmiş

İade Tipleri

Bir iade tutarının nereye yatırılacağını ifade eden değerlerdir.

DeğerAçıklama
PROVIDERÖdemenin alındığı yere (Karta ya da APM e)
WALLETCüzdana

Para Gönderimi

Para Gönderim Talebi Sonuç Durumları

Para gönderim talebi alınması sonucunu ifade eden değerdir.

DeğerAçıklama
SUCCESSPara gönderimi başarıyla tamamlandı.
FAILUREPara gönderimi gerçekleştirilemedi.
NO_RECORD_FOUNDPara gönderimi yapılacak kayıt bulunamadı

Cüzdana Para Gönderme/Çekme

Cüzdana Para Gönderme/Çekme Tipleri

Üye işyerinin Craftgate sisteminde tanımladığı üyesine para gönderme nedenleridir.
Standart bir üye işyeri için varsayılan değer REDEEM_ONLY_LOYALTY dir. Opsiyonel olarak gönderilmesi durumunda REDEEM_ONLY_LOYALTY değeri gönderilmelidir.

DeğerAçıklama
REDEEM_ONLY_LOYALTYSadakat programları kapsamında kullanılabilen tiptir. Üyeye bu tipde gönderilen paralar üye tarafından sadece sistem içerisinde harcanabilir.

Günlük İşlem Raporları

Günlük İşlem Raporları Dosya Tipleri

DeğerAçıklama
CSVComma Separated Values dosya tipi uzantısı.
XLSXExcel dosya tipi uzantısı.

İmza Hesaplama

Craftgate API'lerine doğrudan yapılacak her istekte, üye işyeri hesabının erişim anahtarları kullanılarak bir kimlik doğrulaması yapılması gerekmektedir. Üye iş yerine ait erişim anahtarları bilgisine Merchant Panel üzerinden ulaşabilirsiniz.

Eğer Craftgate Client kullanıyorsanız erişim anahtarları bilgisini Craftgate objesine parametre olarak vermeniz yeterli olacaktır. Eğer client kullanmıyorsanız aşağıdaki işlemlerin gerçekleştirilmesi zorunludur.

Üye işyeri hesabınızla birlikte kimlik doğrulaması yapmak için API Gateway'e yapacağınız her istekte aşağıdaki header' ları göndermeniz gerekmektedir:

Header AdıAçıklama
x-api-keyAPI erişim anahtarı
x-rnd-keyİsteğe özel oluşturulmuş rastgele bir string değer
x-auth-versionKimlik doğrulama algoritmasınin versiyon numarası. Hangi değeri vermeniz gerektiğinden emin değilseniz V1 verebilirsiniz
x-signatureYukarıdaki parametreler, gizli erişim şifresi ve yapılan isteğe özgü birtakım bilgiler kullanılarak oluşturulmuş imza.
Daha fazla bilgi için bkz. İmza Hesaplama Algoritması

İmza Hesaplama Algoritması

İmza, isteğin doğru kaynaktan geldiğini doğrulamak için kullanılan bir sağlama değeridir. Yapılan isteğe özel olduğu için her istekte yeniden hesaplanıp, istekle birlikte gönderilmelidir. İmza değerini hesaplamak için:

  • Aşağıdaki değerleri uç uca birleştir
    • İsteğin yapıldığı URL'in ham hali (hostname, protocol ve query string dahil)
    • Üye işyeri hesabının API erişim anahtarı (API Key)
    • Üye işyeri hesabının gizli erişim şifresi (Secret Key)
    • İsteğe özgü oluşturulmuş rastgele bir string
    • Eğer mevcut ise isteğin body'si
  • Birleştirilen string'in SHA-256 hash'ini hesapla (Hesaplama sırasında SHA-256 çıktısının digest (bytes), byte encoding'inin de UTF-8 olması gerektiği unutmayınız.)
  • Hash'in Base64 ile şifrelenmiş halini hesapla

Craftgate Sandbox oramına attığınız istekler için imza hesaplamak isterseniz, kullanılan bilgiler içinde sandbox hesabı için kullanılan bilgiler olmalıdır. Yani url içinde sandbox api url'i olan https://sandbox-api.craftgate.io, sandbox hesabınıza ait api key ve secret key bilgileri gibi. Canlı ortamında ise bu bilgiler canlı hesabınıza ait olmalı. Yani url içinde canlı sistemin api url'i olan https://api.craftgate.io ve canlı hesabına ait api key ve secret key gibi.

Hesaplama sırasında payload içeriğinin encoding'inin değişmediğinden emin olunuz. Eğer değişirse, payload içinde farklı, hesaplanan veri içerisinde farklı olacağından "Signature is not equal!" hatası ile karşılaşırsınız.

Algoritmanın detayları için client'larımıza ait aşağıdaki kodlar incelenebilir.

Örnek 1

Parametreler
AdDeğer
İstek URLhttps://api.craftgate.io/onboarding/v1/members/1
Request Body-
API Keykey-1
Secret KeyFooBar123!
Random KeyXa15Fp11T
İmza Hesaplama
  • Full URL:
    https://api.craftgate.io/onboarding/v1/members/1
  • Query String: -
  • API Key:
    key-1
  • Secret Key:
    FooBar123!
  • Random Key:
    Xa15Fp11T
  • Request Body: -
  • Birleştirilmiş String:
    https://api.craftgate.io/onboarding/v1/members/1key-1FooBar123!Xa15Fp11T
  • Signature:
    y1TtnjNCJEvlkP5ufCkK3H0i2guMB/bKL4Ayw3VlKWA=
İsteğe Eklenecek Header'lar
AdDeğer
x-api-keykey-1
x-rnd-keyrGciw1df
x-auth-versionV1
x-signaturey1TtnjNCJEvlkP5ufCkK3H0i2guMB/bKL4Ayw3VlKWA=

Örnek 2

Parametreler
AdDeğer
İstek URLhttps://api.craftgate.io/onboarding/v1/members
Request Body{"email": "haluk.demir@example.com","name": "Haluk Demir","phoneNumber": "905551111111","address": "Beylerbeyi Cad. Lale Sok. No: 38 Daire: 3 Üsküdar","contactName": "Haluk","contactSurname": "Demir","memberExternalId": "0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
API Keykey-1
Secret KeyFooBar123!
Random KeyXa15Fp11T
İmza Hesaplama
  • Full URL:
    https://api.craftgate.io/onboarding/v1/members
  • Query String: -
  • API Key: key-1
  • Secret Key:
    FooBar123!
  • Random Key:
    Xa15Fp11T
  • Request Body:
    {"email": "haluk.demir@example.com","name": "Haluk Demir","phoneNumber": "905551111111","address": "Beylerbeyi Cad. Lale Sok. No: 38 Daire: 3 Üsküdar","contactName": "Haluk","contactSurname": "Demir","memberExternalId": "0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Birleştirilmiş String:
    https://api.craftgate.io/onboarding/v1/memberskey-1FooBar123!Xa15Fp11T{"email": "haluk.demir@example.com","name": "Haluk Demir","phoneNumber": "905551111111","address": "Beylerbeyi Cad. Lale Sok. No: 38 Daire: 3 Üsküdar","contactName": "Haluk","contactSurname": "Demir","memberExternalId": "0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Signature:
    nv8y2bSnFjYNRzVRqzkHTK5RXKuN04hoK6fLE2+nzTw=
İsteğe Eklenecek Header'lar
AdDeğer
x-api-keykey-1
x-rnd-keyXa15Fp11T
x-auth-versionV1
x-signaturepYuONv7/IgM14OAuSoANWUUgfVSwRX3bYeSZLXltb04=