API Başvurusu

Bu sayfada, bir API anahtarının çağırabileceği tüm prosedürler istek alanları ve örnek yanıtlarıyla birlikte yer alır. Temel konuları (anahtarlar, hatalar, yeniden denemeler, limitler) Chargeless API'si: arka ucunuz için kılavuzu açıklar ve akışları adım adım anlatır; bu sayfa ise yalnızca listedir. Buradaki alanlar openapi/backend-api/v1.yaml dosyasından alınmıştır; bu dosya proto'lardan üretilir ve her alanı açıklamasıyla birlikte içerir. Bu sayfa ile o dosya arasında fark varsa dosya esas alınır.

Bir API anahtarıyla yalnızca bu 20 prosedür çağrılabilir. Diğer tüm prosedürler permission_denied döndürür.

Bu Sayfa Nasıl Okunur

Her prosedür, https://api.chargeless.io/{service}/{procedure} adresine JSON gövdesiyle yapılan bir POST isteğidir; istekte anahtarınız ve Content-Type: application/json başlığı bulunur. Örneklerde yalnızca gövde gösterilir:

curl -sS https://api.chargeless.io/sr.cases.v1.CasesService/ListActions \
  -H "Authorization: Bearer $CHARGELESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pageSize": 50}'

• Alan adları lowerCamelCase'tir, enum'lar adlarıyla string olarak yazılır, 64 bitlik tamsayılar (amountMinor, number, sayaçlar) yanıtlarda string'dir, zamanlar UTC cinsinden RFC 3339 biçimindedir. Varsayılan değerdeki (boş, sıfır, false) alanlar yanıtta yer almaz; bu yüzden eksik bir alanı varsayılan değerinde kabul edin.
• Para {"amountMinor": "1999", "currency": "USD"} biçimindedir: para biriminin en küçük birimi cinsinden bir tamsayı ve bir ISO 4217 kodu. Toplamlar para birimi bazında verilir; farklı para birimleri asla birbirine eklenmez.
• Kimlikler (id) opak string'lerdir. API, defterin (ledger) kimliklerini (bir müşteri, bir ödeme, bir abonelik, bir işlem, bir vaka) döndürür ve isteklerde de bunları bekler; sağlayıcı kimlikleri (ch_…, sub_…, cus_…) bunların yanında döndürülür ve yalnızca ilgili alan bunu belirtiyorsa kabul edilir.
• Bazı istek alanları yalnızca Chargeless'ın kendi sohbeti, yardım sitesi ve talep otomasyonu içindir (transcript, ticketId, answeredMessageId, bir talepteki sessionId, address, portalBindingId, includeRetention). Bu alanlardan birini içeren bir API anahtarı isteği invalid_argument ile reddedilir. Bu alanlar aşağıda listelenmemiştir.
• Bazı yanıt alanları yalnızca panel üyelerine gönderilir ve API anahtarıyla yapılan çağrılarda her zaman boş döner: müşterinin e-postası (customerEmail, maskedCustomerEmail, SubscriptionCustomer.email), sağlayıcı paneline bağlantı, bir vakanın notları ve müşteri istatistikleri ile ListSubscriptions'ın plan listesi.

Sayfalama

Listeler pageSize ve pageToken ile sayfalanır: nextPageToken değerini değiştirmeden, aynı filtrelerle pageToken olarak geri gönderin; bu değer boş dönene kadar devam edin. Token opaktır ve yalnızca oluşturulduğu filtrelerle çalışır.

from dahil, to hariçtir. Listeler en yeniden eskiye sıralanır.

Kimlik

Bir müşterinin ödemelerini okumadan veya onun adına işlem yapmadan önce müşterinin kimliğini kanıtlayın. Chargeless her kimlik kanıtını bir müşteri kayıtları kümesine bağlar: bu kümede her ödeme bağlantısı için en fazla bir hesap müşterisi ve bir misafir müşteri bulunur (misafir müşteri, misafir olarak yapılan ödemelerin sahibidir ve ödeme sırasında verilen e-posta adresiyle tanınır). Sonraki çağrılarda kümenin tamamını iletin.

