Skip to content

Feedback (Webhooks) ​

Ödeal notifies the result of a transaction performed on the POS device (successful payment, cancellation, failed payment, invoice creation, etc.) to an address you define, with a server-to-server POST request. This lets you update your own system without waiting for the device.

INFO

Webhooks are optional. Only the notifications whose address you have defined are sent; if no address is defined, no notification is sent.

Notification Types ​

NotificationWhen is it sent?Address field (Configuration)Details
Payment InformationWhen a payment is completed successfullypaymentSucceededUrlPayment Information
Cancellation InformationWhen a successful payment is cancelledpaymentCancelledUrlCancellation Information
Failed Payment InformationWhen a payment cannot be taken (e.g. declined by the bank)paymentFailedUrlFailed Payment Information
E-Invoice Created InformationWhen the e-Archive / e-Invoice of a successful payment is sent to the integratoreInvoiceCreatedUrlE-Invoice Created Information
E-Invoice Cancellation InformationWhen an invoice is cancelled due to a payment cancellationeInvoiceCancelledUrlE-Invoice Cancellation Information
Basket Cancellation InformationWhen a basket sent to the device but not yet paid is cancelledbasketCancelledUrlBasket Cancellation Information

All notification addresses are defined with the Configuration service. You can check the defined addresses with the Get Configuration service.

Receiving a Notification ​

Address requirements ​

  • The address must be reachable from the internet and use HTTPS.
  • Ödeal sends a POST request with a JSON body to the address.
  • Do not use query parameters in the address (such as ?event=...); define a separate path for each notification type instead. For example:
    • https://api.example.com/odeal/payment-succeeded
    • https://api.example.com/odeal/payment-cancelled

Headers sent ​

HeaderValue
Content-Typeapplication/json
Acceptapplication/json
X-ODEAL-REQUEST-KEYThe odealRequestKey value you defined in the configuration

Security

To verify that the request comes from Ödeal, check the X-ODEAL-REQUEST-KEY header and reject the request if the value does not match the odealRequestKey in your configuration. Do not share this key with anyone.

If you would like to use Basic Authentication (Authorization: Basic ...) instead of the key, send the authorizationType field as BASIC in the Configuration service and fill in the basicAuthUsername / basicAuthPassword fields.

Response and redelivery ​

  • When you receive a notification, respond with a 2xx HTTP status code (e.g. 200 OK). The response body is ignored.
  • Responses other than 2xx (e.g. 401, 404, 500) and connection errors are recorded as failed notifications on the Ödeal side.
  • Respond quickly; do heavy work (stock updates, accounting records, etc.) in the background after responding.
  • Automatic redelivery of failed notifications is not guaranteed. For missed notifications, query the transactions with the Transaction Report service and reconcile them with your records.
  • The same notification may arrive more than once. Match your records by PaymentRefCode (payment notifications) or BasketRefCode (invoice and basket notifications) so you do not process the same transaction twice.

Field names

Field names in the notification bodies start with an uppercase letter (PaymentRefCode, BasketDetail, etc.). The only exception is the lowercase vkn field, which carries the seller's tax number. Fields without a value are not omitted; they are sent as null.

Payment Notifications ​

Payment Information, Cancellation Information and Failed Payment Information use the same body structure. Depending on the notification type, some fields are filled and some are null.

Payment Information (Successful Payment) ​

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"
}

Cancellation Information ​

Sent when a successful payment is cancelled. PaymentRefCode is the same as in the Payment Information notification of the cancelled payment; match the cancellation using this value.

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"
}

Failed Payment Information ​

Sent when a payment cannot be taken. The reason is in the PaymentDetail.FailReason field. The basket amount has not been collected; you can send the basket for payment again.

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"
}

Payment notification fields ​

