GİRİŞ

    API Endpoint
        https://api.imzapos.com/
                

Test Kullanıcı Bilgileri

Bayi Kodu 16
Kullanıcı Adı apitest
Şifre [email protected]*DK?rbu[_w4/
API Anahtarı R_48%Y3;Sk]mXwT

TOKEN ALMA


    curl --request POST \
    --url https://api.imzapos.com/api/v1/token \
    --header 'Content-Type: application/json' \
    --data '{
    "resellerId":16,
    "userName":"apitest",
    "password":"[email protected]*DK?rbu[_w4/"
    }'
    
    
            Response Örneği:
            {
            "status": true,
            "statusCode": 200,
            "data": {
            "token": "chSRNKH9vbrzJOxzLplOzDn9X62v0dl3rnCFo5n9uOKcK7zWVOh0Ro2Y3S3RSVJRzyHfLsLQClek3LzaGgam6vlDunLVBWrZF2mVzUKnCQyqJRfsddLw5gVENEvhgzOp4EfAidlwWwjp753cIc2iL5eihiIuimGNCIwEwfJ91ZaI7pGSKSZD6qe8k6cAU0NtpWnyJyqnT3qwfVl2b0kQMDQVoxdzCJoBMqckCRJVmwuDAsdPVjieP6gmGSKVU0kJ",
            "expire_date": "3000-01-01T00:00:00",
            "expire_at": 60
            }
            }
        

Token süresi response içerisinde dakika cinsinden ve expire date olarak belirtilmektedir. Mevcut sürümde 1 saattir.

Mevcut token expire olana kadar kullanılması, uygulama performansı açısından tavsiye edilmektedir.

Token Kullanımı

Authorization key olarak "Bearer" kullanılmaktadır.

İstek "Header" bölümüne "Authorization" anahtar kelimesi ile "Bearer + token" değeri girilmelidir.

Request Parametreleri

Parametre Adı Tipi Zorunlu Açıklaması
resellerId Integer * Bayi Kodu
userName String * Kullanıcı Adı
password String * Şifre

Response Parametreleri

Parametre Adı Tipi Açıklaması
token String Token İçeriği
expire_date DateTime Token Süre Dolum Tarihi(UTC)
expire_at Integer Token Süre Dolum Dakikası

Hash Üretme

Yapılacak her istekte Token yanı sıra, Store Key ile şifrelenmiş bir hash değeri oluşturulması gerekir.

Hash oluşturulurken bazı random değerler kullanılır. Bu değerleri Header ile API'ye belirtmeniz gerekmektedir.

Header Adı Açıklaması
x-random İsteğe özel oluşturulmuş, minimum 20 karakter uzunluğunda rastgele bir string değer
x-hash Hash oluşturma algoritması ile oluşturulmuş değer.

Hash Hesaplama

Hash bazı anahtarların uç uca bağlanması ile(arada boşluk ya da herhangi bir karakter olmadan) oluşturulan bir değerdir

Sırası ile

  • İstek body'sinin Base64 Encode hali(İstek body'si boşsa eklemeyiniz)
  • Header alanında oluşturduğunuz "x-random" değeri
  • API Anahtarı

Örnek 1

Parametre Değer
İstek Body
x-random d885f1b2-07e9-47f4-a7bc-44699d3919e1
Api Key R_48%Y3;Sk]mXwT

Yukarıdaki değerler ile oluşturulan bir hash değerinin sonucu "lhceKXBqAPsayVzHhL6L/5a4o37UPbVuSxXuvwvmPYU=" olacaktır.

Örnek 2

Parametre Değer
İstek Body {"param1":"param", "param2":4, "param3":"3000-01-01"}
x-random b97a868e-d1bc-4eb1-bfc6-7308f3162d78
Api Key R_48%Y3;Sk]mXwT

Yukarıdaki değerler ile oluşturulan bir hash değerinin sonucu "U+0UETNzHZHr7YHms3Tc0t8pSDNTWZi0nV3gbbhBpXc=" olacaktır.

Non-Secure Ödeme

    
            curl --request POST \
            --url https://api.imzapos.com/api/v1/payment/non-secure \
            --header 'Authorization: Bearer chSRNKH9vbrzJOxzLplOzDn9X62v0dl3rnCFo5n9uOKcK7zWVOh0Ro2Y3S3RSVJRzyHfLsLQClek3LzaGgam6vlDunLVBWrZF2mVzUKnCQyqJRfsddLw5gVENEvhgzOp4EfAidlwWwjp753cIc2iL5eihiIuimGNCIwEwfJ91ZaI7pGSKSZD6qe8k6cAU0NtpWnyJyqnT3qwfVl2b0kQMDQVoxdzCJoBMqckCRJVmwuDAsdPVjieP6gmGSKVU0kJ' \
            --header 'Content-Type: application/json' \
            --header 'x-hash: R3JskSf3HE79k9T9uUKAcmhX003s63Q7m6eEmeblUzo=' \
            --header 'x-random: 3ad657cc-5526-4728-88c5-9b4d0e87f793' \
            --data '{"payment_type":"Auth","reference_transaction_id":"daae358c-b0e7-4070-a867-9cbeb142d568","card_owner_name":"YILMAZ ERDOGAN","card_bin":"4022780000000000","exp_month":"10","exp_year":"3000","cvv":"000","installment":1,"client_ip":"192.168.1.1","amount":104,"currency":"TRY","buyer":{"name":"YILMAZ","surname":"ERDOGAN"},"productList":[{"name":"Ürün1","price":31.12,"quantity":1},{"name":"Ürün2","price":12.01,"quantity":1}]}'
        
                
    
            Response Örneği:
            {
            "status": false,
            "statusCode": 1001,
            "data": {
            "oid": "45365649-0c78-435e-8041-1afa5f288c15",
            "reference_transaction_id": "daae358c-b0e7-4070-a867-9cbeb142d568",
            "payment_type": "Auth",
            "secure_flag": false,
            "reseller_id": 16,
            "user_id": 0,
            "gateway_provider": "provider",
            "amount": 1.04,
            "currency": "TRY",
            "installment": 1,
            "cost_rate": 1.00,
            "sale_rate": 0.00,
            "card_owner_name": "YILMAZ ERDOGAN",
            "card_number": "402278******0000",
            "client_ip": "192.168.1.1",
            "payment_status": 7,
            "status_code": 1001,
            "status_code_description": "Bilinmeyen Hata. Hata Detayına Bakınız",
            "provider_status_message": "41-Kredi karti numarasi gecerli formatta degil.-",
            "provider_reference_id": "164244680950685",
            "transaction_date": "0001-01-01T00:00:00"
            },
            "errors": [
            "Bilinmeyen Hata. Hata Detayına Bakınız"
            ]
            }
        

3D şifre koruması olmadan yapılan ödeme türüdür. Kart sahibine herhangi bir onay mesajı gitmeden ödeme hesaba geçer

Request Parametreleri

Parametre Adı Tipi Zorunlu Açıklaması
payment_type String * Ödeme almak için "Auth", Ön Otorizasyon(Provizyon) için "PreAuth" gönderilmelidir
reference_transaction_id String * Üye iş yerinin işlem için vermiş olduğu değerdir. Her işlem için Unique olmak zorundadır
card_owner_name String * Kart Sahibinin Adı
card_bin String * Kart Numarası
exp_month String * Kart Son Kullanım Tarihinde Ay değeri(tek rakamlı değerlerde 0 ile tamamlanmalıdır. Ör:08)
exp_year String * Kart Son Kullanım Yılı. 4 Basamalı olarak gönderilmelidir
cvv String * Kart Güvenlik Numarası
installment Integer * Taksit Sayısı. Tek Çekim için 1 gönderilmelidir
client_ip String * İşlem yapan kullanıcının IP Adresi
amount Integer * İşlem tutarıdır. Kuruş ayracı olmadan gönderilmelidir. Örneğin 1 TL için 100, 25 TL için 2500, 3.01 TL için 301, 5.6 TL için 560
currency String * Para birimi. Sadece izniniz olan para birimleri kullanılabilir
buyer VeriSeti * Alıcı Bilgisidir
buyer.name String * Alıcı Adı
buyer.surname String * Alıcı Soyadı
productList VeriSetiListesi * Sipariş Ürün Listesi
productList.name String * Ürün Adı
productList.price Decimal * Ürün Fiyatı
productList.quantity Integer * Ürün Adeti

