retrieve-link-payments

POST /api/{team}/gateway/retrieve-link-payments

Ödeme linklerinden yapılan ödemelerin (link ödemeleri) güncel hâlini döndürür; hiçbir şeyi değiştirmez. Link ödemesi API ile açılmaz: linkin ödeme sayfasından ödeme başlatıldığında açılır, status: open ile başlar ve bir ödeme denemesi başarılı olunca paid olur. Her link ödemesi ödenen kalemleri, tutarları, uygulanan kuponu, ödeyenin fatura adresini ve ödeyen işlemi taşır.

Link ödemesinin token'ı işlem yanıtlarında, retrieve-payment-links yanıtındaki transactions[] öğelerinde ve payment_link.* webhook gövdelerinde link_payment.token alanında gelir.

Kimlik doğrulama

X-Api-Key, X-Timestamp, X-Signature, Content-Type: application/json. Ayrıntılar: Kimlik Doğrulama ve İmza.

İstek

Kayıt üç yoldan biriyle adlandırılır; en fazla biri gönderilir:

{ "token": "5e2a8c4f-7b1d-4a3e-9c6f-0d2b4f6a8c1e" }

{ "reference": "LINKPAY1" }

{ "created_from": "2026-09-26", "created_to": "2026-10-02" }

Alan	Tip	Zorunlu	Açıklama
token	string (UUID)	hayır	Link ödemesinin token'ı. reference ya da tarih aralığıyla birlikte gönderilmez.
reference	string	hayır	Link ödemesinin referansı (LINKPAY1, LINKPAY2 …). Linkin kendi referansı değildir. Tarih aralığıyla birlikte gönderilmez.
created_from	string	hayır	Başlangıç günü, YYYY-MM-DD. created_to ile birlikte gönderilir.
created_to	string	hayır	Bitiş günü, YYYY-MM-DD. created_from ile birlikte gönderilir; ondan önce olamaz. Aralık iki gün dahil en fazla 7 gündür.

Tarihler çalışma alanının saat dilimindedir. Hiçbir alan gönderilmezse ({}) bugün dahil son 7 gün listelenir. Yanıt her zaman bir listedir; eşleşen kayıt yoksa liste boştur. Başka bir çalışma alanının kaydı hiçbir zaman dönmez.

Belirli bir linkin ödemeleri için ayrı bir süzgeç yoktur: tarih aralığıyla sorgulayıp sonuçları payment_link.token alanına göre ayırın ya da retrieve-payment-links yanıtındaki işlemlerin link_payment.token değeriyle sorgulayın.

SDK örnekleri

not

Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.

PHP

use Gurmehub\Odemehub\Request\RetrieveLinkPayments;

$linkPayments = $client->retrieveLinkPayments(RetrieveLinkPayments::byReference('LINKPAY1'))->linkPayments;

foreach ($linkPayments as $linkPayment) {
    $linkPayment->paymentLink->token;    // ödemenin yapıldığı link
    $linkPayment->isPaid();              // status: Enum\LinkPaymentStatus::Paid
    $linkPayment->amount;                // çekilen tutar, kupon düşülmüş
    $linkPayment->discount?->code;       // kupon yoksa null
    $linkPayment->transaction?->token;   // ödeyen işlem; ödenmemişse null
}

Node.js

const { linkPayments } = await client.retrieveLinkPayments({ reference: 'LINKPAY1' });

for (const linkPayment of linkPayments) {
    linkPayment.paymentLink.token;    // ödemenin yapıldığı link
    linkPayment.isPaid();             // status: 'paid'
    linkPayment.amount;               // çekilen tutar, kupon düşülmüş
    linkPayment.discount?.code;       // kupon yoksa null
    linkPayment.transaction?.token;   // ödeyen işlem; ödenmemişse null
}

Python

from odemehub.request import RetrieveLinkPayments

link_payments = client.retrieve_link_payments(RetrieveLinkPayments(reference="LINKPAY1")).link_payments

for link_payment in link_payments:
    link_payment.payment_link.token   # ödemenin yapıldığı link
    link_payment.is_paid()            # status: LinkPaymentStatus.PAID
    link_payment.amount               # çekilen tutar, kupon düşülmüş
    link_payment.discount             # Discount (code, amount); kupon yoksa None
    link_payment.transaction          # ödeyen işlem (token, reference, payment_status); ödenmemişse None

Java

import com.odemehub.request.RetrieveLinkPayments;

var linkPayments = client.retrieveLinkPayments(RetrieveLinkPayments.byReference("LINKPAY1")).getLinkPayments();

for (var linkPayment : linkPayments) {
    linkPayment.getPaymentLinkToken();   // ödemenin yapıldığı link
    linkPayment.isPaid();                // getStatus(): LinkPaymentStatus.PAID
    linkPayment.getAmount();             // çekilen tutar, kupon düşülmüş
    linkPayment.getDiscount();           // Discount (getCode(), getAmount()); kupon yoksa null
    linkPayment.getTransaction();        // ödeyen işlem; ödenmemişse null
}