Verify

sr.identity.v1.IdentityService/Verify, sunucunuzun imzaladığı bir kimlik token'ını (Widget İmza Anahtarı ile HS256; claim'ler kılavuzda) doğrular ve token'ın bağlandığı müşteriyi döndürür.

{"token": "eyJhbGciOiJIUzI1NiIs…"}

{
  "customerId": "01a1aff4-5117-79a0-a966-68ed1a264ea1",
  "providerCustomerId": "cus_Q8x…",
  "method": "IDENTITY_METHOD_SIGNED_TOKEN",
  "connectionId": "01a1aff4-50ab-74ce-9c05-b142b747606c",
  "verifiedAt": "2026-11-06T09:30:00Z",
  "expiresAt": "2026-11-06T09:45:00Z"
}

customerId, müşterinin defterdeki kimliğidir: Submit çağrısında identity.customerId olarak, Lookup çağrısında ise customerIds içinde gönderin. Doğrulanamayan ya da süresi dolmuş bir token için unauthenticated, defterde henüz kaydı olmayan bir müşteri için not_found döner.

LookupCustomer

sr.identity.v1.IdentityService/LookupCustomer, bir e-posta adresinin ait olduğu müşterileri bulur: canlı her ödeme bağlantısında, bu adresle kayıtlı tek müşteriyi. Bir bağlantıda aynı adresi birden fazla müşteri paylaşıyorsa o bağlantıda hiçbir müşteri eşleştirilmez.

{"email": "[email protected]"}

{
  "found": true,
  "customerId": "01a1aff4-5117-79a0-a966-68ed1a264ea1",
  "providerCustomerId": "cus_Q8x…",
  "customers": [
    {
      "customerId": "01a1aff4-5117-79a0-a966-68ed1a264ea1",
      "providerCustomerId": "cus_Q8x…",
      "connectionId": "01a1aff4-50ab-74ce-9c05-b142b747606c"
    }
  ]
}

Arama sonucu tek başına kimlik kanıtı değildir: bir adresin kayıtlarınızda kime ait olduğunu gösterir. Bunu kendi sisteminizin doğruladığı adresler için (oturum açmış bir müşteri, onaylanmış bir adres) kullanın; birinin bir forma yazdığı adresler için asla kullanmayın. Bu tür adresler için isteği email ile SubmitCustomerRequest üzerinden gönderin; adresin kendisine ait olduğunu adresin sahibi kanıtlar.

Ödemeler

Lookup

sr.transactions.v1.TransactionsService/Lookup, doğrulanmış bir müşterinin tüm ödeme bağlantılarındaki son ödemelerini (en yeniden eskiye) ve aboneliklerini listeler; her ödeme için iade edilebilir kalanı da verir. İşletmenin barındırdığı bir ödeme sistemi önce okunur; sistem okunamazsa yanıt unavailable olur ve güncel olmayan hiçbir veri döndürülmez.

{"customerIds": ["01a1aff4-5117-79a0-a966-68ed1a264ea1"], "limit": 20}

{
  "transactions": [
    {
      "id": "01a1aff4-53d6-7334-8e2d-9d3d35bfcff5",
      "publicRef": "PAY-7K3F9QS",
      "provider": "stripe",
      "providerTransactionId": "ch_3Q8x…",
      "amount": {"amountMinor": "1900", "currency": "EUR"},
      "refundableRemainder": {"amountMinor": "1900", "currency": "EUR"},
      "state": "succeeded",
      "occurredAt": "2026-11-02T14:05:11Z",
      "cardBrand": "visa",
      "cardLast4": "4242",
      "subscriptionId": "01a1aff4-5500-7a1c-8b2e-0c7d1e2f3a4b",
      "connectionId": "01a1aff4-50ab-74ce-9c05-b142b747606c",
      "connectionLabel": "Stripe"
    }
  ],
  "subscriptions": [
    {
      "id": "01a1aff4-5500-7a1c-8b2e-0c7d1e2f3a4b",
      "publicRef": "SUB-M2XA4TY",
      "provider": "stripe",
      "providerSubscriptionId": "sub_1Q…",
      "state": "active",
      "price": {"amountMinor": "1900", "currency": "EUR"},
      "billingInterval": {"unit": "BILLING_INTERVAL_UNIT_MONTH", "count": 1},
      "currentPeriodEnd": "2026-12-02T14:05:11Z",
      "connectionId": "01a1aff4-50ab-74ce-9c05-b142b747606c",
      "connectionLabel": "Stripe"
    }
  ]
}

