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.

Parametre Adı Tipi Her Zaman Mevcut Açıklama
errors Error Evet Gerçekleşen hataya ilişkin bilgiler içerir. Detaylı bilgi için Bkz. Ödeme Hata Bilgisi

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.

Parametre Adı Tipi Her Zaman Mevcut Açıklama
data any Hayır 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.

Parametre Adı Tipi Her Zaman Mevcut Açıklama
items any[] Evet İş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 Hayır 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 Hayır 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 Hayır 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ğer Açıklama
ACTIVE Aktif, kullanılabilir bir kaydı temsil eder
PASSIVE Pasif, kullanılamaz kayıtları temsil eder

Para Birimleri

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

Değer Açıklama
TRY Türk Lirası
USD ABD Doları
EUR Euro
GBP İngiliz Sterlini
CNY Çin Yuanı
ARS Arjantin Pesosu
BRL Brezilya Reali

Kart Tipleri

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

Değer Açıklama
CREDIT_CARD Kredi kartı
DEBIT_CARD Debit kart
PREPAID_CARD Prepaid kart

Kart Kuruluşları

Kart sağlayıcı kuruluşları ifade eden isimlerdir.

Değer Açıklama
VISA Visa
AMEX American Express
MASTER_CARD Master Card
TROY Troy

Üye

Üye Tipleri

Değer Açıklama
PERSONAL Bireysel
PRIVATE_COMPANY Şahıs Şirketi
LIMITED_OR_JOINT_STOCK_COMPANY Limited ya da Anonim Şirket

Üye Kazancı Hakediş Yerleri

Değer Açıklama
IBAN IBAN
WALLET Cüzdan

Para Gönderimi Geri Dönme Durumları

Değer Açıklama
NOT_BOUNCED Para gönderimi yapıldığında oluşan ilk değerdir. Para gönderiminin ilk denemede gönderildiğini ifade eder.
BOUNCED Para gönderimininin, geri döndü olarak işaretlenmesi ile oluşan durumdur.
UPDATED Para gönderimine konu olan Ad/Soyad/Iban bilgileri ile birlikte satıcı bilgileri güncellendiğinde oluşan durumdur.
PAYOUT_STARTED Parası geri dönen bir işlem için tekrar para gönderimi yapılma esnasında oluşan durumdur.
PAYOUT_COMPLETED Parası 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ğer Açıklama
CARD_PAYMENT Tamamı karttan tahsil edilen ödeme
DEPOSIT_PAYMENT Karttan para yükleme ödemesi
WALLET_PAYMENT Tamamı cüzdandan tahsil edilen ödeme
CARD_AND_WALLET_PAYMENT Bir kısmı karttan, bir kısmı cüzdandan tahsil edilen ödeme
APM Alternatif Ödeme Yöntemi ile ödeme

Ödeme Grupları

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

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

Ödeme Durumları

Ödemenin durumunu ifade eden değerler:

Değer Açıklama
FAILURE Ödeme başarısız
SUCCESS Ödeme başarılı
INIT_THREEDS 3D Secure başlatıldı
CALLBACK_THREEDS Bankanı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ğer Açıklama
WAITING_FOR_APPROVAL Onay bekleniyor
APPROVED Onaylanmış

Ödeme Fazları

Ödemenin bankadaki işlem tipi/fazı:

Değer Açıklama
AUTH Normal 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ğer Açıklama
CARD Kullanıcı ödemeyi kart bilgisi ile yapar
MASTERPASS Kullanıcı ödemeyi Masterpass hesabı ile yapar
PAPARA Kullanıcı ödemeyi Papara hesabı ile yapar
PAYONEER Kullanıcı ödemeyi Payoneer hesabı ile yapar
SODEXO Kullanıcı ödemeyi Sodexo hesabı ile yapar
EDENRED Kullanıcı ödemeyi Edenred hesabı ile yapar
PAYPAL Kullanıcı ödemeyi PayPal hesabı ile yapar

Para Gönderim Durumları

Para Gönderim durumunu ifade eden değerler:

Değer Açıklama
CANCELLED Para gönderimi iptal edildi
NO_PAYOUT Para gönderimi yapılmayacak
WAITING_FOR_PAYOUT Para gönderimi için bekleniyor
PAYOUT_STARTED Para gönderimi başlatıldı
PAYOUT_COMPLETED Para gönderimi tamamlandı
CANCELLED Para gönderimi iptal edilmiş

Para Gönderimi Tipi

Para Gönderimi Tiplerini ifade eden değerler:

