Geri Bildirim (Webhooks)

Ödeal, POS cihazında gerçekleşen bir işlemin sonucunu (başarılı ödeme, iptal, başarısız ödeme, fatura oluşması vb.) sizin belirlediğiniz adrese sunucudan sunucuya POST isteği ile bildirir. Bu sayede ödemenin sonucunu cihazdan beklemeden kendi sisteminizde güncelleyebilirsiniz.

INFO

Geri bildirimler isteğe bağlıdır. Yalnızca adresini tanımladığınız bildirimler gönderilir; hiçbir adres tanımlamazsanız bildirim gönderilmez.

Bildirim Türleri

Bildirim	Ne zaman gönderilir?	Adres alanı (Konfigürasyon)	Detay
Ödeme Bilgisi	Ödeme başarıyla tamamlandığında	`paymentSucceededUrl`	Ödeme Bilgisi
İptal Bilgisi	Başarılı bir ödeme iptal edildiğinde	`paymentCancelledUrl`	İptal Bilgisi
Başarısız Ödeme Bilgisi	Ödeme alınamadığında (ör. banka reddi)	`paymentFailedUrl`	Başarısız Ödeme Bilgisi
E-Fatura Oluştu Bilgisi	Başarılı ödeme sonrası e-Arşiv / e-Fatura entegratöre iletildiğinde	`eInvoiceCreatedUrl`	E-Fatura Oluştu Bilgisi
E-Fatura İptal Bilgisi	Ödeme iptaline bağlı olarak fatura iptal edildiğinde	`einvoiceCancelledUrl` *	E-Fatura İptal Bilgisi
Sepet İptal Bilgisi	Cihaza gönderilen ama ödemesi alınmamış sepet iptal edildiğinde	`basketCancelledUrl` *	Sepet İptal Bilgisi

Ödeme Bilgisi, İptal Bilgisi, Başarısız Ödeme Bilgisi ve E-Fatura Oluştu Bilgisi adresleri Konfigürasyon servisi ile tanımlanır. Tanımlı adresleri Konfigürasyonu Getir servisi ile kontrol edebilirsiniz.

* Bu adreslerin tanımlanması için Ödeal entegrasyon ekibiyle iletişime geçin.

Bildirimi Karşılamak

Adres gereksinimleri

Adres internetten erişilebilir ve HTTPS olmalıdır.
Ödeal, adrese POST metoduyla, gövdesi JSON olan bir istek gönderir.
Adreste sorgu parametresi (?event=... gibi) kullanmayın; bildirim türünü ayırt etmek için her bildirim için ayrı bir yol (path) tanımlayın. Örneğin:
- https://api.ornek.com/odeal/payment-succeeded
- https://api.ornek.com/odeal/payment-cancelled

Gönderilen header'lar

Header	Değer
`Content-Type`	`application/json`
`Accept`	`application/json`
`X-ODEAL-REQUEST-KEY`	Konfigürasyonda tanımladığınız `odealRequestKey` değeri

Güvenlik

İsteğin Ödeal'den geldiğini doğrulamak için X-ODEAL-REQUEST-KEY header'ını kontrol edin ve değer konfigürasyondaki odealRequestKey ile eşleşmiyorsa isteği reddedin. Bu anahtarı kimseyle paylaşmayın.

Anahtar yerine Basic Authentication (Authorization: Basic ...) kullanmak isterseniz Ödeal entegrasyon ekibiyle iletişime geçin.

Yanıt ve tekrar gönderim

Bildirimi aldığınızda 2xx (ör. 200 OK) HTTP durum kodu ile yanıt verin. Yanıt gövdesi dikkate alınmaz.
2xx dışındaki yanıtlar (ör. 401, 404, 500) ve bağlantı hataları Ödeal tarafında başarısız bildirim olarak kaydedilir.
İsteği hızlıca yanıtlayın; ağır işlemleri (stok güncelleme, muhasebe kaydı vb.) yanıt döndükten sonra arka planda yapın.
Başarısız bildirimlerin otomatik olarak tekrar gönderilmesi garanti edilmez. Kaçırılan bildirimler için İşlem Rapor servisi ile işlemleri sorgulayıp kendi kayıtlarınızla eşleştirin.
Aynı bildirim birden fazla kez gelebilir. Kayıtlarınızı PaymentRefCode (ödeme bildirimleri) veya BasketRefCode (fatura ve sepet bildirimleri) ile eşleştirerek aynı işlemi iki kez işlemeyin.

Alan adları