Response Parametreleri

Parametre Adı Tipi Açıklaması
oid String API tarafından işleminiz için verilen kod. Bu kodun saklanması gerekmektedir. Bazı özel durumlarsa sadece bu kod ile işlem yapabilirsiniz
gateway_provider String İşleminizin hangi ödeme sağlayıcı aracılığı ile yapıldığı bilgisidir
cost_rate Decimal Maliyet oranınız
sale_rate Decimal Satış oranınız
payment_status Integer Ödeme durumu. 7 ise işlem başarısız, 10 ise işlem başarılıdır. Buradaki değere göre işleminizi sonlandırabilirsiniz.
status_code Integer Durum Kodu. Durum Kodu Listesi içerisinden detaylarını öğrenebilirsiniz
status_code_description String Durum Kodu açıklaması. Durum Kodu Listesi içerisinden detaylarını öğrenebilirsiniz
provider_status_message String Ödeme sağlayıcının döndüğü mesajdır. Bazı ödeme sağlayıcılarının hata kodları tekilleştirilememektedir. "status_code" değeri 1001 döndüğü zaman, bu alanı incelemeniz tavsiye edilir
provider_reference_id String Ödeme sağlayıcının işleme verdiği numaradır. Ödeme sağlayıcı ile iletişime geçerken bu kodu belirtebilirsiniz.

3D-Secure Ödeme

    
            curl --request POST \
            --url https://api.imzapos.com/api/v1/payment/3d-secure \
            --header 'Authorization: basic MTY6YXBpdGVzdDpGeDlAKkRLP3JidVtfdzQv' \
            --header 'Content-Type: application/json' \
            --header 'x-hash: np8YX1OaSbIam6DBzmHGVHEvP2MYrD151zdBJIHAxl0=' \
            --header 'x-random: 46697aa9-ed4d-454e-9d89-a751fd9b242d' \
            --data '{"payment_type":"Auth","reference_transaction_id":"daae358c-b0e7-4070-a867-9cbeb142d568","card_owner_name":"YILMAZ ERDOGAN","card_bin":"4022780000000000","exp_month":"10","exp_year":"3000","cvv":"000","installment":1,"client_ip":"192.168.1.1","amount":104,"currency":"TRY","success_url":"https://domain.com#success","error_url":"https://domain.com#error","buyer":{"name":"YILMAZ","surname":"ERDOGAN"},"productList":[{"name":"Ürün1","price":31.12,"quantity":1},{"name":"Ürün2","price":12.01,"quantity":1}]}'
        
                
    
            Response Örneği:
            {
            "status": true,
            "statusCode": 10,
            "data": {
            "redirect_url": "https://api.imzapos.com/redirect-service/3d-secure/c76hEaqtAwu3dYTQ4G8YjW35zQXrT1MxJSyfoeKS0D8bHYZK6F3TqyPFEAsxC9ZJ",
            "expire_date": "3000-01-01T00:00:00",
            "expire_at": 1
            }
            }
        

3D şifre koruması ile yapılan ödeme türüdür

İstek yapıldıktan sonra "redirect_url" parametresi dönülür. Kart sahibi bu url'e yönledirilmelidir.

Request Parametreleri