Değer Açıklama
SETTLEMENT Ödeme/İptal/İade işlemlerinden dolayı oluşan para gönderimlerini temsil eder
BOUNCED_SETTLEMENT Parası gönderildikten sonra bazı nedenlerden dolayı parası geri dönen işlemleri tekrar göndermek için yapılan para gönderimini temsil eder
WITHDRAW Satı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ğer Açıklama
COLLECTION Ödeme/İptal/İade işlemlerinden dolayı oluşan para gönderimlerini temsil eder
BOUNCED Parası gönderildikten sonra bazı nedenlerden dolayı parası geri dönen işlemleri tekrar göndermek için yapılan para gönderimini temsil eder
WITHDRAW Satı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 Status Açıklama
0 3D Secure doğrulama veya imzası geçersiz
1 Tam Doğrulama, işleme devam edilebilir
2 Kart sahibi veya bankası sisteme kayıtlı değil
3 Kartın bankası sisteme kayıtlı değil
4 Doğrulama denemesi, kart sahibi sisteme daha sonra kayıt olmayı seçmiş
5 Doğrulama yapılamıyor
6 3D Secure hatası
7 Sistem hatası

Ödeme Kaynakları

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

Değer Açıklama
API API üzerinden
MASTERPASS Masterpass üzerinden
CHECKOUT_FORM Ödeme formu üzerinden

Alternatif Ödeme Yöntemleri

Craftgate tarafından desteklenen Alternatif Ödeme Yöntemleri

Değer Açıklama
PAPARA Papara
PAYONEER Payoneer
SODEXO Sodexo
EDENRED Edenred
PAYPAL PayPal

Direkt Alternatif Ödeme Yöntemleri

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

Değer Açıklama
FUND_TRANSFER EFT/Havale ile Ödeme
CASH_ON_DELIVERY Kapı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ğer Açıklama
REDIRECT_TO_URL Kullanıcı, cevap içerisinde yer alan redirectUrl adresine yönlendirilmelidir.
OTP_REQUIRED Kullanıcıdan OTP doğrulama kodu alınmalıdır.
NONE Ek bir aksiyon alınmasına gerek bulunmamaktadır.

Ödül Tipleri

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

Değer Açıklama
REWARD_MONEY Puan Kullanımı
ADDITIONAL_INSTALLMENT Ek Taksit
POSTPONING_INSTALLMENT Taksit Atlatma
EXTRA_POINTS Ekstra Puan
GAINING_MINUTES Kontör Kazanım
POSTPONING_STATEMENT Ekstre Erteleme

İadeler

İade Durumları

Bir iadenin durumunu ifade eden değerlerdir.

Değer Açıklama
SUCCESS Başarılı
FAILURE Başarısız

İade Durumları

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

Değer Açıklama
NO_REFUND Ödeme başarılı değil
NOT_REFUNDED İadesi bulunmuyor
PARTIAL_REFUNDED Parçalı iade edilmiş
FULLY_REFUNDED İade edilmiş

İade Tipleri

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

Değer Açıklama
PROVIDER Ödemenin alındığı yere (Karta ya da APM e)
WALLET Cüzdana

Para Gönderimi

Para Gönderim Talebi Sonuç Durumları

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

Değer Açıklama
SUCCESS Para gönderimi başarıyla tamamlandı.
FAILURE Para gönderimi gerçekleştirilemedi.
NO_RECORD_FOUND Para 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ğer Açıklama
REDEEM_ONLY_LOYALTY Sadakat 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ğer Açıklama
CSV Comma Separated Values dosya tipi uzantısı.
XLSX Excel 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-key API erişim anahtarı
x-rnd-key İsteğe özel oluşturulmuş rastgele bir string değer
x-auth-version Kimlik doğrulama algoritmasınin versiyon numarası. Hangi değeri vermeniz gerektiğinden emin değilseniz V1 verebilirsiniz
x-signature Yukarı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
  • Hash'in Base64 ile şifrelenmiş halini hesapla

Örnek 1

Parametreler
Ad Değer
İstek URL https://api.craftgate.io/onboarding/v1/members/1
Request Body -
API Key key-1
Secret Key FooBar123!
Random Key Xa15Fp11T
İ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
Ad Değer
x-api-key key-1
x-rnd-key rGciw1df
x-auth-version V1
x-signature y1TtnjNCJEvlkP5ufCkK3H0i2guMB/bKL4Ayw3VlKWA=

Örnek 2

Parametreler
Ad Değer
İstek URL https://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","identityNumber": "11111111110","contactName": "Haluk","contactSurname": "Demir","memberExternalId": "0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
API Key key-1
Secret Key FooBar123!
Random Key Xa15Fp11T
İ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","identityNumber": "11111111110","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","identityNumber": "11111111110","contactName": "Haluk","contactSurname": "Demir","memberExternalId": "0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Signature:
    nv8y2bSnFjYNRzVRqzkHTK5RXKuN04hoK6fLE2+nzTw=
İsteğe Eklenecek Header'lar
Ad Değer
x-api-key key-1
x-rnd-key Xa15Fp11T
x-auth-version V1
x-signature pYuONv7/IgM14OAuSoANWUUgfVSwRX3bYeSZLXltb04=