Bildirim gövdelerindeki alan adları büyük harfle başlar (PaymentRefCode, BasketDetail vb.). Tek istisna, satıcının vergi numarasını taşıyan küçük harfli vkn alanıdır. Değeri olmayan alanlar gövdeden çıkarılmaz, null olarak gönderilir.

Ödeme Bildirimleri

Ödeme Bilgisi, İptal Bilgisi ve Başarısız Ödeme Bilgisi aynı gövde yapısını kullanır. Bildirim türüne göre bazı alanlar dolu, bazıları null gelir.

Ödeme Bilgisi (Başarılı Ödeme)

json

{
  "PaymentRefCode": "1000000001",
  "CustomerRefCode": null,
  "MerchantRefCode": "1700000000001",
  "PaymentDetail": {
    "Amount": 60.0,
    "Installment": 1,
    "SignedDate": "2026-10-07",
    "CancelledDate": null,
    "BatchId": "12",
    "StanNumber": "1234",
    "ReferenceNumber": "600000000001",
    "BankCode": null,
    "AuthCode": "123456",
    "FailReason": null,
    "PaymentMethod": "Kredi Kartı / Banka Kartı",
    "CardNumber": "400000******0000"
  },
  "BasketDetail": {
    "BasketRefCode": "11111111-2222-4333-8444-000000000001",
    "CustomInfo": null,
    "NetPrice": 54.55,
    "GrossPrice": 60.0,
    "VatPrice": 5.45,
    "Vat": 0,
    "BasketItems": [
      {
        "ItemRefCode": "11111111-2222-4333-8444-000000000101",
        "Quantity": 1.0,
        "NetPrice": 54.545455,
        "GrossPrice": 60.0,
        "Vat": 10,
        "VatPrice": 5.454545
      }
    ],
    "ExternalDeviceKey": null
  },
  "TerminalDetail": {
    "SerialNo": "PAX000000001",
    "Service": "SADEPOS507"
  },
  "ReceiptNumber": "10",
  "ReceiptDate": "2026-10-07 14:15:32",
  "vkn": "1234567890"
}

İptal Bilgisi

Başarılı bir ödeme iptal edildiğinde gönderilir. PaymentRefCode, iptal edilen ödemenin Ödeme Bilgisi bildirimindeki değeriyle aynıdır; iptali bu değer üzerinden eşleştirin.

json

{
  "PaymentRefCode": "1000000001",
  "CustomerRefCode": null,
  "MerchantRefCode": null,
  "PaymentDetail": {
    "Amount": 60.0,
    "Installment": 1,
    "SignedDate": "2026-10-07",
    "CancelledDate": "2026-10-07 15:02:41",
    "BatchId": "12",
    "StanNumber": "1234",
    "ReferenceNumber": "600000000001",
    "BankCode": null,
    "AuthCode": "123456",
    "FailReason": null,
    "PaymentMethod": null,
    "CardNumber": null
  },
  "BasketDetail": {
    "BasketRefCode": "11111111-2222-4333-8444-000000000001",
    "CustomInfo": null,
    "NetPrice": 54.55,
    "GrossPrice": 60.0,
    "VatPrice": 5.45,
    "Vat": 0,
    "BasketItems": [
      {
        "ItemRefCode": "11111111-2222-4333-8444-000000000101",
        "Quantity": 1.0,
        "NetPrice": 54.545455,
        "GrossPrice": 60.0,
        "Vat": 10,
        "VatPrice": 5.454545
      }
    ],
    "ExternalDeviceKey": null
  },
  "TerminalDetail": null,
  "ReceiptNumber": null,
  "ReceiptDate": null,
  "vkn": "1234567890"
}

Başarısız Ödeme Bilgisi

Ödeme alınamadığında gönderilir. Başarısızlık nedeni PaymentDetail.FailReason alanındadır. Bu bildirim için sepet tutarı tahsil edilmemiştir; sepeti yeniden ödemeye gönderebilirsiniz.

json