Parametre Adı Tipi Zorunlu Açıklaması
payment_type String * Ödeme almak için "Auth", Ön Otorizasyon(Provizyon) için "PreAuth" gönderilmelidir
reference_transaction_id String * Üye iş yerinin işlem için vermiş olduğu değerdir. Her işlem için Unique olmak zorundadır
card_owner_name String * Kart Sahibinin Adı
card_bin String * Kart Numarası
exp_month String * Kart Son Kullanım Tarihinde Ay değeri(tek rakamlı değerlerde 0 ile tamamlanmalıdır. Ör:08)
exp_year String * Kart Son Kullanım Yılı. 4 Basamalı olarak gönderilmelidir
cvv String * Kart Güvenlik Numarası
installment Integer * Taksit Sayısı. Tek Çekim için 1 gönderilmelidir
client_ip String * İşlem yapan kullanıcının IP Adresi
amount Integer * İşlem tutarıdır. Kuruş ayracı olmadan gönderilmelidir. Örneğin 1 TL için 100, 25 TL için 2500, 3.01 TL için 301, 5.6 TL için 560
currency String * Para birimi. Sadece izniniz olan para birimleri kullanılabilir
success_url String * Çekim işlemi başarılı sonuçlanırsa yönlendirilecek URL bilgisi
error_url String * Çekim işlemi hatalı sonuçlanırsa yönlendirilecek URL bilgisi
buyer VeriSeti * Alıcı Bilgisidir
buyer.name String * Alıcı Adı
buyer.surname String * Alıcı Soyadı
productList VeriSetiListesi * Sipariş Ürün Listesi
productList.name String * Ürün Adı
productList.price Decimal * Ürün Fiyatı
productList.quantity Integer * Ürün Adeti

Response Parametreleri

Parametre Adı Tipi Açıklaması
redirect_url String Son kullanıcının yönlendirileceği URL bilgisi
expire_date DateTime Token Süre Dolum Tarihi(UTC)
expire_at Integer Token Süre Dolum Dakikası

Success ve Error URL'lerine dönen değerler

Parametre Adı Tipi Açıklaması
data String Non-secure servisindeki "RESPONSE PARAMETRELERI" başlığı altında bulunan değerler Base64 Encoded olarak gönderilir
random String API tarafından HASH için üretilmiş rastgele değerdir
hash String Verinin doğruluğunun sağlanması için oluşturulan hash değeridir. Kesinlikle teyit edilmesi tavsiye edilir. Oluşturulma şekli(data+random+APIKEY)

Ön Otorizasyon(Provizyon) Onaylama


    curl --request POST \
    --url https://api.imzapos.com/api/v1/payment/post-auth \
    --header 'Authorization: basic MTY6YXBpdGVzdDpGeDlAKkRLP3JidVtfdzQv' \
    --header 'Content-Type: application/json' \
    --header 'x-hash: xRFAliek2iiKh2U7GuJO0zqnMkbTEgkQ0WnBuajwRlQ=' \
    --header 'x-random: 5771f471-ac6e-4543-8c56-28ee575a08c6' \
    --data '{"oid":"bbde07f9-637e-410c-8c97-ae9b84c14970","reseller_id":19,"reference_transaction_id":"4a0f2571-f4d0-4735-840c-788d9d9cdd73","amount":0}'

        
            Başarılı Response Örneği:
            {
            "status": true,
            "statusCode": 100
            }


            Başarısız Response Örneği:
            {
            "status": false,
            "statusCode": 1056,
            "errors": [
            "Satış işlemlerinde provizyon kapama yapılamaz"
            ]
            }
        

PreAuth ile yapılan ön otorizasyon işlemlerinin 25 gün içerisinde kapatılması gerekmektedir. Aksi takdirde karttaki bloke kaldırılır.

Provizyon kapama işlemleri ödeme sağlayıcınıza bağlı olarak parçalı olarak yapılabilmektedir. Ör: 300 TL'lik bir Provizyonun önce 100 TL'lik bir kısmını daha sonra 200 TL'lik bir kısmını onaylayabilirsiniz.

