In-Store API V3

iyzico In-Store API V3 — Genel Bakış

iyzico In-Store API V3, fiziksel satış noktalarında (POS) dijital ödeme deneyimi sunmak için tasarlanmış bir REST API'dir. Tüm istekler x-api-key, x-secret-key ve x-merchant-id header'ları ile kimlik doğrulamasından geçer; yanıtlar JSON formatında döner.

---

Entegrasyon Akışı

Kullanıcı Yönetimi

Ödeme akışına dahil edilecek kullanıcıları bu servis grubu üzerinden yönetirsiniz. Yeni bir kullanıcı oluşturabilir, sistemden silebilir ya da mevcut kullanıcıları sayfalanmış şekilde listeleyebilirsiniz. Her kullanıcı, bağlı olduğu banka ve terminal bilgilerini (enrollment) taşır; bu bilgiler ödeme başlatma adımında otomatik olarak kullanılır.

Kullanıcı Ekleme

post

Yeni bir kullanıcı oluşturur ve kullanıcı bilgilerini döner.

Authorizations

ApiKeyAuth & MerchantIdAuth & SecretKeyAuth

x-api-keystringRequired

x-merchant-idstringRequired

x-secret-keystringRequired

Body

application/json

userIdstringRequired

Kullanıcı kimliği

Example: user-123

Responses

200

Kullanıcı başarıyla oluşturuldu

application/json

userIdstringOptional

Sisteme kayıtlı kullanıcının benzersiz kimliği.

Example: user-001

400

Geçersiz parametre veya eksik alan

application/json

401

Geçersiz veya eksik header

application/json

500

Sunucu hatası

application/json

post/user

HTTPcURLJavaScriptPython

POST /v3/in-store/user HTTP/1.1
Host: sandbox-api.iyzipay.com
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_API_KEY
x-secret-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "userId": "user-123"
}

{
  "userId": "user-001",
  "enrollments": [
    {
      "enrolledBank": "AKBANK",
      "enrolledTerminalId": "123123"
    },
    {
      "enrolledBank": "ISBANK",
      "enrolledTerminalId": "456456"
    }
  ]
}

Kullanıcı Listeleme

get

Sistemdeki kullanıcıların sayfalanmış (paginated) listesini döner.

Authorizations

ApiKeyAuth & MerchantIdAuth & SecretKeyAuth

x-api-keystringRequired

x-merchant-idstringRequired

x-secret-keystringRequired

Query parameters

pageNumberintegerOptional

Sayfa numarası

Default: 1Example: 1

pageCountintegerOptional

Sayfa başına kullanıcı sayısı

Default: 100Example: 100

Responses

200

Başarılı — kullanıcı listesi döner

application/json

400

Geçersiz parametre veya eksik alan

application/json

401

Geçersiz veya eksik header

application/json

500

Sunucu hatası

application/json

get/user/list

HTTPcURLJavaScriptPython