{
  "PaymentRefCode": "1000000002",
  "CustomerRefCode": null,
  "MerchantRefCode": null,
  "PaymentDetail": {
    "Amount": 460.0,
    "Installment": 1,
    "SignedDate": "2026-10-07",
    "CancelledDate": null,
    "BatchId": "12",
    "StanNumber": "1235",
    "ReferenceNumber": null,
    "BankCode": null,
    "AuthCode": null,
    "FailReason": "Yetersiz bakiye",
    "PaymentMethod": null,
    "CardNumber": null
  },
  "BasketDetail": {
    "BasketRefCode": "11111111-2222-4333-8444-000000000002",
    "CustomInfo": null,
    "NetPrice": 383.33,
    "GrossPrice": 460.0,
    "VatPrice": 76.67,
    "Vat": 0,
    "BasketItems": [
      {
        "ItemRefCode": "11111111-2222-4333-8444-000000000102",
        "Quantity": 1.0,
        "NetPrice": 383.333333,
        "GrossPrice": 460.0,
        "Vat": 20,
        "VatPrice": 76.666667
      }
    ],
    "ExternalDeviceKey": null
  },
  "TerminalDetail": null,
  "ReceiptNumber": null,
  "ReceiptDate": null,
  "vkn": "1234567890"
}

Ödeme bildirimi alanları

Alan	Tip	Bildirim	Açıklama
`PaymentRefCode`	string	Tümü	Ödemenin Ödeal tarafındaki benzersiz numarası. İptal bildirimi aynı değerle gelir.
`CustomerRefCode`	string / null	Tümü	Sepette müşteri için gönderdiğiniz harici müşteri kodu
`MerchantRefCode`	string / null	Ödeme Bilgisi	Üye işyerinin Ödeal referans kodu
`PaymentDetail.Amount`	number	Tümü	İşlem tutarı (TL)
`PaymentDetail.Installment`	number	Tümü	Taksit sayısı (tek çekim için `1`)
`PaymentDetail.SignedDate`	string	Tümü	İşlem tarihi, `yyyy-MM-dd`
`PaymentDetail.CancelledDate`	string / null	İptal Bilgisi	İptal tarihi
`PaymentDetail.BatchId`	string / null	Tümü	Cihazın gün sonu (batch) numarası
`PaymentDetail.StanNumber`	string / null	Tümü	İşlemin STAN numarası
`PaymentDetail.ReferenceNumber`	string / null	Tümü	Banka referans numarası
`PaymentDetail.AuthCode`	string / null	Ödeme Bilgisi, İptal Bilgisi	Banka provizyon (onay) kodu
`PaymentDetail.FailReason`	string / null	Başarısız Ödeme Bilgisi	Ödemenin başarısız olma nedeni
`PaymentDetail.PaymentMethod`	string / null	Ödeme Bilgisi	Ödeme yöntemi (ör. `Kredi Kartı / Banka Kartı`, `Nakit`)
`PaymentDetail.CardNumber`	string / null	Ödeme Bilgisi	Maskelenmiş kart numarası; kartsız ödemelerde `null`
`BasketDetail`	object / null	Tümü	Ödemeye ait sepet; sepetsiz işlemlerde `null`
`BasketDetail.BasketRefCode`	string	Tümü	Sepeti oluştururken gönderdiğiniz sepet referans kodu
`BasketDetail.CustomInfo`	string / null	Tümü	Sepette gönderdiğiniz özel bilgi, olduğu gibi geri iletilir
`BasketDetail.NetPrice` / `GrossPrice` / `VatPrice`	number	Tümü	Sepetin KDV hariç tutarı / KDV dahil tutarı / KDV tutarı
`BasketDetail.BasketItems[].ItemRefCode`	string	Tümü	Ürün için gönderdiğiniz referans kodu
`BasketDetail.BasketItems[].Quantity`	number	Tümü	Miktar
`BasketDetail.BasketItems[].NetPrice` / `GrossPrice` / `VatPrice`	number	Tümü	Ürünün birim KDV hariç fiyatı / birim KDV dahil fiyatı / birim KDV tutarı
`BasketDetail.BasketItems[].Vat`	number	Tümü	Ürünün KDV oranı (%)
`TerminalDetail.SerialNo`	string	Ödeme Bilgisi	İşlemin yapıldığı cihazın mali seri numarası
`TerminalDetail.Service`	string	Ödeme Bilgisi	Cihazın hizmet tipi
`ReceiptNumber`	string / null	Ödeme Bilgisi	Mali belge (fiş/fatura) numarası
`ReceiptDate`	string / null	Ödeme Bilgisi	Mali belge tarihi, `yyyy-MM-dd HH:mm:ss` (Türkiye saati)
`vkn`	string	Tümü	Satıcının (üye işyeri) VKN / TCKN bilgisi

Fatura Bildirimleri

E-Fatura Oluştu Bilgisi

Başarılı ödemenin faturası e-Arşiv / e-Fatura entegratörüne iletildiğinde gönderilir. Faturanın PDF adresi EInvoiceDetail.PdfUrl alanındadır.

json