Request Parametreleri

Parametre Adı Tipi Zorunlu Açıklaması
oid String *(resellerId ve reference_transaction_id gönderilmezse) Sistem tarafından verilen ödeme işlem numarası
reseller_id Integer *(oid gönderilmezse) Bayi Kodu
reference_transaction_id String *(oid gönderilmezse) Üye işyeri tarafından belirlenen unique işlem numarası
amount Decimal * Provizyonun onaylanan tutarı. Eğer tamamının onaylanmasını istiyorsanız 0 gönderiniz.

Response Parametreleri

Parametre Adı Tipi Açıklaması
status Bool İşlem durumu. Başarılı ise true, başarısız ise false
statusCode Integer Durum Kodu. Durum Kodu Listesi içerisinden detaylarını öğrenebilirsiniz
errors String Array Hata açıklaması

Ödeme İade


    curl --request POST \
    --url https://api.imzapos.com/api/v1/payment/refund \
    --header 'Authorization: basic MTY6YXBpdGVzdDpGeDlAKkRLP3JidVtfdzQv' \
    --header 'Content-Type: application/json' \
    --header 'x-hash: ZmvDxQztMCahRButcEsMxMKPgP92WPSX0QdOszqMvMM=' \
    --header 'x-random: ab53e87c-57d3-4daa-8f19-34bc4766a81f' \
    --data '{"oid":"bbde07f9-637e-410c-8c97-ae9b84c14970","reseller_id":19,"reference_transaction_id":"4a0f2571-f4d0-4735-840c-788d9d9cdd73","amount":10}'

        
            Başarılı Response Örneği:
            {
            "status": true,
            "statusCode": 100
            }


            Başarısız Response Örneği:
            {
            "status": false,
            "statusCode": 202,
            "errors": [
            "Hatalı işlem numarası"
            ]
            }
        

Request Parametreleri

Parametre Adı Tipi Zorunlu Açıklaması
oid String *(resellerId ve reference_transaction_id gönderilmezse) Sistem tarafından verilen ödeme işlem numarası
reseller_id Integer *(oid gönderilmezse) Bayi Kodu
reference_transaction_id String *(oid gönderilmezse) Üye işyeri tarafından belirlenen unique işlem numarası
amount Decimal * İade tutarı. 0 değeri kabul edilmemektedir.

Response Parametreleri

Parametre Adı Tipi Açıklaması
status Bool İşlem durumu. Başarılı ise true, başarısız ise false
statusCode Integer Durum Kodu. Durum Kodu Listesi içerisinden detaylarını öğrenebilirsiniz
errors String Array Hata açıklaması

Durum Kodları

