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
| Notification | When is it sent? | Address field (Configuration) | Details |
|---|---|---|---|
| Payment Information | When a payment is completed successfully | paymentSucceededUrl | Payment Information |
| Cancellation Information | When a successful payment is cancelled | paymentCancelledUrl | Cancellation Information |
| Failed Payment Information | When a payment cannot be taken (e.g. declined by the bank) | paymentFailedUrl | Failed Payment Information |
| E-Invoice Created Information | When the e-Archive / e-Invoice of a successful payment is sent to the integrator | eInvoiceCreatedUrl | E-Invoice Created Information |
| E-Invoice Cancellation Information | When an invoice is cancelled due to a payment cancellation | eInvoiceCancelledUrl | E-Invoice Cancellation Information |
| Basket Cancellation Information | When a basket sent to the device but not yet paid is cancelled | basketCancelledUrl | Basket 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
POSTrequest 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-succeededhttps://api.example.com/odeal/payment-cancelled
Headers sent
| Header | Value |
|---|---|
Content-Type | application/json |
Accept | application/json |
X-ODEAL-REQUEST-KEY | The 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) orBasketRefCode(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)
{
"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.
{
"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.
{
"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
| Field | Type | Notification | Description |
|---|---|---|---|
PaymentRefCode | string | All | Unique number of the payment on the Ödeal side. The cancellation notification arrives with the same value. |
CustomerRefCode | string / null | All | The external customer code you sent for the customer in the basket |
MerchantRefCode | string / null | Payment Information | The merchant's Ödeal reference code |
PaymentDetail.Amount | number | All | Transaction amount (TRY) |
PaymentDetail.Installment | number | All | Number of installments (1 for a single payment) |
PaymentDetail.SignedDate | string | All | Transaction date, yyyy-MM-dd |
PaymentDetail.CancelledDate | string / null | Cancellation Information | Cancellation date |
PaymentDetail.BatchId | string / null | All | The device's end-of-day (batch) number |
PaymentDetail.StanNumber | string / null | All | STAN number of the transaction |
PaymentDetail.ReferenceNumber | string / null | All | Bank reference number |
PaymentDetail.AuthCode | string / null | Payment, Cancellation | Bank authorization (approval) code |
PaymentDetail.FailReason | string / null | Failed Payment Information | Reason why the payment failed |
PaymentDetail.PaymentMethod | string / null | Payment Information | Payment method (e.g. Kredi Kartı / Banka Kartı, Nakit) |
PaymentDetail.CardNumber | string / null | Payment Information | Masked card number; null for non-card payments |
BasketDetail | object / null | All | The basket of the payment; null for transactions without a basket |
BasketDetail.BasketRefCode | string | All | The basket reference code you sent when creating the basket |
BasketDetail.CustomInfo | string / null | All | The custom information you sent in the basket, returned as is |
BasketDetail.NetPrice / GrossPrice / VatPrice | number | All | Basket amount excluding VAT / including VAT / VAT amount |
BasketDetail.BasketItems[].ItemRefCode | string | All | The reference code you sent for the product |
BasketDetail.BasketItems[].Quantity | number | All | Quantity |
BasketDetail.BasketItems[].NetPrice / GrossPrice / VatPrice | number | All | Unit price excluding VAT / unit price including VAT / unit VAT amount |
BasketDetail.BasketItems[].Vat | number | All | VAT rate of the product (%) |
TerminalDetail.SerialNo | string | Payment Information | Fiscal serial number of the device |
TerminalDetail.Service | string | Payment Information | Service type of the device |
ReceiptNumber | string / null | Payment Information | Fiscal document (receipt/invoice) number |
ReceiptDate | string / null | Payment Information | Fiscal document date, yyyy-MM-dd HH:mm:ss (Turkey time) |
vkn | string | All | Tax 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.
{
"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.
{
"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
| Field | Type | Description |
|---|---|---|
BasketRefCode | string | Reference code of the basket the invoice belongs to |
CustomInfo | string / null | The custom information you sent in the basket |
BasketDetails | object | Full detail of the invoiced basket (E-Invoice Created Information only). Buyer information is under BasketDetails.Customer. |
EInvoiceDetail.PdfUrl | string | Address where the invoice can be viewed |
EInvoiceDetail.Type | string | Invoice type: EARSIV (e-Archive) or EFATURA (e-Invoice) |
EInvoiceDetail.Number | string | Invoice number |
EInvoiceDetail.State | string | Invoice status at the time of the notification (e.g. IN_PROGRESS, COMPLETED) |
vkn | string | Tax 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.
{
"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.
Returning to the App (A2A Deeplink)
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:
<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:
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");
}
}| Parameter | Type | Description |
|---|---|---|
basketReferenceCode | String | Basket reference code |
reason | String | Description of the transaction result |
result | Boolean | true: payment successful, false: payment failed or cancelled |
Example deeplink:
https://www.domain.com/odeal_gateway?basketReferenceCode=ABC123&reason=Payment+successful&result=trueTIP
The deeplink only informs your app on the device. Use the Payment Information notification above to confirm the payment result on your server.

