API Dokümantasyonu Versiyon: 1.0.2 Son güncelleme: 21.04.2025
Dil
Başlangıç

Shopinext API ile iletişim JSON formatında gerçekleştirilir. Sizinle paylaşılan "İstemci Kimliği" ve "İstemci Gizli Anahtarı" bilgileri, tüm API taleplerinizde kullanılması gereken "Erişim Token"i talep etmek için kullanılmalıdır. "Erişim Tokeni" 1 saat geçerlidir. Bu süreden sonra "Yenileme Tokeni" (24 saat geçerlidir) kullanarak yeni bir "Erişim Token"i oluşturmanız gerekir.

Shopinext API'si üzerinden ödeme talepleri oluşturabilir ve ödemelerinizin durumunu sorgulayabilirsiniz. Ödeme oluştururken bir "Geri Arama URL'si" tanımlayarak ödeme durumu güncellemeleri gerçek zamanlı olarak alabilirsiniz. Ayrıca, taksit ve komisyon bilgilerine API üzerinden erişebilirsiniz.

API hizmetini kullanmak için, Shopinext tarafından bu hizmet için yetkilendirilmiş olmanız gerekir. Sorularınızı ve destek taleplerinizi support@shopinext.com e-posta adresimize gönderebilirsiniz.

Uç Noktalar
API Canlı Ortamı:
https://api.shopinext.com

API Test Ortamı:
https://apidev.shopinext.com
Kimlik Doğrulama

Bir "Erişim Token"i oluşturmak için, aşağıda belirtilen uç noktaya "İstemci Kimliği" ve "İstemci Gizli Anahtarı" bilgileriyle bir talep göndermeniz gerekir. "Erişim Token"i 1 saat geçerlidir. Bu süre dolmadan önce, "Yenileme Token"i kullanarak yeni bir "Erişim Token"i (24 saat geçerlidir) oluşturmanız gerekir.

POST /authenticate
İSTEK PARAMETRELERİ - POST

Parametre Tür Açıklama Gerekli
client_id String İstemci Kimliği Evet
client_secret String İstemci Gizli Anahtarı Evet

POST /refreshToken
İSTEK PARAMETRELERİ - POST

Parametre Tür Açıklama Gerekli
refresh_token String Yenileme Tokeni Evet

POST/authenticate
Talep
{
    "client_id": "SNT98s721xsaS96S",
    "client_secret": "SNC71219sz77As"
}
Cevap
{
    "status": 1,
    "access_token": "SNT98s721xsaS96S",
    "refresh_token": "SNC71219sz77As",
    "access_token_validity": "2025-04-17 00:00:00",
    "refresh_token_validity": "2025-04-18 00:00:00"
}
POST/refreshToken
Talep
{
    "refresh_token": "SNR123s2998asdXZSA"
}
Cevap
{
    "status": 1,
    "access_token": "SNT98s721xsaS96S",
    "refresh_token": "SNC71219sz77As",
    "access_token_validity": "2025-04-17 00:00:00",
    "refresh_token_validity": "2025-04-18 00:00:00"
}
Ödeme Oluştur

Bir ödeme oluşturmak için, aşağıdaki parametrelerle yeni bir talep oluşturun. Ödeme güncellemeleri, ödeme nihai bir sonuca ulaşana kadar "Geri Arama URL'si" olarak belirttiğiniz URL adresine gönderilecektir.

POST /createPayment
İSTEK PARAMETRELERİ - POST

