Sayfalama, Filtreler ve Sıralama

Her liste uç noktası (GET /v1/payment_intents, /v1/refunds, /v1/customers, /v1/events vb.) aynı zarfı döndürür ve imleç (cursor) tabanlı sayfalama kullanır.

{
  "object": "list",
  "url": "/v1/payment_intents",
  "has_more": true,
  "total_count": 248,
  "data": [
    {
      "id": "pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5A",
      "object": "payment_intent",
      "amount": 12500,
      "currency": "try",
      "status": "succeeded",
      "capture_method": "automatic",
      "created": 1790000000,
      "livemode": false
    }
  ]
}

İmleçler

Parametre	Anlamı
`limit`	Sayfa boyutu, 1 ile 100 arası, varsayılan 10.
`starting_after`	Önceki sayfanın son nesnesinin id'si; sonraki sayfayı döndürür.
`ending_before`	Geçerli sayfanın ilk nesnesinin id'si; önceki sayfayı döndürür.

Listeler en yeniden eskiye doğru sıralanır. has_more değeri false olana kadar, son öğenin id değerini starting_after olarak geçerek sonraki sayfayı alın:

curl "https://pay.example.com/v1/payment_intents?limit=50&starting_after=pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5A" \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY"

İmleçler nesne id'leridir; bu nedenle yeni nesneler oluşturulurken ve nesne filtrelerinizle artık eşleşmediğinde de geçerli kalır. Başka bir üye işyerine ait bir id, 404 resource_missing sonucunu verir.

Toplamlar

Toplam, ek bir sayım maliyeti getirir; bu yüzden isteğe bağlıdır. include[]=total_count ekleyin; liste total_count alanını taşır (filtrelerinizle eşleşen nesne sayısı). Sayım 10000 ile sınırlıdır: bundan fazlası eşleşirse total_count değeri 10000 olur ve total_count_capped değeri true olur. Diğer her include[] değeri 400 döndürür.

curl -g "https://pay.example.com/v1/refunds?status=succeeded&include[]=total_count" \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY"

Filtreler

Filtreler AND ile birleştirilir. Uç nokta için geçerli olmayan bir filtre veya hatalı biçimli bir değer, param alanında ilgili parametreyi belirten 400 parameter_invalid döndürür. Filtre değerleri asla yanıtta geri yansıtılmaz.

Enum'lar tek bir değer, virgülle ayrılmış bir liste (status=succeeded,canceled) veya tekrarlanan status[]=… kabul eder.
Aralıklar name[gte] ve name[lte] kullanır (belgelenen yerlerde [gt] ve [lt] de). Değerler created için unix saniyesi, tutarlar için en küçük para birimi, tarihler için YYYY-MM-DD biçimindedir. gte değerinin lte değerinden büyük olması hatadır.
Boolean değerler tam olarak true veya false olmalıdır.

Kaynak	Filtreler
Ödemeler	`status`, `amount[gte
İadeler	`payment_intent`, `status`, `method`, `amount[gte
Ödeme aktarımları (payouts)	`status`, `created[gte
Bakiye yüklemeleri (top-ups)	`status`, `created[gte
İtirazlar (disputes)	`status`, `evidence_due_by[gte

Her uç noktanın tam parametreleri API reference içindedir.

Arama

Ödemelerde q ve ödemeler, iadeler, müşteriler ve itirazlar genelinde GET /v1/search?q=…, yalnızca dizinlenen değerlerle eşleşir: bir nesne id'si (pi_, att_, re_, cus_, dp_), tam bir müşteri e-postası (büyük/küçük harf duyarsız) veya bir ödeme açıklamasının başlangıcı. Alt dize araması desteklenmez; ödemeleri kendi referansınızla bulmak için metadata[key]=value kullanın. q içinde bir kart numarası bulunması 400 card_data_in_url ile reddedilir.

Sıralama

Artan sıralama için sort=<key>, azalan sıralama için sort=-<key> ekleyin. Varsayılan -created değeridir. Anahtarlar: created, amount; ayrıca itirazlar için evidence_due_by ve ödeme aktarımları için arrival_date. İmleçler her sıralamada kararlı kalır: sıralama değerleri eşit olan satırlar ne atlanır ne de tekrarlanır.

İlişkili nesneleri genişletme

Bazı alanlar varsayılan olarak bir id içerir. Nesnenin tamamını almak için expand[]=<field> ekleyin; örneğin bir ödemede expand[]=latest_attempt, expand[]=attempts, expand[]=customer veya expand[]=line_items:

curl -g "https://pay.example.com/v1/payment_intents/pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5A?expand[]=customer&expand[]=line_items" \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY"