retrieve-payments

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

Ödeme denemelerini döndürür: reddedilen, süresi dolan ve ödeme sayfasından (sipariş, ödeme linki, abonelik) alınan ödemeler dahil. Bir ödemeyi token'ıyla, bir referansla yapılmış bütün denemeleri ya da belli günlerdeki denemeleri sorarsınız; liste eskiden yeniye sıralanır. 3D dönüşünde, webhook geldiğinde ya da yanıtını alamadığınız bir ödemeyi yeniden denemeden önce sonucu buradan öğrenirsiniz.

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": "3b7e1f20-5c4a-4d8e-9f1b-7a6c5d4e3f21" }

{ "reference": "SIP-10233" }

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

Alan	Tip	Zorunlu	Açıklama
`token`	string (UUID)	hayır	Kaydın token'ı. `reference` ya da tarih aralığıyla birlikte gönderilmez.
`reference`	string	hayır	Ödemenin referansı; o referansla yapılmış bütün denemeler döner. 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.

SDK örnekleri

not

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

PHP
Node.js
Python
Java
cURL

use Gurmehub\Odemehub\Request\RetrievePayments;

$payment = $client->retrievePayments(RetrievePayments::byToken($transactionToken))->payments[0] ?? null;

$attempts = $client->retrievePayments(RetrievePayments::byReference('SIP-10231'))->payments;

$list = $client->retrievePayments(RetrievePayments::between('2026-09-26', '2026-10-02'));
$list->successful();   // geçen denemeler

const [payment] = (await client.retrievePayments({ token: transactionToken })).payments;

const attempts = (await client.retrievePayments({ reference: 'SIP-10231' })).payments;

const list = await client.retrievePayments({ createdFrom: '2026-09-26', createdTo: '2026-10-02' });
list.successful();   // geçen denemeler

from odemehub.request import RetrievePayments

payments = client.retrieve_payments(RetrievePayments(token=transaction_token)).payments

attempts = client.retrieve_payments(RetrievePayments(reference="SIP-10231")).payments

listing = client.retrieve_payments(RetrievePayments(created_from="2026-09-26", created_to="2026-10-02"))
listing.successful()   # geçen denemeler

import com.odemehub.request.RetrievePayments;

var payments = client.retrievePayments(RetrievePayments.byToken(transactionToken)).getPayments();

var attempts = client.retrievePayments(RetrievePayments.byReference("SIP-10231")).getPayments();

var list = client.retrievePayments(RetrievePayments.between("2026-09-26", "2026-10-02"));
list.successful();   // geçen denemeler

URI_PATH="/api/$ODEMEHUB_TEAM/gateway/retrieve-payments"
BODY='{"reference":"SIP-10231"}'
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

{
  "result": { "successful": true, "message": null },
  "payments": [
    {
      "token": "0b8f6c2d-3e41-4a7b-9c5d-1e2f3a4b5c6d",
      "reference": "SIP-10231",
      "status": "successful",
      "payment_status": "paid",
      "security_type": "secure",
      "amount": "450.00",
      "base_amount": "450.00",
      "currency": "TRY",
      "installment_number": 1,
      "is_test": false,
      "error_code": null,
      "error_message": null,
      "created_at": "2026-10-02T09:15:30.000000Z",
      "customer": {
        "reference": "musteri-88",
        "billing_address": { "firstname": "Ahmet", "lastname": "Yılmaz", "email": "[email protected]" }
      },
      "conversion": null,
      "order": null,
      "payment_link": null,
      "link_payment": null,
      "subscription": null
    }
  ]
}

Tarih aralığıyla sorulduğunda yanıt ayrıca listenin kapsadığı günleri taşır: "created_from": "2026-09-26", "created_to": "2026-10-02".

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 (`YYYY-MM-DD`, çalışma alanının saat dilimi).
`payments[]`	array	İşlem nesneleri, eskiden yeniye. Eşleşen yoksa boş dizi.

İşlem nesnesi

Bu listede ve retrieve-payment-links yanıtındaki transactions[] dizisinde döner.

Alan	Tip	Açıklama
`token`	string	Ödemenin token'ı.
`reference`	string	Ödemenin referansı: sizin gönderdiğiniz; ödeme sayfasından alındıysa siparişin ya da aboneliğin referansı, ödeme linkinden alındıysa link ödemesinin referansı (`LINKPAY{n}`). Linkin kendi referansıyla sorgu linkin ödemelerini getirmez; onlar için `retrieve-link-payments` kullanılır.
`status`	string	`started`, `redirected_to_secure_page`, `returned_from_secure_page`, `timeout`, `failed`, `expired`, `successful`. `timeout`: sağlayıcı yanıt vermedi, sonuç belirsiz.
`payment_status`	string	`unpaid`, `paid`, `cancelled`, `refunded`, `partially_refunded`.
`security_type`	string	`secure` ya da `regular`.
`amount`, `base_amount`	string	Çekilen ve satılan tutar.
`currency`	string	Para birimi.
`installment_number`	integer	Taksit sayısı.
`is_test`	boolean	Test modunda alındıysa `true`.
`error_code`	string \| null	Sağlayıcının ret kodu.
`error_message`	string \| null	Ret ya da süre dolumu nedeni.
`created_at`	string	ISO 8601 UTC.
`customer`	object	`reference` ve `billing_address` (Ödeme yanıtındaki gibi).
`conversion`	object \| null	Kur çevirisi; yoksa `null`.
`order`	object \| null	Ödeme bir siparişin ödeme sayfasından alındıysa `{ "token" }`.
`payment_link`	object \| null	Ödeme bir ödeme linkinden alındıysa `{ "token" }` (linkin token'ı).
`link_payment`	object \| null	Ödeme bir ödeme linkinden alındıysa `{ "token" }` (link ödemesinin token'ı; `retrieve-link-payments`). `payment_link` ile birlikte dolu gelir.
`subscription`	object \| null	Ödeme bir aboneliğin dönemi içinse `{ "token" }` (aboneliğin token'ı).
`saved_card`	object \| null	Yalnızca ödeme kartın saklanmasını istediyse bulunur: ödeme başarılı ve kart saklandıysa kart nesnesi, değilse `null`.

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 ya da planı API'yi kapsamıyor.
`422`	Doğrulama hatası.
`429`	İstek sınırı aşıldı.

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.`

Kimlik doğrulama​

İstek​

SDK örnekleri​

Yanıt​

İşlem nesnesi​

HTTP durum kodları​

Hatalar​