cURL

URI_PATH="/api/$ODEMEHUB_TEAM/gateway/retrieve-link-payments"
BODY='{"reference":"LINKPAY1"}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "POST" "$URI_PATH" "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')

curl -X POST "https://sandbox.odemehub.com$URI_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ODEMEHUB_API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Yanıt

Ödenmiş bir link ödemesi:

{
  "result": { "successful": true, "message": null },
  "link_payments": [
    {
      "token": "5e2a8c4f-7b1d-4a3e-9c6f-0d2b4f6a8c1e",
      "reference": "LINKPAY1",
      "payment_link": {
        "token": "7c9e1a3b-5d2f-4b6a-8e0c-2a4c6e8b0d1f",
        "reference": "LNK-1"
      },
      "payment_provider_token": null,
      "status": "paid",
      "items": [
        { "reference": null, "name": "Bağış", "quantity": 1, "unit_amount": "100.00", "tax_rate": "0.00" }
      ],
      "subtotal": "100.00",
      "tax_amount": "0.00",
      "amount": "100.00",
      "discount": null,
      "currency": "TRY",
      "customer": {
        "billing_address": { "firstname": "Ayşe", "lastname": "Kaya", "email": "[email protected]" }
      },
      "is_test": false,
      "created_at": "2026-10-02T10:58:00.000000Z",
      "transaction": {
        "token": "1f3a5c7e-9b2d-4f6a-8c0e-3b5d7f9a1c2e",
        "reference": "LINKPAY1",
        "payment_status": "paid"
      }
    }
  ]
}

Alan	Tip	Açıklama
created_from, created_to	string	Yalnızca tarih aralığıyla (ya da boş gövdeyle) sorulduğunda: listenin kapsadığı günler.
link_payments[]	array	Link ödemesi nesneleri, eskiden yeniye.

Link ödemesi nesnesi

Alan	Tip	Açıklama
token	string	Link ödemesinin token'ı.
reference	string	Geçidin ürettiği referans: LINKPAY1, LINKPAY2 … Bu ödemenin işlemleri de aynı reference ile döner.
payment_link	object	Ödemenin yapıldığı link: token, reference.
payment_provider_token	string | null	Ödeme açıldığında linkte belirtilen ödeme hesabı; belirtilmemişse null.
status	string	open (ödenmedi) ya da paid.
items[]	array	Ödenen kalemler: reference, name, quantity, unit_amount (KDV dahil), tax_rate. Ödeme denemesi başlatıldığı andaki hâliyle yazılır; ödendikten sonra linkin değişmesi bu kalemleri etkilemez. Tutarı ödeyenin belirlediği linkte adı linkin item_name değeri olan tek kalemdir.
subtotal	string	KDV hariç toplam. Kupon uygulandıysa indirim düşülmüş.
tax_amount	string	KDV. Kupon uygulandıysa indirim düşülmüş.
amount	string	Karttan çekilen (açıkken çekilecek) tutar. Kupon uygulandıysa indirim düşülmüş.
discount	object | null	Ödeme sayfasında uygulanan kupon: code, amount. Kupon yoksa null. Kupon yalnızca amount_type fixed ya da predefined olan linklerde uygulanır. Bkz. Kupon ve discount.
currency	string	Ödemenin para birimi; linkte para birimi seçimi açıksa ödeyenin seçtiği.
customer	object | null	billing_address: ödeme sayfasında girilen fatura adresi, yalnızca dolu alanlarla. Fatura adresi girilmemişse null.
is_test	boolean | null	Ödenene kadar null; ödenince ödemenin test modunda alınıp alınmadığı.
created_at	string	ISO 8601 UTC.
transaction	object | null	Ödemeyi ödeyen başarılı işlem: token, reference, payment_status (paid, cancelled, refunded, partially_refunded). Ödenmemişse null. Bu token retrieve-payments, refund-payment ve cancel-payment ile kullanılır.

HTTP durum kodları

Kod	Durum
200	Liste döndü; eşleşen kayıt yoksa boş.
401	API anahtarı ya da imza geçersiz.
403	Çalışma alanı işlem yapamıyor, planı ödeme linklerini kapsamıyor ya da Link ile Ödeme modülü kapalı.
422	Doğrulama hatası.
429	İstek sınırı aşıldı.

403 mesajları: Çalışma alanınızın planı bu özelliği kapsamıyor. (plan) / Çalışma alanınızda bu modül kapalı; panelde Modüller sayfasından açılabilir. (modül kapalı).

Hatalar

Alan	Mesaj
token	Token ile birlikte referans ya da tarih aralığı gönderilmez.
reference	Referans ile birlikte tarih aralığı gönderilmez.
created_to	Bitiş tarihi başlangıç tarihinden önce olamaz. / Tarih aralığı en fazla 7 gün olabilir.