FieldTypeNotificationDescription
PaymentRefCodestringAllUnique number of the payment on the Ödeal side. The cancellation notification arrives with the same value.
CustomerRefCodestring / nullAllThe external customer code you sent for the customer in the basket
MerchantRefCodestring / nullPayment InformationThe merchant's Ödeal reference code
PaymentDetail.AmountnumberAllTransaction amount (TRY)
PaymentDetail.InstallmentnumberAllNumber of installments (1 for a single payment)
PaymentDetail.SignedDatestringAllTransaction date, yyyy-MM-dd
PaymentDetail.CancelledDatestring / nullCancellation InformationCancellation date
PaymentDetail.BatchIdstring / nullAllThe device's end-of-day (batch) number
PaymentDetail.StanNumberstring / nullAllSTAN number of the transaction
PaymentDetail.ReferenceNumberstring / nullAllBank reference number
PaymentDetail.AuthCodestring / nullPayment, CancellationBank authorization (approval) code
PaymentDetail.FailReasonstring / nullFailed Payment InformationReason why the payment failed
PaymentDetail.PaymentMethodstring / nullPayment InformationPayment method (e.g. Kredi Kartı / Banka Kartı, Nakit)
PaymentDetail.CardNumberstring / nullPayment InformationMasked card number; null for non-card payments
BasketDetailobject / nullAllThe basket of the payment; null for transactions without a basket
BasketDetail.BasketRefCodestringAllThe basket reference code you sent when creating the basket
BasketDetail.CustomInfostring / nullAllThe custom information you sent in the basket, returned as is
BasketDetail.NetPrice / GrossPrice / VatPricenumberAllBasket amount excluding VAT / including VAT / VAT amount
BasketDetail.BasketItems[].ItemRefCodestringAllThe reference code you sent for the product
BasketDetail.BasketItems[].QuantitynumberAllQuantity
BasketDetail.BasketItems[].NetPrice / GrossPrice / VatPricenumberAllUnit price excluding VAT / unit price including VAT / unit VAT amount
BasketDetail.BasketItems[].VatnumberAllVAT rate of the product (%)
TerminalDetail.SerialNostringPayment InformationFiscal serial number of the device
TerminalDetail.ServicestringPayment InformationService type of the device
ReceiptNumberstring / nullPayment InformationFiscal document (receipt/invoice) number
ReceiptDatestring / nullPayment InformationFiscal document date, yyyy-MM-dd HH:mm:ss (Turkey time)
vknstringAllTax ID (VKN / TCKN) of the seller (merchant)

Invoice Notifications ​

E-Invoice Created Information ​

Sent when the invoice of a successful payment is forwarded to the e-Archive / e-Invoice integrator. The PDF address of the invoice is in the EInvoiceDetail.PdfUrl field.

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-Invoice Cancellation Information ​

Sent when an invoice is cancelled due to a payment cancellation.

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"
}

Invoice notification fields ​

FieldTypeDescription
BasketRefCodestringReference code of the basket the invoice belongs to
CustomInfostring / nullThe custom information you sent in the basket
BasketDetailsobjectFull detail of the invoiced basket (E-Invoice Created Information only). Buyer information is under BasketDetails.Customer.
EInvoiceDetail.PdfUrlstringAddress where the invoice can be viewed
EInvoiceDetail.TypestringInvoice type: EARSIV (e-Archive) or EFATURA (e-Invoice)
EInvoiceDetail.NumberstringInvoice number
EInvoiceDetail.StatestringInvoice status at the time of the notification (e.g. IN_PROGRESS, COMPLETED)
vknstringTax ID (VKN / TCKN) of the seller (merchant)

Invoice status

The E-Invoice Created Information is sent when the invoice is forwarded to the integrator; at that moment State is usually IN_PROGRESS. Processing by the Revenue Administration (GİB) may take additional time; no separate notification is sent for this status change.

Basket Cancellation Information ​

Sent when a basket that was sent to the device but not paid is cancelled. The body is the basket itself.

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 is the device key you sent when creating the basket; you can use it to tell which cash register/device the basket belongs to.

INFO

This section is different from server notifications: in an APP2APP (A2A) integration, when the payment is completed the Ödeal app passes the result to your app on the device via a deeplink. See the Client Callback (Intent) page for details.

The following intent filter must be added to your application's AndroidManifest.xml file:

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>

Important

Don't forget to replace the android:host and android:pathPattern values with your own domain and path information.

The payment result can be read by calling the following function in the onCreate() method of the Activity the intent filter was added to:

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");
    }
}
ParameterTypeDescription
basketReferenceCodeStringBasket reference code
reasonStringDescription of the transaction result
resultBooleantrue: payment successful, false: payment failed or cancelled

Example deeplink:

https://www.domain.com/odeal_gateway?basketReferenceCode=ABC123&reason=Payment+successful&result=true

TIP

The deeplink only informs your app on the device. Use the Payment Information notification above to confirm the payment result on your server.

Ödeal A.Ş.