{
  "BasketRefCode": "11111111-2222-4333-8444-000000000003",
  "CustomInfo": null,
  "BasketDetails": {
    "Id": 100000001,
    "ReferenceCode": "11111111-2222-4333-8444-000000000003",
    "OrderId": 0,
    "OrganisationId": 300000001,
    "EmployeeId": 10001,
    "CustomerId": 20001,
    "Customer": {
      "Id": 20001,
      "Type": 0,
      "Title": null,
      "ExternalCustomerId": "MUSTERI-001",
      "FirstName": "Ahmet",
      "LastName": "Yılmaz",
      "Phone": "5555555555",
      "TckNo": "11111111111",
      "TaxNumber": null,
      "TaxOffice": null,
      "OrganisationId": 300000001,
      "Email": "[email protected]",
      "City": "İstanbul",
      "Town": "Kadıköy",
      "Address": "Moda Cad. No:5",
      "OdealCustomerId": 30001
    },
    "ReceiptInfo": null,
    "CustomInfo": null,
    "NetPrice": 181.82,
    "GrossPrice": 200.0,
    "VatRatio": null,
    "VatPrice": 18.18,
    "SctRatio": null,
    "SctPrice": 0.0,
    "BasketType": "SIMPLE",
    "BasketItems": [
      {
        "Id": 40001,
        "ExternalProductId": "URUN-001",
        "ProductName": "ÖRNEK ÜRÜN",
        "ProductQuantity": 1.0,
        "Unit": {
          "Id": 4,
          "Code": "C62",
          "Name": "ADET (Unit)",
          "DisplayNameTr": "Adet",
          "DisplayNameEn": "Number of International Units",
          "IsDecimal": false
        },
        "NetPrice": 181.818182,
        "GrossPrice": 200.0,
        "VatRatio": 10,
        "VatPrice": 18.181818,
        "SctRatio": 0,
        "SctPrice": 0.0,
        "Metadata": { "VatExemptionCode": null }
      }
    ],
    "DeviceId": 50001,
    "PaymentOptions": { "TERMINAL": 200.0 },
    "CreatedDate": "2026-10-07 14:38:02",
    "Status": 2
  },
  "EInvoiceDetail": {
    "PdfUrl": "https://portal.odeal.com/invoice?ettn=00000000-0000-4000-8000-000000000001",
    "Type": "EARSIV",
    "Number": "ABC2026000000001",
    "State": "IN_PROGRESS"
  },
  "vkn": "1234567890"
}

E-Fatura İptal Bilgisi

Ödeme iptaline bağlı olarak fatura iptal edildiğinde gönderilir.

json

{
  "BasketRefCode": "11111111-2222-4333-8444-000000000003",
  "CustomInfo": null,
  "EInvoiceDetail": {
    "PdfUrl": "https://portal.odeal.com/invoice?ettn=00000000-0000-4000-8000-000000000001",
    "Type": "EARSIV",
    "Number": "ABC2026000000001",
    "State": "CANCELLED"
  },
  "vkn": "1234567890"
}

Fatura bildirimi alanları

Alan	Tip	Açıklama
`BasketRefCode`	string	Faturanın ait olduğu sepetin referans kodu
`CustomInfo`	string / null	Sepette gönderdiğiniz özel bilgi
`BasketDetails`	object	Faturası kesilen sepetin tüm detayı (yalnızca E-Fatura Oluştu Bilgisi). Alıcı bilgileri `BasketDetails.Customer` altındadır.
`EInvoiceDetail.PdfUrl`	string	Faturanın görüntülenebileceği adres
`EInvoiceDetail.Type`	string	Fatura tipi: `EARSIV` (e-Arşiv) veya `EFATURA` (e-Fatura)
`EInvoiceDetail.Number`	string	Fatura numarası
`EInvoiceDetail.State`	string	Bildirim anındaki fatura durumu (ör. `IN_PROGRESS`, `COMPLETED`)
`vkn`	string	Satıcının (üye işyeri) VKN / TCKN bilgisi

Fatura durumu

E-Fatura Oluştu Bilgisi, fatura entegratöre iletildiği anda gönderilir; bu anda State genellikle IN_PROGRESS olur. Faturanın GİB tarafından işlenmesi ayrıca zaman alabilir; bu durum değişikliği için ayrı bir bildirim gönderilmez.

Sepet İptal Bilgisi

Cihaza gönderilmiş ancak ödemesi alınmamış bir sepet iptal edildiğinde gönderilir. Gövde doğrudan sepet bilgisidir.

json