Parametre Tür Açıklama Gerekli
firstname String Müşteri Adı Evet
surname String Müşteri Soyadı Evet
email String Müşteri E-Postası Evet
phone String Müşteri Telefonu Evet
amount Double Toplam Tutar Evet
currency String Para Birimi - TRY, USD, EUR, GBP Evet
max_installment Integer Maks. Taksit Sayısı - Varsayılan 1 Hayır
merchant_order_id String Satıcı Sipariş ID Evet
identity_number String Kimlik Numarası Evet
company String Şirket Hayır
tax_office String Vergi Dairesi Hayır
tax_number String Vergi Numarası Hayır
is_digital Integer Dijital Ürünlerden Oluşan Sipariş Evet
order_products Nesne dizisi Sipariş Ürünleri Evet
billing_info Nesne Faturalandırma Bilgileri Evet
shipping_info Nesne Teslimat Bilgileri Evet
success_url String Başarılı Ödeme Sayfası URL Evet
fail_url String Hata Sayfası URL Evet
callback_url String Callback URL (Webhook) Evet
language String Varsayılan Dil: TR (TR, EN, DE) Hayır

POST/createPayment
Talep
{
    "firstname": "Hasan",
    "surname": "Öncel",
    "email": "test@shopinext.com",
    "amount": 200.00,
    "currency": "TRY",
    "max_installment": 1,
    "merchant_order_id": "XXXXXXXX",
    "identity_number": "11111111111",
    "company": "",
    "tax_office": "",
    "tax_number": "",
    "is_digital": 0,
    "order_products": [{
        "name": "Deneme",
        "quantity": 2,
        "price": 100,
        "total": 200
    }],
    "billing_info": {
        "billing_firstname": "Hasan",
        "billing_surname": "Öncel",
        "billing_address": "Örnek Mah. Örnek Sok. No: 3/4",
        "billing_city": "Beşiktaş",
        "billing_state": "İstanbul",
        "billing_postal_code": "34330",
        "billing_country": "TR",
        "billing_country_code": "+90",
        "billing_phone": "5445553366"
    },
    "shipping_info": {
        "shipping_firstname": "Hasan",
        "shipping_surname": "Öncel",
        "shipping_address": "Örnek Mah. Örnek Sok. No: 3/4",
        "shipping_city": "Beşiktaş",
        "shipping_state": "İstanbul",
        "shipping_postal_code": "34330",
        "shipping_country": "TR",
        "shipping_country_code": "+90",
        "shipping_phone": "905445553366"
    },
    "success_url": "https://www.example.com/success_url",
    "fail_url": "https://www.example.com/fail_url",
    "callback_url": "https://www.example.com/callback",
    "language": "TR"
}
Cevap
{
    "status": 1,
    "payment_id": "S1234567890",
}
Webhook

Bir ödeme oluşturduktan sonra ödeme nihai şekilde sonuçlanana kadar ödeme oluşturma isteğinde bildirdiğiniz "Callback URL" adresine ödemenin durumu ile ilgili güncellemeler iletilir. Size iletilen isteğe alındı onayı olarak "OK" cevabını dönmeniz gerekmektedir. Aksi halde 48 saat boyunca güncellemeler tarafınıza iletilmeye devam edilir. Talebin Shopinext'den geldiğini teyit edebilmeniz adına istek içerisinde "hash" bilgisi yer almaktadır. Bu bilgi istemci kimliği ve istemci gizli anahtarının sha256 algoritması ile şifrelenmesi sonucunda oluşur.

# Durum Durum Kodu
1 İşleniyor processing
2 Başarılı successful
3 Başarısız unsuccessful
4 İptal Edildi cancelled
5 İade Edildi refunded
6 Kısmi İade partially_refunded

POSTWebhook - CALLBACK_URL
Talep
{
    "payment_id": "S1234567890",
    "status": "processing",
    "hash": "5e4ff8ebb5fe84d8c7968ce..."
}
Cevap
OK
Ödeme Listesi Sorgula

Bir tarih aralığı belirterek ödeme sorgulamak için, kimlik doğrulama sırasında oluşturulan "token"ı "startdate" ve "enddate" parametreleriyle birlikte sağlamanız gerekir. Tek seferde en fazla 45 günlük aralık sorgulayabilirsiniz.

GET /getPayments
İSTEK PARAMETRELERİ - GET

Parametre Tür Açıklama Gerekli
startdate String Başlangıç Tarihi (YYYY-MM-DD HH:mm:ss) Evet
enddate String Bitiş Tarihi (YYYY-MM-DD HH:mm:ss) Evet