status_code status_description
0 Tamamlanmamış işlem. Herhangi bir işlemde bulunmayın.
100 İşlem başarılı
101 Provizyon gerçekleştirildi
201 Bu satış işlemi için uygun pos bulunamadı
202 Hatalı işlem numarası
203 Hatalı kullanıcı adı ya da şifre
204 Kullanıcı aktif değil
205 Kullanıcı blokeli
206 Reference_transaction_id zaten kullanılmış
207 Girmiş olduğunuz döviz türü terminal için tanımlı değil
208 İşlem tutarı çok düşük
401 Şifre ve Şifre tekrar değerleri aynı değil
402 Kullanıcı adı zaten mevcut
403 Kullanıcı bulunamadı
404 Bayi bulunamadı
406 Hatalı URL
407 Ödeme sağlayıcı bulunamadı
408 Domain tanınmıyor
409 Providerdan sağlıklı cevap alınamıyor
410 Ödeme sağlayıcı tarafındaki bilgileriniz hatalı
411 Komisyon tanımlamaları yapılmadı
412 Bu taksit için komisyon tanımlaması mevcut değil
413 Günlük işlem sayısı limiti aşıldı
414 Günlük işlem tutarı limiti aşıldı
415 Aylık işlem sayısı limiti aşıldı
416 Aylık işlem tutarı limiti aşıldı
417 Şifre yeterince komplex değil.(Küçük Harf, Büyük Harf, Rakam ve Özel Harakter içermelidir. Min 6 Karakter olmalıdır)
418 Model not valid
419 x-hash parametresi doğru değil
500 Sistem hatası
1001 Bilinmeyen Hata. Hata Detayına Bakınız
1002 Ödemeniz banka tarafından onaylanmadı. Lütfen bankanızla görüşün.
1003 Kartınız internet alışverişine kapalı. Bankanız ile görüşebilirsiniz.
1004 Kısıtlı Kart
1005 Karta el koyun
1006 Kart numarası tanınamadı
1007 Kart sahibine kapalı işlem. Lütfen başka bir kart ile deneyin
1008 Kart limiti bu işlem için yetersiz
1009 Son kullanma tarihi hatalı
1010 Kayıp kart. Karta el koyun
1011 Kart engellenmiş
1012 Önceden onaylanan işlem
1013 Bağlantı hatası. Lütfen tekrar deneyiniz
1014 Geçersiz işlem
1015 3D doğrulama başarısız. CAVV Error
1016 3D doğrılama üye işyeri tarafından sağlanamadı. ECI Error
1017 CV2 yanlış girme sayısı aşıldı
1018 CV2 uzunluğu hatalı
1019 Çalıntı kart. Karta el koyunuz
1020 CV2 hatalı
1021 Terminalin bu işlem için yetkisi yok
1022 İade tutarı, kalan işlem tutarından büyük olamaz
1023 Debit kartlarda iade yapılamaz
1024 Ödül puanı yetersiz
1025 AMEX kart hatası
1026 Kart numarası hatalı
1027 Kart bankası bulunamadı
1028 3DS zorunlu işlem
1029 Debit kartlar ile taksit yapılamaz
1030 İstek zaman aşımına uğradı
1031 Ödeme alınamadı
1032 Yurtdışı kartlar ile işlem yapamazsınız
1033 Terminalin taksit yetkisi bulunmuyor
1034 Para çekme limit aşımı
1035 PIN giriş sayısı aşıldı
1036 Geçersiz PIN
1037 Son kullanma tarihi geçersiz
1038 Ödeme kullanıcı tarafından iptal edildi
1039 Ödeme işlemi sırasında hata oluştu. Lütfen tekrar deneyin.
1040 Dolandırıcılık Şüphesi
1041 Kart işlemine izin verilmedi
1042 Eposta geçerli formatta değil
1043 İşlem için bankanızdan onay alınız
1044 Terminal kategori kodu hatalı
1045 İşlem öncesinde günsonu yapınız
1046 Banka ya da terminal işlem yapamıyor
1047 Banka işlemi engelledi
1048 Satış tutarı ödül puanından düşük olamaz
1049 Geçersiz tutar
1050 Geçersiz kart tipi
1051 İade Başarısız. Hata detayına bakınız
1052 Güvenlik anahtarı hatalı
1053 İade işlemi manuel olarak yapılacak. Pos sağlayıcıya bilgi verildi
1054 Parçalı iade işlemi pos sağlayıcı tarafından desteklenmiyor
1055 Provizyon süresi doldu. İşlem yapılamaz
1056 Satış işlemlerinde provizyon kapama yapılamaz
1058 Ürün fiyatları ile işlem tutarı aynı değil
1059 Genel Hata. Pos sağlayıcı hata detayı vermemektedir. Hata açıklamasına bakınız
1060 Submerchant bulunamadı
1061 İşlem kısmen başarılı
1062 Pos sağlayıcı işlem numarasını tanımıyor
1063 Provizyon kapama/iptal tutarı, kalan işlem tutarından büyük olamaz
1064 Parçalı Provizyon Kapama işlemi pos sağlayıcı tarafından desteklenmiyor
1065 İşlem gerçekleşmesi için alt işlem bilgisi gönderilmeli(sub_transaction_id)