Her ödemenin ve aboneliğin kısa bir genel referansı vardır: publicRef ("PAY-" ya da "SUB-" ve ardından yedi karakter; sonuncusu kontrol karakteridir; ADR 0042). Bu referans çalışma alanınızda benzersizdir ve hiçbir zaman değişmez; müşterileriniz ve ekibiniz sohbette, yardım sitesinde, e-postalarda ve panelde bu değeri görür. Müşterinin başvururken bu referansı verebilmesi için makbuzlarınızda ve hesap sayfalarınızda gösterin. Referans yalnızca kaydı işaret eder; birinin kim olduğunu asla kanıtlamaz. API, targetId olarak yine defter kimliklerini alır.

• Bir ödemenin state değeri pending, succeeded, partially_refunded, refunded, disputed veya failed; bir aboneliğinki active, trialing, past_due, canceled, unpaid, incomplete, paused, grace veya expired olur. Bilinmeyen bir değeri belirtilmemiş kabul edin.
• refunded, kimin yaptığından bağımsız olarak gerçekleşmiş tüm iadeleri kapsar. Bir sağlayıcı Chargeless'ın iadelerinden birini sonradan geri aldığında refundReversedAt doldurulur: iade yine hesaba katılır, ancak para müşteride kalmamıştır.
• connectionLabel, ekibinizin belirlediği bir metindir; düz veri olarak gösterin.
• Her ödeme kaydı, siparişi ödeme sağlayıcısının bildirdiği haliyle içerir: lineItems (en fazla ilk 10 satır; toplam satır sayısını lineCount verir), totals (ara toplam, indirim, kargo, vergi ve verginin fiyata dahil olup olmadığı) ve linesState. Boş bir lineItems değerini satır olmadığı şeklinde yorumlamadan önce linesState alanına bakın: LINES_STATE_UNREAD (henüz sorgulanmadı; belirtilmemiş bir durumu da aynı şekilde ele alın), LINES_STATE_COMPLETE, LINES_STATE_TRUNCATED (ödemede 100'den fazla satır var), LINES_STATE_NONE (sağlayıcıda bu ödeme için satır yok) veya LINES_STATE_UNSUPPORTED (sağlayıcı satır bilgisi vermiyor).
• Her satırda şunlar bulunur: bir kind (LINE_ITEM_KIND_ITEM veya LINE_ITEM_KIND_SHIPPING), bir name, productRef ve sku (işletmenin barındırdığı bir sağlayıcıdan gelen satırlarda ikisi de boştur), bir quantity; unitAmount, subtotal (satırın indirimi ve vergisi düşülmeden önce), discount, tax ve total tutarları; ayrıca taxRatePpm (milyonda bir cinsinden: %1 = 10.000), taxName, taxInclusive, periodStart, periodEnd ve proration. Chargeless hiçbir değeri kendisi hesaplamaz: sağlayıcının bildirmediği bir değer yanıtta yer almaz. Tutarlar ödemenin para birimindedir ve negatif olabilir (kıst dönem (proration) alacağı gibi); satırların toplamının ödemenin amount değerine eşit olması gerekmez. Satır adları işletmenin yazdığı metinlerdir; düz veri olarak gösterin. Satırlar yalnızca görüntüleme içindir: iade her zaman ödeme üzerinden bir tutar olarak yapılır.

Politika

Evaluate

sr.policy.v1.PolicyService/Evaluate, önerilen bir iade veya iptal için yayımlanmış politikanın nasıl karar vereceğini, hiçbir şey kaydetmeden önizler. Önizleme bir taahhüt değildir: siz işlemi göndermeden önce kararın dayandığı bilgiler değişebilir ve Submit kararı yeniden verir.

{
  "actionType": "ACTION_TYPE_REFUND",
  "targetId": "01a1aff4-53d6-7334-8e2d-9d3d35bfcff5",
  "reasonCode": "duplicate",
  "source": "SOURCE_CHAT",
  "identityIds": ["01a1aff4-5117-79a0-a966-68ed1a264ea1"],
  "identityMethod": "IDENTITY_METHOD_SIGNED_TOKEN"
}

{
  "decision": {
    "outcome": "OUTCOME_ALLOW",
    "policyVersion": "v7",
    "amount": {"amountMinor": "1900", "currency": "EUR"},
    "reasons": [{"code": "eligible", "text": "…"}],
    "trace": [
      {"name": "kill_switch", "passed": true},
      {"name": "identity", "passed": true, "detail": "signed_token"},
      {"name": "target_state", "passed": true, "detail": "19.00 EUR refundable; requested 19.00 EUR"}
    ]
  }
}

Karar nesnesi, işlemlerde yer alan karar nesnesinin aynısıdır (aşağıda bkz. Karar).

GetPublished

sr.policy.v1.PolicyService/GetPublished yayımlanmış politikayı döndürür. İstek gövdesi {}.

{
  "policyVersion": "v7",
  "publishedAt": "2026-11-01T08:00:00Z",
  "document": "eyJ2ZXJzaW9uIjoxLCJpZGVudGl0eSI6…"
}

document, kanonik politika JSON'unu bayt olarak taşır; bu yüzden base64 ile kodlanmış gelir. Politikayı okumak için base64 kodunu çözün (sözleşmelerdeki policy/v1). Yayımlanmış politikası olmayan bir çalışma alanında yanıt failed_precondition olur.

ListVersions

sr.policy.v1.PolicyService/ListVersions, kayıtlı tüm sürümleri en yeniden eskiye, sayfa başına en fazla 100 sürüm olacak şekilde listeler. Sürümler hiçbir zaman değiştirilmez veya silinmez.

{
  "versions": [
    {
      "policyVersion": "v7",
      "number": 7,
      "published": true,
      "publishedAt": "2026-11-01T08:00:00Z",
      "documentSha256": "e83c1abc4fac148b23fadf553c571b1ce87fa8d84de80fbd5de0c1b935d55464",
      "note": "Lower the auto-refund cap for TRY"
    }
  ],
  "hasMore": true
}

hasMore true ise beforeVersion değerini son number değerine ayarlayıp yeniden isteyin. Yerini yeni bir sürüme bırakan sürümlerde supersededAt, önceki bir sürümü geri yükleyen sürümlerde ise restoredFromVersion alanı bulunur.

GetVersion

sr.policy.v1.PolicyService/GetVersion tek bir sürümü ve belgesini (yukarıdaki gibi base64) döndürür.

{"policyVersion": "v6"}

Yanıt {"version": {…as in ListVersions…}, "document": "…"} biçimindedir; çalışma alanında olmayan bir sürüm için not_found döner.

İşlemler

Submit

sr.actions.v1.ActionsService/Submit, bir işlem hakkında yayımlanmış politikaya göre karar verir, işlemi kaydeder ve ödeme sağlayıcısında yürütmeyi başlatır. Bu çağrının yer aldığı akış kılavuzda anlatılır.

{
  "idempotencyKey": "backend:ord_8812:refund:01a1aff4-53d6-7334-8e2d-9d3d35bfcff5",
  "type": "ACTION_TYPE_REFUND",
  "targetId": "01a1aff4-53d6-7334-8e2d-9d3d35bfcff5",
  "reasonCode": "duplicate",
  "identity": {
    "customerIds": ["01a1aff4-5117-79a0-a966-68ed1a264ea1"],
    "method": "IDENTITY_METHOD_SIGNED_TOKEN"
  },
  "requestedBy": "account-page",
  "waitSeconds": 5
}

{
  "action": {
    "id": "01a1aff5-427d-765f-a005-d2675fe290ab",
    "caseId": "01a1aff5-427b-7a35-b2a4-1f8e6d0c9b11",
    "type": "ACTION_TYPE_REFUND",
    "status": "ACTION_STATUS_EXECUTED",
    "targetId": "01a1aff4-53d6-7334-8e2d-9d3d35bfcff5",
    "customerId": "01a1aff4-5117-79a0-a966-68ed1a264ea1",
    "amount": {"amountMinor": "1900", "currency": "EUR"},
    "reasonCode": "duplicate",
    "decision": {"outcome": "OUTCOME_ALLOW", "policyVersion": "v7", "reasons": [{"code": "eligible", "text": "…"}]},
    "policyVersion": "v7",
    "providerRef": "re_3Q…",
    "source": "SOURCE_CHAT",
    "requestedBy": "account-page",
    "createdAt": "2026-11-06T09:31:02Z",
    "executedAt": "2026-11-06T09:31:03Z"
  },
  "replayed": false
}

API anahtarıyla gönderilen bir işlem source: SOURCE_CHAT ile kaydedilir ve widget'taki bir sohbetle tamamen aynı şekilde karara bağlanır. Devredilen işlem, belirlediğiniz devir hedefine gider: paneldeki ekip kuyruğu, handoff.requested webhook'u ya da her ikisi. Daha önce kullanılmış bir anahtar ilk işlemi replayed: true ile döndürür; aynı anahtar başka bir tür veya hedefle gönderilirse failed_precondition döner. İtiraz işlemlerini yalnızca Chargeless'ın kendisi yapar; bu işlemler invalid_argument ile reddedilir.

Politikanız bir iptalle birlikte son ödemeyi de iade ediyorsa (subscriptions.refund_last_charge_if) ve izin verilen bir iptal bu koşulu sağlıyorsa, yanıtta ayrıca followup yer alır: bu, söz konusu iadenin ayrı işlemidir; aynı veritabanı transaction'ı içinde diğer iadeler gibi karara bağlanır ve kendi durumu vardır (iptal gerçekleşse bile bu iade reddedilebilir veya devredilebilir). İadenin anahtarı, iptal anahtarının sonuna :refund:{transaction_id} eklenerek oluşturulur (44 karakter daha); bu yüzden iptal anahtarlarını 160 karakterin altında tutun: daha uzun bir anahtar, iadenin anahtarını sağlayıcı için fazla uzun hâle getirebilir; bu durumda iade başarısız olur ve ekibinize iletilir. İptal için yapılan Get çağrısı bu iadeyi de döndürür; Submit de iptali beklediği gibi bu iadeyi de bekler.

Get

sr.actions.v1.ActionsService/Get tek bir işlemi, Submit yanıtındaki biçimde ve güncel durumuyla döndürür.

{"actionId": "01a1aff5-427d-765f-a005-d2675fe290ab"}

Yanıt {"action": {…}} biçimindedir.

İşlem

Karar

Formunuzdan Gelen İstekler

SubmitCustomerRequest

sr.tickets.v1.RequestIntakeService/SubmitCustomerRequest, kendi destek formunuzdan gelen tek bir isteği alır, bir talep açar ve kararı politikaya bırakır. Akış kılavuzda anlatılır.

{
  "ticketId": "01a1b00b-2c4e-7f10-9a8b-6d5e4c3b2a19",
  "ticketNumber": "1042",
  "pageUrl": "https://acme.help.chargeless.io/t/9fK2…",
  "outcome": "CUSTOMER_REQUEST_OUTCOME_IDENTITY_REQUIRED",
  "reasonCode": "identity_required",
  "actionId": "01a1b00b-2c51-7d0e-8f3a-5b4c3d2e1f00",
  "replayed": false
}

outcome değeri CUSTOMER_REQUEST_OUTCOME_EXECUTED, _PENDING, _DENIED, _HANDOFF veya _IDENTITY_REQUIRED olur. invalid_argument dışındaki hatalar failed_precondition olarak döner ve ayrıntıda nedeni belirtilir: TARGET_NOT_FOUND, INVALID_IDENTITY_TOKEN, NO_REPLY_ADDRESS (token'daki müşterinin kayıtlı bir adresi yok), TENANT_NOT_LIVE veya KEY_REUSED (aynı requestId farklı içerikle gönderildi).

Çalışma Alanı

GetTenant

sr.tenant.v1.TenantService/GetTenant çalışma alanınızı döndürür. İstek gövdesi {}. Chargeless çalışma alanını askıya almışken de yanıt veren tek çağrı budur.

{
  "tenant": {
    "id": "01a1b700-5c8b-78d0-9ac5-0e50fde96cc5",
    "slug": "acme",
    "name": "Acme Store",
    "status": "TENANT_STATUS_ACTIVE",
    "settlementCurrency": "USD",
    "timeZone": "Europe/Istanbul",
    "activatedAt": "2026-11-07T17:13:36.978820Z",
    "handoffDestination": "HANDOFF_DESTINATION_TEAM_QUEUE_AND_WEBHOOK",
    "widgetOrigins": ["https://shop.acme.example"]
  },
  "helpSite": {"slug": "acme", "url": "https://acme.help.chargeless.io", "chosen": true},
  "customerPortal": {"enabled": true, "url": "https://acme.help.chargeless.io", "codeSignIn": true}
}

• status değeri TENANT_STATUS_ONBOARDING (henüz canlı değil: kalan adımları onboarding listeler), TENANT_STATUS_ACTIVE veya TENANT_STATUS_SUSPENDED olur.
• killSwitch (sizin acil durdurma anahtarınız), operatorHold (Chargeless'ın durdurması) ve circuitBreakerOpen (devre kesici) false iken yanıtta yer almaz. Bunlardan herhangi biri true olduğu sürece hiçbir otomatik iade veya iptal yapılmaz.
• test, test çalışma alanlarında true olur.
• Yanıtta ayrıca asistanın üslubu (assistantStyle), yardım bağlantılarınız ve yardım sitesinin marka ayarları bulunur. tenant.paymentProvider ve tenant.handoff kullanımdan kaldırılmıştır (deprecated): bir çalışma alanının birden fazla ödeme bağlantısı ve webhook uç noktası olabilir.

İşlemler, Vakalar ve Ödemeler

sr.cases.v1.CasesService, çalışma alanınızda olup bitenleri kendi raporlamanız ve mutabakatınız için sunar. Bu prosedürlerin tümü salt okunurdur.

ListActions

Tüm işlemler, en yeniden eskiye.

{"from": "2026-11-01T00:00:00Z", "statuses": ["ACTION_STATUS_HANDOFF"], "pageSize": 50}

Yanıt {"actions": [Action…], "nextPageToken": "…"} biçimindedir.

ListCases

Vakalar (bir sohbet, bir talep, bir dolandırıcılık uyarısı, bir itiraz, bir ekip işlemi, bir portal talebi), en yeniden eskiye; her biri en son kararı ve tutarıyla birlikte.

{
  "cases": [
    {
      "id": "01a1b7d7-cf73-7d19-aead-31ccf144948c",
      "number": "348",
      "type": "CASE_TYPE_TICKET",
      "status": "CASE_STATUS_HANDED_OFF",
      "customerId": "01a1b700-5e57-7515-bc66-6bf4bec0d27d",
      "transactionId": "01a1b700-83f0-7f25-af58-82a8474e203d",
      "ticketId": "01a1b7d6-c2e2-785c-af0d-e6c7a0209674",
      "connectionId": "6e776da5-5c08-8dd5-aa9d-6c9736dfdbea",
      "connectionLabel": "Stripe",
      "openedAt": "2026-11-07T21:08:56.302765Z",
      "closedAt": "2026-11-07T21:08:56.302765Z",
      "summary": {
        "latestDecision": {
          "actionId": "01a1b7d7-cf75-7c0b-b3b9-a9013967a01a",
          "actionType": "ACTION_TYPE_REFUND",
          "actionStatus": "ACTION_STATUS_HANDOFF",
          "outcome": "OUTCOME_HANDOFF",
          "reasonCode": "reason_not_auto_refundable",
          "decidedAt": "2026-11-07T21:08:56.309789Z"
        },
        "amount": {"amountMinor": "1999", "currency": "USD"},
        "amountKind": "CASE_AMOUNT_KIND_REQUESTED"
      }
    }
  ],
  "nextPageToken": "MTc5NDA4NTcz…"
}

number, vakadan söz ederken kullanılan numaradır ("CS-348"). Bağlantıya göre filtrelenen sorguların bir süre sınırı vardır; bu süre aşılırsa yanıt deadline_exceeded olur (filtreyi daraltın veya yeniden deneyin).

GetCase

Tek bir vaka; zaman çizelgesi, işlemleri ve her kararın dayandığı olgularla birlikte.

{"caseId": "01a1b7d7-cf73-7d19-aead-31ccf144948c"}

ListRefunds

Ödemelerinizdeki tüm iadeler, en yeniden eskiye: Chargeless'ın kendi iadeleri (REFUND_ORIGIN_SUPPORTROUTE, işlemleri ve vakalarıyla birlikte) ve başka yerde, yani sağlayıcıda (REFUND_ORIGIN_PROVIDER) veya kendi sisteminizde (REFUND_ORIGIN_MERCHANT_SYSTEM) yapılan iadeler.

{
  "refunds": [
    {
      "id": "01a1b700-69cc-7080-b5ca-e541a95862d7",
      "origin": "REFUND_ORIGIN_SUPPORTROUTE",
      "provider": "stripe",
      "providerRefundId": "re_c58FA64x0aOqOxLK0I9ZjlZb",
      "amount": {"amountMinor": "4200", "currency": "USD"},
      "state": "PAYMENT_REFUND_STATE_SUCCEEDED",
      "refundedAt": "2026-11-07T17:13:40.044033Z",
      "charge": {
        "transactionId": "01a1b700-5ea6-736f-99fe-80e460b95079",
        "providerRef": "ch_8w2pTukEA4IOftQJexOZbddA",
        "amount": {"amountMinor": "4200", "currency": "USD"},
        "cardBrand": "visa",
        "cardLast4": "9772",
        "customerId": "01a1b700-5ea6-707e-bb61-b0763860a280",
        "customerProviderRef": "cus_aQYDQuFGnAjZ6rt25BbC8jvo"
      },
      "actionId": "01a1b700-65e6-7b4d-ae33-d46bf87e283f",
      "caseId": "01a1b700-65e6-76d0-9a8b-1325c5b3c1f2",
      "caseNumber": "5",
      "actionStatus": "ACTION_STATUS_EXECUTED",
      "source": "SOURCE_FRAUD_ALERT",
      "decisionReason": "eligible",
      "connectionId": "6e776da5-5c08-8dd5-aa9d-6c9736dfdbea",
      "connectionLabel": "Stripe"
    }
  ],
  "totals": [
    {"amount": {"amountMinor": "219885", "currency": "EUR"}, "refunds": "36"},
    {"amount": {"amountMinor": "790509", "currency": "USD"}, "refunds": "160"}
  ],
  "nextPageToken": "MTc5NDA3MTYy…"
}

totals, seçilen aralıkta para birimi başına iade edilen toplam tutarı verir (başarılı olmuş ve geri alınmamış iadeler; kaynak ve bağlantı filtreleri uygulanır) ve her sayfada aynıdır. reversedAt, sonradan geri alınan bir iadeyi işaretler.

ListDisputes

İtirazlar ve sorgular, en yeniden eskiye; ilgili ödeme ve Chargeless'ın her biri için yaptıklarıyla birlikte.

Her kayıtta şunlar bulunur: dispute (sağlayıcı, kimlik, durum, tutar, neden, evidenceDueBy, openedAt, closedAt, fundsWithdrawn), charge, vaka, vakadaki en son işlem (actionType: kabul, kanıt gönderme veya devir; ve actionStatus), evidenceState ve handledByProvider. Sonuncusu, itirazı kayıtlı satıcı (merchant of record; Paddle, FastSpring) kendisi yürütüyorsa true olur.

ListFraudWarnings

Erken dolandırıcılık uyarıları (EFW), en yeniden eskiye; ilgili ödeme ve dolandırıcılık uyarısı iş akışının (workflow) her biri için verdiği iade kararıyla birlikte (iş akışı sürerken actionId boştur).

Her kayıtta şunlar bulunur: provider, providerWarningId, fraudType, warnedAt, actionable (ödeme üzerinde hâlâ işlem yapılabiliyorsa), charge, vaka ve karar (actionStatus, decisionReason), fromHistory (sağlayıcının geçmiş kayıtlarından okunmuş ve hiç işlenmemiş) ve handledByProvider.

ListSubscriptions

Ödeme bağlantılarınızdaki abonelikler, seçilen zaman alanına göre en yeniden eskiye.

{
  "subscriptions": [
    {
      "id": "01a1b700-732b-73e9-bdff-36fe4600be3c",
      "provider": "stripe",
      "providerSubscriptionId": "sub_zRD1wEx9r98zQYWAjTRFPDf2",
      "state": "SUBSCRIPTION_STATE_ACTIVE",
      "customer": {"id": "01a1b700-661c-74aa-a45d-8db455c36d2b", "providerRef": "cus_xXbSfStFNII7WdETMI6oe0l6"},
      "planRef": "price_kGmpyErZM0VmStFVzlC6gTqs",
      "price": {"amountMinor": "1500", "currency": "USD"},
      "billingInterval": {"unit": "BILLING_INTERVAL_UNIT_WEEK", "count": 1},
      "startedAt": "2026-11-06T17:13:35Z",
      "currentPeriodEnd": "2026-11-13T17:13:35Z",
      "cancelAtPeriodEnd": true,
      "canceledAt": "2026-11-07T17:13:35Z",
      "connectionId": "6e776da5-5c08-8dd5-aa9d-6c9736dfdbea",
      "connectionLabel": "Stripe"
    }
  ],
  "nextPageToken": "MTc5Mzk4NTIx…"
}

Planın görünen adı (planName ve planName filtresi) yalnızca panelde kullanılabilir.

ListProviderCalls

Chargeless'ın kendi ödeme sisteminize yaptığı çağrılar (işletmenin barındırdığı bir bağlantı; bkz. Kendi faturalama sisteminizi bağlamak), en yeniden eskiye; 90 gün saklanır. İstek ve yanıt gövdeleri ile kişisel veriler yer almaz. Böyle bir bağlantısı olmayan çalışma alanına boş bir sayfa döner.

Her çağrı kaydında şunlar bulunur: at, operation, outcome, outcomeDetail (bir ret kodu ya da yanıtın neyi ihlal ettiği), httpStatus, latencyMs, attempt, requestId (loglarınızda da yer alan X-SR-Request-Id), correlationId ve türü, değişiklik yapan çağrılar için idempotencyKey, ve hata zarfınızdaki (error envelope) bayrak HTTP durum koduyla çeliştiğinde retryableMismatch ile birlikte errorRetryable.

GetProviderHealth

İşletmenin barındırdığı bir bağlantının sağlık durumu, izleme (monitoring) için: açık sağlayıcı uyarıları, son 7 günde çözülenler ve son 24 saatteki çağrıların sonuca göre dağılımı.

Yanıtta openAlerts ve resolvedAlerts (kind: kimlik bilgileri reddedildi, sözleşme ihlali, erişilemiyor, kimlik bilgilerinin süresi doluyor; en fazla üç istek kimliği içeren figures) ile [windowStart, windowEnd) aralığında sonuca göre supportPath, sync ve check sayıları bulunur. Stripe bağlantısı için yanıt {} olur. Yanıt en fazla 30 saniye gecikmeli olabilir ve tüm çağıranlar aynı yanıtı alır; bu yüzden daha sık sorgulamak aynı yanıtı döndürür. resource_exhausted aldığınızda en az bir saniye bekleyin.