{
  "BasketRefCode": "ORNEK-11111111-2222-4333-8444-000000000004",
  "CustomInfo": null,
  "NetPrice": 454.55,
  "GrossPrice": 500.0,
  "VatPrice": 45.45,
  "Vat": 0,
  "BasketItems": [
    {
      "ItemRefCode": "URUN-002",
      "Quantity": 1.0,
      "NetPrice": 454.545455,
      "GrossPrice": 500.0,
      "Vat": 10,
      "VatPrice": 45.454545
    }
  ],
  "ExternalDeviceKey": "KASA-1"
}

ExternalDeviceKey, sepeti oluştururken gönderdiğiniz cihaz anahtarıdır; sepetin hangi kasaya/cihaza ait olduğunu ayırt etmek için kullanabilirsiniz.

Uygulamaya Dönüş (A2A Deeplink)

INFO

Bu bölüm sunucu bildirimlerinden farklıdır: APP2APP (A2A) entegrasyonunda ödeme tamamlandığında Ödeal uygulaması, sonucu cihaz üzerinde sizin uygulamanıza deeplink ile iletir. Ayrıntılar için Client Callback (Intent) sayfasına bakın.

Uygulamanızın AndroidManifest.xml dosyasına aşağıdaki intent filter eklenmelidir:

xml

<intent-filter>
    <action android:name="android.intent.action.VIEW"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <data android:scheme="https"/>
    <data android:host="www.domain.com"/>
    <data android:pathPattern="/odeal_gateway"/>
</intent-filter>

Önemli

android:host ve android:pathPattern değerlerini kendi domain ve path bilgilerinizle değiştirmeyi unutmayın.

Intent filter hangi Activity'ye eklendiyse, o Activity'nin onCreate() methodunda aşağıdaki fonksiyon çağırılarak ödeme sonucuna ulaşılabilir:

java

private void getDeeplinkData() {
    Uri intentData = getIntent().getData();

    if (intentData != null) {
        try {
            Log.d("IntentDataTag", "IntentData: " + intentData);

            String basketReferenceCode = intentData.getQueryParameter("basketReferenceCode");
            String reason = intentData.getQueryParameter("reason");
            boolean result = Boolean.parseBoolean(intentData.getQueryParameter("result"));

            Log.d("IntentDataTag", "IntentData: Basket Reference Code: " + basketReferenceCode
                + " Reason: " + reason + " Result: " + result);
        } catch (Exception e) {
            Log.e("IntentDataTag", "IntentData: Exception -> " + e);
        }
    } else {
        Log.d("IntentDataTag", "IntentData: There is no data");
    }
}

Parametre	Tip	Açıklama
`basketReferenceCode`	String	Sepet referans kodu
`reason`	String	İşlem sonucu açıklaması
`result`	Boolean	`true`: ödeme başarılı, `false`: ödeme başarısız veya iptal edildi

Örnek deeplink:

https://www.domain.com/odeal_gateway?basketReferenceCode=ABC123&reason=Ödeme+başarılı&result=true

TIP

Deeplink yalnızca cihazdaki uygulamanızı bilgilendirir. Ödeme sonucunu sunucunuzda kesinleştirmek için yukarıdaki Ödeme Bilgisi bildirimini kullanın.

Geri Bildirim (Webhooks) ​

Bildirim Türleri ​

Bildirimi Karşılamak ​

Adres gereksinimleri ​

Gönderilen header'lar ​

Yanıt ve tekrar gönderim ​

Ödeme Bildirimleri ​

Ödeme Bilgisi (Başarılı Ödeme) ​

İptal Bilgisi ​

Başarısız Ödeme Bilgisi ​

Ödeme bildirimi alanları ​

Fatura Bildirimleri ​

E-Fatura Oluştu Bilgisi ​

E-Fatura İptal Bilgisi ​

Fatura bildirimi alanları ​

Sepet İptal Bilgisi ​

Uygulamaya Dönüş (A2A Deeplink) ​

Geri Bildirim (Webhooks)

Bildirim Türleri

Bildirimi Karşılamak

Adres gereksinimleri

Gönderilen header'lar

Yanıt ve tekrar gönderim

Ödeme Bildirimleri

Ödeme Bilgisi (Başarılı Ödeme)

İptal Bilgisi

Başarısız Ödeme Bilgisi

Ödeme bildirimi alanları

Fatura Bildirimleri

E-Fatura Oluştu Bilgisi

E-Fatura İptal Bilgisi

Fatura bildirimi alanları

Sepet İptal Bilgisi

Uygulamaya Dönüş (A2A Deeplink)