# Durum Durum Kodu
1 İşleniyor processing
2 Başarılı successful
3 İptal Edildi cancelled
4 İade Edildi refunded
5 Kısmi İade partially_refunded

GET/getPayments
Talep
{
    "startdate": "2024-06-19 00:00:00"
    "enddate": "2024-06-19 23:59:59"
}
Cevap
{
    "status": 1
    "payments": [{
        "payment_id": "S1234567890",
        "merchant_order_id": "X12T55A",
        "firstname": "Hasan",
        "surname": "Öncel",
        "email": "test@shopinext.com",
        "channel": "API",
        "domain": "www.shopinext.com",
        "status_type": "Sales",
        "status": "Successful",
        "amount": 200.00,
        "currency": "TRY",
        "installment": 1,
        ""currency_rates": "{\"USD\":\"36.4792\",\"EUR\":\"38.0094\",\"GBP\":\"46.006\"}",         "commission": 5.9,
        "transaction_fee": 0.5,
        "vat": 1.28,
        "is_digital": 0,
        "identity_number": "11111111111",
        "company": "",
        "tax_office": "",
        "tax_number": ""
        "payment_date": "2024-06-19 15:00:00"
        "payment_note": ""
        "order_products": [{
            "name": "Deneme",
            "quantity": 2,
            "price": 100,
            "total": 200
        }],
        "billing_info": {
            "billing_firstname": "Hasan",
            "billing_surname": "Öncel",
            "billing_address": "Örnek Mah. Örnek Sok. No: 3/4",
            "billing_city": "Beşiktaş",
            "billing_state": "İstanbul",
            "billing_postal_code": "34330",
            "billing_country": "TR",
            "billing_country_code": "+90",
            "billing_phone": "5445553366"
        },
        "shipping_info": {
            "shipping_firstname": "Hasan",
            "shipping_surname": "Öncel",
            "shipping_address": "Örnek Mah. Örnek Sok. No: 3/4",
            "shipping_city": "Beşiktaş",
            "shipping_state": "İstanbul",
            "shipping_postal_code": "34330",
            "shipping_country": "TR",
            "shipping_country_code": "+90",
            "shipping_phone": "5445553366"
        },
        "created_at": "2024-06-19 01:03:00"
    }]
}
Tek Ödeme Sorgula

Tek bir ödemenin bilgilerini sorgulamak için, kimlik doğrulama sırasında oluşturulan "token" ile birlikte Shopinext Ödeme Kimliği bilgilerini sağlamanız gerekir.

API hizmetini kullanmak için Sanal POS hizmetinizi kullanıyor olmanız gerekir. Sorularınızı ve destek taleplerinizi support@shopinext.com e-posta adresimize gönderebilirsiniz.

GET /getPayment
İSTEK PARAMETRELERİ - GET

Parametre Tür Açıklama Gerekli
payment_id String Shopinext Ödeme ID Evet

# Durum Durum Kodu
1 İşleniyor processing
2 Başarılı successful
3 İptal Edildi cancelled
4 İade Edildi refunded
5 Kısmi İade partially_refunded

GET/getPayment
Talep
{
    "payment_id": "S1234567890"
}
Cevap
{
    "status": 1
    "payment": {
        "payment_id": "S1234567890",
        "merchant_order_id": "X12T55A",
        "firstname": "Hasan",
        "surname": "Öncel",
        "email": "test@shopinext.com",
        "channel": "API",
        "domain": "www.shopinext.com",
        "status_type": "Sales",
        "status": "Successful",
        "amount": 200.00,
        "currency": "TRY",
        "installment": 1,
        ""currency_rates": "{\"USD\":\"36.4792\",\"EUR\":\"38.0094\",\"GBP\":\"46.006\"}",         "commission": 5.9,
        "transaction_fee": 0.5,
        "vat": 1.28,
        "is_digital": 0,
        "identity_number": "11111111111",
        "company": "",
        "tax_office": "",
        "tax_number": ""
        "payment_date": "2024-06-19 15:00:00"
        "payment_note": ""
        "order_products": [{
            "name": "Deneme",
            "quantity": 2,
            "price": 100,
            "total": 200
        }],
        "billing_info": {
            "billing_firstname": "Hasan",
            "billing_surname": "Öncel",
            "billing_address": "Örnek Mah. Örnek Sok. No: 3/4",
            "billing_city": "Beşiktaş",
            "billing_state": "İstanbul",
            "billing_postal_code": "34330",
            "billing_country": "TR",
            "billing_country_code": "+90",
            "billing_phone": "5445553366"
        },
        "shipping_info": {
            "shipping_firstname": "Hasan",
            "shipping_surname": "Öncel",
            "shipping_address": "Örnek Mah. Örnek Sok. No: 3/4",
            "shipping_city": "Beşiktaş",
            "shipping_state": "İstanbul",
            "shipping_postal_code": "34330",
            "shipping_country": "TR",
            "shipping_country_code": "+90",
            "shipping_phone": "5445553366"
        },
        "created_at": "2024-06-19 01:03:00"
    }
}
Taksit Bilgileri

Shopinext hesabınızda tanımlanan taksit bilgilerini döndürür.

GET /getInstallments
GET/getInstallments
Talep
Boş
Cevap
{
    "status": 1
    "installments": [{
        "installmentCount": 2,
        "installmentRate": 5.99
    }, {
        "installmentCount": 3,
        "installmentRate": 6.99
    }, {
        "installmentCount": 4,
        "installmentRate": 7.99
    }]
}
Komisyon Bilgileri

Shopinext hesabınızda tanımlı komisyon bilgileri hakkında bilgi alabilirsiniz.

GET /getCommissions
GET/getCommissions
Talep
Boş
Cevap
{
    "status": 1
    "commissions": {
        "try_commission": 5.99,
        "try_transaction_fee": 0.25,
        "try_commission_int": 5.99,
        "try_transaction_fee_int": 0.25,
        "usd_commission": 5.99,
        "usd_transaction_fee": 0.25,
        "eur_commission": 5.99,
        "eur_transaction_fee": 0.25,
        "gbp_commission": 5.99,
        "gbp_transaction_fee": 0.25,
        "btc_commission": 5.99,
        "btc_transaction_fee": 0.25,
        "eth_commission": 5.99,
        "eth_transaction_fee": 0.25
    }
}
Hata Kodları

Shopinext API'si aşağıda belirtilen hata kodlarını kullanır:

Hata Kodu Açıklama
SNE1 Token oluşturma başarısız oldu. Sağladığınız kimlik doğrulama bilgileri yanlış.
SNE2 Eksik parametre. Gerekli bir parametre sağlamadınız.
SNE3 Ödeme Kimliği bulunamadı. Sağladığınız açıklamayla ödeme yok.
SNE4 Tarih aralığı yanlış. "startdate" ve "enddate" parametrelerini kontrol edin.
SNE5 Ödeme oluşturma başarısız oldu. Parametreleri kontrol edin.
SNE6 Sistem Hatası. Lütfen bizimle iletişime geçin.
SNE7 İstenen para birimi için yetkiniz yok.
SNE8 Satış limitini aştınız.
SNE9 Kart altyapısı desteklenmiyor.
SNE10 Bu IP adresi ile işlem yapma yetkiniz bulunmamaktadır.
SNE11 Bu domain üzerinden işlem yapma yetkiniz bulunmamaktadır.
SNE12 En fazla 45 günlük tarih aralığı belirtebilirsiniz.

Test Kartları

Aşağıdaki kredi kartı bilgilerini test işlemleri için kullanabilirsiniz.

Kart Numarası Son kullanım CVV 3D Şifre
4546 7112 3456 7894 12/2026 000 a
5401 3412 3456 7891 12/2026 000 a

Destek

Destek talepleriniz için bize e-posta yoluyla ulaşabilirsiniz.

support@shopinext.com

API Uç Noktaları
API Canlı Ortamı:
https://api.shopinext.com

API Test Ortamı:
https://api.dev.shopinext.com
POST/authenticate
Talep
{
    "client_id": "SNT98s721xsaS96S",
    "client_secret": "SNC71219sz77As"
}
Cevap
{
    "status": 1,
    "access_token": "SNT98s721xsaS96S",
    "refresh_token": "SNC71219sz77As",
    "access_token_validity": "2025-04-17 00:00:00",
    "refresh_token_validity": "2025-04-18 00:00:00"
}
POST/refreshToken
Talep
{
    "refresh_token": "SNR123s2998asdXZSA"
}
Cevap
{
    "status": 1,
    "access_token": "SNT98s721xsaS96S",
    "refresh_token": "SNC71219sz77As",
    "access_token_validity": "2025-04-17 00:00:00",
    "refresh_token_validity": "2025-04-18 00:00:00"
}
POST/createPayment
Talep
{
    "firstname": "Hasan",
    "surname": "Öncel",
    "email": "test@shopinext.com",
    "amount": 200.00,
    "currency": "TRY",
    "max_installment": 1,
    "merchant_order_id": "XXXXXXXX",
    "identity_number": "11111111111",
    "company": "",
    "tax_office": "",
    "tax_number": "",
    "is_digital": 0,
    "order_products": [{
        "name": "Deneme",
        "quantity": 2,
        "price": 100,
        "total": 200
    }],
    "billing_info": {
        "billing_firstname": "Hasan",
        "billing_surname": "Öncel",
        "billing_address": "Örnek Mah. Örnek Sok. No: 3/4",
        "billing_city": "Beşiktaş",
        "billing_state": "İstanbul",
        "billing_postal_code": "34330",
        "billing_country": "TR",
        "billing_country_code": "+90",
        "billing_phone": "5445553366"
    },
    "shipping_info": {
        "shipping_firstname": "Hasan",
        "shipping_surname": "Öncel",
        "shipping_address": "Örnek Mah. Örnek Sok. No: 3/4",
        "shipping_city": "Beşiktaş",
        "shipping_state": "İstanbul",
        "shipping_postal_code": "34330",
        "shipping_country": "TR",
        "shipping_country_code": "+90",
        "shipping_phone": "905445553366"
    },
    "success_url": "https://www.example.com/success_url",
    "fail_url": "https://www.example.com/fail_url",
    "callback_url": "https://www.example.com/callback",
    "language": "TR"
}
Cevap
{
    "status": 1,
    "payment_id": "S1234567890"
}
POSTWebhook - CALLBACK_URL
Talep
{
    "payment_id": "S1234567890",
    "status": "successful",
    "hash": "5e4ff8ebb5fe84d8c7968ce..."
}
Cevap
OK
GET/getPayments
Talep
{
    "startdate": "2024-06-19 00:00:00",
    "enddate": "2024-06-19 23:59:59"
}
Cevap
{
    "status": 1
    "payments": [{
        "payment_id": "S1234567890",
        "merchant_order_id": "X12T55A",
        "firstname": "Hasan",
        "surname": "Öncel",
        "email": "test@shopinext.com",
        "channel": "API",
        "domain": "www.shopinext.com",
        "status_type": "Sales",
        "status": "Successful",
        "amount": 200.00,
        "currency": "TRY",
        "installment": 1,
        ""currency_rates": "{\"USD\":\"36.4792\",\"EUR\":\"38.0094\",\"GBP\":\"46.006\"}",         "commission": 49.9,
        "transaction_fee": 0.5,
        "vat": 10.08,
        "is_digital": 0,
        "identity_number": "11111111111",
        "company": "",
        "tax_office": "",
        "tax_number": ""
        "payment_date": "2024-06-19 15:00:00"
        "payment_note": ""
        "order_products": [{
            "name": "Deneme",
            "quantity": 2,
            "price": 100,
            "total": 200
        }],
        "billing_info": {
            "billing_firstname": "Hasan",
            "billing_surname": "Öncel",
            "billing_address": "Örnek Mah. Örnek Sok. No: 3/4",
            "billing_city": "Beşiktaş",
            "billing_state": "İstanbul",
            "billing_postal_code": "34330",
            "billing_country": "TR",
            "billing_country_code": "+90",
            "billing_phone": "5445553366"
        },
        "shipping_info": {
            "shipping_firstname": "Hasan",
            "shipping_surname": "Öncel",
            "shipping_address": "Örnek Mah. Örnek Sok. No: 3/4",
            "shipping_city": "Beşiktaş",
            "shipping_state": "İstanbul",
            "shipping_postal_code": "34330",
            "shipping_country": "TR",
            "shipping_country_code": "+90",
            "shipping_phone": "5445553366"
        },
        "created_at": "2024-06-19 01:03:00"
    }]
}
GET/getPayment
Talep
{
    "payment_id": "S1234567890"
}
Cevap
{
    "status": 1
    "payment": {
        "payment_id": "S1234567890",
        "merchant_order_id": "X12T55A",
        "firstname": "Hasan",
        "surname": "Öncel",
        "email": "test@shopinext.com",
        "channel": "API",
        "domain": "www.shopinext.com",
        "status_type": "Sales",
        "status": "Successful",
        "amount": 200.00,
        "currency": "TRY",
        "installment": 1,
        ""currency_rates": "{\"USD\":\"36.4792\",\"EUR\":\"38.0094\",\"GBP\":\"46.006\"}",         "commission": 5.9,
        "transaction_fee": 0.5,
        "vat": 1.28,
        "is_digital": 0,
        "identity_number": "11111111111",
        "company": "",
        "tax_office": "",
        "tax_number": ""
        "payment_date": "2024-06-19 15:00:00"
        "payment_note": ""
        "order_products": [{
            "name": "Deneme",
            "quantity": 2,
            "price": 100,
            "total": 200
        }],
        "billing_info": {
            "billing_firstname": "Hasan",
            "billing_surname": "Öncel",
            "billing_address": "Örnek Mah. Örnek Sok. No: 3/4",
            "billing_city": "Beşiktaş",
            "billing_state": "İstanbul",
            "billing_postal_code": "34330",
            "billing_country": "TR",
            "billing_country_code": "+90",
            "billing_phone": "5445553366"
        },
        "shipping_info": {
            "shipping_firstname": "Hasan",
            "shipping_surname": "Öncel",
            "shipping_address": "Örnek Mah. Örnek Sok. No: 3/4",
            "shipping_city": "Beşiktaş",
            "shipping_state": "İstanbul",
            "shipping_postal_code": "34330",
            "shipping_country": "TR",
            "shipping_country_code": "+90",
            "shipping_phone": "5445553366"
        },
        "created_at": "2024-06-19 01:03:00"
    }
}
GET/getInstallments
Talep
Boş
Cevap
{
    "status": 1
    "installments": [{
        "installmentCount": 2,
        "installmentRate": 5.99
    }, {
        "installmentCount": 3,
        "installmentRate": 6.99
    }, {
        "installmentCount": 4,
        "installmentRate": 7.99
    }]
}
GET/getCommissions
Talep
Boş
Cevap
{
    "status": 1
    "commissions": {
        "try_commission": 5.99,
        "try_transaction_fee": 0.25,
        "try_commission_int": 5.99,
        "try_transaction_fee_int": 0.25,
        "usd_commission": 5.99,
        "usd_transaction_fee": 0.25,
        "eur_commission": 5.99,
        "eur_transaction_fee": 0.25,
        "gbp_commission": 5.99,
        "gbp_transaction_fee": 0.25,
        "btc_commission": 5.99,
        "btc_transaction_fee": 0.25,
        "eth_commission": 5.99,
        "eth_transaction_fee": 0.25
    }
}