GET /v3/in-store/user/list HTTP/1.1
Host: sandbox-api.iyzipay.com
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_API_KEY
x-secret-key: YOUR_API_KEY
Accept: */*

{
  "userList": [
    {
      "userId": "user-001",
      "enrollments": [
        {
          "enrolledBank": "AKBANK",
          "enrolledTerminalId": "123123"
        },
        {
          "enrolledBank": "ISBANK",
          "enrolledTerminalId": "456456"
        }
      ]
    },
    {
      "userId": "user-002",
      "enrollments": [
        {
          "enrolledBank": "AKBANK",
          "enrolledTerminalId": "123123"
        }
      ]
    }
  ]
}

Kullanıcı Silme

delete

Var olan bir kullanıcıyı sistemden siler.

Authorizations

ApiKeyAuth & MerchantIdAuth & SecretKeyAuth

x-api-keystringRequired

x-merchant-idstringRequired

x-secret-keystringRequired

Body

application/json

userIdstringRequired

Silinecek kullanıcı kimliği

Example: user-123

Responses

200

Kullanıcı başarıyla silindi

application/json

userIdstringOptional

Başarıyla silinen kullanıcının kimliği. Silme işleminin doğrulanması amacıyla döner.

Example: user-123

400

Geçersiz parametre veya eksik alan

application/json

401

Geçersiz veya eksik header

application/json

500

Sunucu hatası

application/json

delete/user

HTTPcURLJavaScriptPython

DELETE /v3/in-store/user HTTP/1.1
Host: sandbox-api.iyzipay.com
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_API_KEY
x-secret-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "userId": "user-123"
}

{
  "userId": "user-123"
}

Ödeme Başlatma

Ödeme süreci /payment/init endpoint'i ile başlar. Başarılı bir istek, müşteriyi iyzico mobil uygulamasına yönlendiren bir deepLinkUrl ve sonraki adımda şifre çözmek için kullanılacak bir paymentSessionToken döner. Müşteri uygulamayı açıp ödemeyi onayladıktan sonra sonuç, sizin belirlediğiniz x-callback-url adresine şifreli olarak iletilir.

Ödeme Başlatma

post

Müşterinin ödeme sürecini başlatır. Başarılı yanıt içindeki deepLinkUrl ile müşteri iyzico uygulamasına yönlendirilir.

Entegrasyon Akışı:

1. Bu endpoint ile deepLinkUrl ve paymentSessionToken alınır.

2. Müşteri deepLinkUrl ile yönlendirilir (iyzico uygulaması açılır).

3. Müşteri ödemeyi tamamlar.

4. Callback URL'e şifreli sonuç iletilir.

5. /crypt/decrypt ile şifreli data çözülür.

Authorizations

ApiKeyAuth & MerchantIdAuth & SecretKeyAuth

x-api-keystringRequired

x-merchant-idstringRequired

x-secret-keystringRequired

Header parameters

x-callback-urlstring · uriRequired

İşlem sonucu bildirimi için callback URL

Example: https://yoursite.com/callback

Body

application/json

userIdstringRequired

Ödemeyi yapacak kullanıcı ID'si

Example: usr_12345

orderIdstringRequired

Sipariş referans numarası

Example: ord_98765

amountBigDecimalRequired

Ödeme tutarı

Example: 150.00

Responses

200

Ödeme başarıyla başlatıldı

application/json

statusstringOptional

İşlemin sonucunu gösterir. Başarılı durumlarda "success" döner.

Example: success

errorCodestring · nullableOptional

Hata oluşması durumunda iyzico hata kodunu içerir, aksi hâlde null döner.

errorMessagestring · nullableOptional

Hata oluşması durumunda açıklayıcı mesajı içerir, aksi hâlde null döner.

deepLinkUrlstringOptional

Müşterinin iyzico mobil uygulamasına yönlendirileceği deep link URL'i. Bu link açıldığında uygulama ödeme ekranını başlatır.

Example: iyzico://payment?token=abc123

paymentSessionTokenstringOptional

Ödeme oturumuna özgü token. Ödeme tamamlandıktan sonra /crypt/decrypt adımında şifre çözmek için kullanılır.

Example: abc123xyz

paymentIdinteger · int64Optional

iyzico tarafından atanan benzersiz ödeme kimliği. İade ve sorgulama işlemlerinde referans olarak kullanılır.

Example: 1000001

422

Validasyon hatası — eksik veya hatalı alan

application/json

500

Sunucu hatası

application/json

post/payment/init

HTTPcURLJavaScriptPython

POST /v3/in-store/payment/init HTTP/1.1
Host: sandbox-api.iyzipay.com
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_API_KEY
x-secret-key: YOUR_API_KEY
x-callback-url: https://yoursite.com/callback
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "userId": "usr_12345",
  "orderId": "ord_98765",
  "amount": "150.00"
}

{
  "status": "success",
  "errorCode": null,
  "errorMessage": null,
  "deepLinkUrl": "iyzico://payment?token=abc123",
  "paymentSessionToken": "abc123xyz",
  "paymentId": 1000001
}

Ödeme Sonucu Şifre Çözme

Callback URL'inize gelen şifreli data değeri, /crypt/decrypt endpoint'i aracılığıyla çözülür. İstek gövdesine şifreli veriyi ve ödeme başlatma adımından elde ettiğiniz paymentSessionToken'ı eklemeniz yeterlidir. Yanıt; ödeme durumu, tutar ve sipariş referansını açık metin olarak döner.

Ödeme Sonucu

post

Ödeme tamamlandıktan sonra callback ile gelen şifreli data değerini çözer ve ödeme sonucunu döner.

Authorizations

ApiKeyAuth & MerchantIdAuth & SecretKeyAuth

x-api-keystringRequired

x-merchant-idstringRequired

x-secret-keystringRequired

Body

application/json

datastringRequired

Callback ile gelen şifreli ödeme verisi

Example: U2FsdGVkX1+ENCRYPTED_DATA_HERE==

paymentSessionTokenstringRequired

Ödeme başlatma adımında alınan token

Example: abc123xyz

Responses

200

Şifre başarıyla çözüldü

application/json

statusstringOptional

İşlemin sonucunu gösterir. Başarılı durumlarda "success" döner.

Example: success

systemTimeLongOptional

Sunucu tarafındaki işlem zamanı (Unix epoch, milisaniye).

Example: 1750291200000

422

Validasyon hatası — eksik veya hatalı alan

application/json

500

Sunucu hatası

application/json

post/crypt/decrypt

HTTPcURLJavaScriptPython

POST /v2/in-store/crypt/decrypt HTTP/1.1
Host: sandbox-api.iyzipay.com
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_API_KEY
x-secret-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "data": "U2FsdGVkX1+ENCRYPTED_DATA_HERE==",
  "paymentSessionToken": "abc123xyz"
}

{
  "status": "success",
  "systemTime": 1750291200000,
  "inStoreCompleteOperation": {
    "transaction": {
      "transactionDate": "19 Haziran 2026 10:30",
      "transactionDateISO": "2026-06-19T10:30:00.000+0300",
      "receipt": {
        "detail": [
          {
            "key": "Merchant ID",
            "value": "XYZABC"
          },
          {
            "key": "Terminal ID",
            "value": "ABCXYZ"
          },
          {
            "key": "Merchant Name",
            "value": "kolaybutik"
          },
          {
            "key": "Card Number",
            "value": "******1234"
          },
          {
            "key": "Authorization Code",
            "value": "ABC123"
          },
          {
            "key": "Operation Name",
            "value": "Sale"
          },
          {
            "key": "Status",
            "value": "Approved"
          },
          {
            "key": "Response",
            "value": 0
          },
          {
            "key": "Message",
            "value": "00 Sale Approved"
          },
          {
            "key": "RRN",
            "value": 123456
          },
          {
            "key": "Application Label",
            "value": "Debit Mastercard"
          },
          {
            "key": "AID",
            "value": "A000000"
          }
        ]
      },
      "amount": "150.00",
      "currencyCode": "0949",
      "transactionCode": "Sale",
      "recordId": 987654321,
      "maskedPan": "******1111",
      "authorizationCode": "AUTH01",
      "responseCodeValue": "00",
      "statusCode": "Approved",
      "resultText": "Approved",
      "rrn": "623001234567",
      "screenMessage": "00 Sale Approved",
      "isVoidable": true,
      "isRefundable": true,
      "bankResponseCodeValue": "00",
      "issuerBin": "411111",
      "acquirerId": "0012",
      "clearingDate": "2026-06-20T00:00:00.000+0300",
      "hasDiscount": false,
      "hasInstallment": true
    }
  }
}

İptal ve İade

Tamamlanmış bir ödeme için /payment/refund endpoint'ini kullanabilirsiniz. refundAmount alanını doldurursanız kısmi iade, boş bırakırsanız tam iade gerçekleştirilir. Süreç, ödeme başlatmaya benzer şekilde işler: dönen deepLinkUrl üzerinden müşteri onayı alınır ve sonuç callback URL'inize iletilir.

İptal / İade Başlat

post

Daha önce gerçekleştirilmiş bir ödeme için iptal veya iade işlemi başlatır. refundAmount girilmezse tam iade yapılır.

Authorizations

ApiKeyAuth & MerchantIdAuth & SecretKeyAuth

x-api-keystringRequired

x-merchant-idstringRequired

x-secret-keystringRequired

Header parameters

x-callback-urlstring · uriRequired

İşlem sonucu bildirimi için callback URL

Example: https://yoursite.com/callback

Body

application/json

userIdstringRequired

İşlemi başlatan kullanıcı ID'si

Example: usr_12345

paymentIdLongRequired

İade edilecek ödemenin ID'si

Example: 1000001

refundAmountBigDecimal · nullableOptional

Kısmi iade tutarı; girilmezse tam iade yapılır

Example: 50.00

Responses

200

İade işlemi başarıyla başlatıldı

application/json

statusstringOptional

İşlemin sonucunu gösterir. Başarılı durumlarda "success" döner.

Example: success

errorCodestring · nullableOptional

Hata oluşması durumunda iyzico hata kodunu içerir, aksi hâlde null döner.

errorMessagestring · nullableOptional

Hata oluşması durumunda açıklayıcı mesajı içerir, aksi hâlde null döner.

deepLinkUrlstringOptional

Müşteriyi iade onay ekranına yönlendiren deep link URL'i. İade akışı bu link üzerinden tamamlanır.

Example: iyzico://refund?token=def456

paymentSessionTokenstringOptional

İade oturumuna özgü token. Callback sonrasında şifre çözmek için kullanılır.

Example: def456uvw

paymentIdLongOptional

İade işlemi başlatılan orijinal ödemenin kimliği.

Example: 1000001

422

Validasyon hatası — eksik veya hatalı alan

application/json

500

Sunucu hatası

application/json

post/payment/refund

HTTPcURLJavaScriptPython

POST /v3/in-store/payment/refund HTTP/1.1
Host: sandbox-api.iyzipay.com
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_API_KEY
x-secret-key: YOUR_API_KEY
x-callback-url: https://yoursite.com/callback
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "userId": "usr_12345",
  "paymentId": 1000001,
  "refundAmount": "50.00"
}

{
  "status": "success",
  "errorCode": null,
  "errorMessage": null,
  "deepLinkUrl": "iyzico://refund?token=def456",
  "paymentSessionToken": "def456uvw",
  "paymentId": 1000001
}

Ödeme Sorgulama

/payment/query endpoint'i, daha önce oluşturulmuş bir ödemenin güncel durumunu sorgulamanızı sağlar. Yanıtta ödeme durumu, tutar, sipariş numarası ve kullanıcı bilgisi yer alır. Bu endpoint özellikle callback alınamadığı durumlarda veya ödeme durumunu periyodik olarak doğrulamak istediğinizde kullanılır.

Ödeme Sorgula

get

Belirtilen paymentId ile bir ödemenin güncel durumunu sorgular.

Authorizations

ApiKeyAuth & MerchantIdAuth & SecretKeyAuth

x-api-keystringRequired

x-merchant-idstringRequired

x-secret-keystringRequired

Query parameters

paymentIdLongRequired

Sorgulanacak ödemenin ID'si

Example: 1000001

Responses

200

Ödeme bilgileri başarıyla döndü

application/json

statusstringOptional

İşlemin sonucunu gösterir. Başarılı durumlarda "success" döner.

Example: success

errorCodestring · nullableOptional

Hata oluşması durumunda iyzico hata kodunu içerir, aksi hâlde null döner.

errorMessagestring · nullableOptional

Hata oluşması durumunda açıklayıcı mesajı içerir, aksi hâlde null döner.

errorGroupstring · nullableOptional

Hata grubunu belirten alan. Başarılı işlemlerde null döner.

localestring · nullableOptional

İşlemin gerçekleştiği dil/bölge kodu.

systemTimeLongOptional

Sunucu tarafındaki işlem zamanı (Unix epoch, milisaniye).

Example: 1750329600000

conversationIdstring · nullableOptional

İsteğe bağlı olarak iletilen konuşma/istek takip kimliği.

paymentIdLongOptional

Sorgulanan ödemenin iyzico sistemindeki benzersiz kimliği.

Example: 123456789

orderIdstringOptional

Ödeme oluşturulurken iletilen sipariş referans numarası.

Example: ORD-2026-001

userIdstringOptional

Ödemeyi gerçekleştiren kullanıcının kimliği.

Example: usr_12345

422

Validasyon hatası — eksik veya hatalı alan

application/json

500

Sunucu hatası

application/json

get/payment/query

HTTPcURLJavaScriptPython

GET /v3/in-store/payment/query?paymentId=1000001 HTTP/1.1
Host: sandbox-api.iyzipay.com
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_API_KEY
x-secret-key: YOUR_API_KEY
Accept: */*

{
  "status": "success",
  "errorCode": null,
  "errorMessage": null,
  "errorGroup": null,
  "locale": null,
  "systemTime": 1750329600000,
  "conversationId": null,
  "paymentId": 123456789,
  "orderId": "ORD-2026-001",
  "userId": "usr_12345",
  "transactionDetail": {
    "screenMessage": "İşlem Onaylandı",
    "rrn": "6123001234567",
    "transactionDate": "19/06/2026 11:30:00",
    "amount": "250.00",
    "currencyCode": "TRY",
    "transactionCode": "Sale",
    "maskedPan": "450634******1234",
    "authorizationCode": "123456",
    "statusCode": "00",
    "resultText": "ONAYLANDI",
    "isVoidable": true,
    "isRefundable": false
  }
}