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) |