Blesyum Core

billing

24 uç · /api/v1/billing

İstek örnekleri ucun GERÇEK metodu ve yolundan üretilir. 24 ucun elle doğrulanmış gövde örneği henüz yok; o uçlarda iskelet gövdesizdir — uydurma bir alan yazmıyoruz.

POST/api/v1/billing/addon

Add an optional module to the subscription (TADM-02) — the license updates

Oturum

immediately; the module is billed on the next renewal invoice (no live charge). Requires `core.settings.manage`.

İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/addon" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
DELETE/api/v1/billing/addon/{module_key}

Remove an optional module from the subscription (TADM-02). Requires

OturumYol parametresi: module_key

`core.settings.manage`.

İstek
curl -X DELETE "https://api.blesyum.com/api/v1/billing/addon/<module_key>" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/auto-renew

Toggle automatic renewal (BILL-19).

Oturum
İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/auto-renew" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/cancel

Schedule cancellation at period end with a retention reason (TADM-06). Access

Oturum

continues until `current_period_end`; the reason is recorded for churn analytics. Requires `core.settings.manage`.

İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/cancel" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/cards/verify/callback

Bankanın 3DS dönüşü — **kimliksiz** bir POST. Sonucu banka değil iyzico söyler:

Oturum

`threeds_complete` otoriterdir (sahte `paymentId` → Failure → kapı açılmaz). Başarıda: kart doğrulanmış damgalanır → 1 ₺ İADE edilir → lisans `pending_payment` durumundan **`pending_review`**'a geçer (ONB-01: hesabı biz onaylıyoruz; abonelik ve modül adresleri onay anında doğar). Sonra tarayıcı panele döndürülür; 3DS bir iframe içinde açılmış olabileceği için üst pencere hedeflenir.

İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/cards/verify/callback" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/cards/verify/start

Kart doğrulamayı başlat. Dönen `threeds_html` tarayıcıda gösterilir; banka 3DS

Oturum

ekranından sonra `callback` ucumuza POST eder. Sıra bilinçli: kart ÖNCE iyzico kasasına konur (token alınır), 1 ₺ çekim token'la yapılır. Böylece PAN hiçbir aşamada bizde tutulmaz — callback ayrı bir istek olduğu için ham kartı saklamak gerekseydi, saklamamak için kurulan bütün düzen çökerdi.

İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/cards/verify/start" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/change-plan

Billing change plan

Oturum
İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/change-plan" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/coupon

Apply a discount coupon to the subscription (BILL-05); the next renewal

Oturum

invoice receives the discount. Requires `core.billing.manage`.

İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/coupon" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
GET/api/v1/billing/invoices

List the active tenant's invoices (BILL-01). Requires billing visibility.

Oturum
İstek
curl -X GET "https://api.blesyum.com/api/v1/billing/invoices" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
GET/api/v1/billing/invoices/{id}

One invoice with its lines.

OturumYol parametresi: id
İstek
curl -X GET "https://api.blesyum.com/api/v1/billing/invoices/<id>" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
GET/api/v1/billing/invoices/{id}/pdf

Download an invoice as a PDF (BILL-04) — requires `core.billing.view`.

OturumYol parametresi: id
İstek
curl -X GET "https://api.blesyum.com/api/v1/billing/invoices/<id>/pdf" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
GET/api/v1/billing/invoices/export

Accounting export of the tenant's invoices as CSV (BILL-16) — amounts in major

Oturum

units. Requires `core.billing.view`.

İstek
curl -X GET "https://api.blesyum.com/api/v1/billing/invoices/export" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/iyzico/webhook

Receive an iyzico payment webhook (BILL-22). Public, but authenticated by an

Oturum

HMAC signature over the raw body. On a success event we settle the matching open invoice (idempotent — a duplicate delivery is a no-op). NOTE: the exact field/header scheme is confirmed against iyzico's webhook spec once live credentials are set; the verification + idempotent settle are stable.

İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/iyzico/webhook" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
GET/api/v1/billing/payment-methods

List saved cards — display fields only (BILL-17).

Oturum
İstek
curl -X GET "https://api.blesyum.com/api/v1/billing/payment-methods" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/payment-methods

Save a card the client already tokenized with iyzico (BILL-08/17). The raw

Oturum

PAN/CVV never reach Blesyum — only the token + display fields arrive here.

İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/payment-methods" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
DELETE/api/v1/billing/payment-methods/{id}

Remove a saved card (BILL-21).

OturumYol parametresi: id
İstek
curl -X DELETE "https://api.blesyum.com/api/v1/billing/payment-methods/<id>" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/payment-methods/{id}/default

Make a saved card the default for auto-charge (BILL-18).

OturumYol parametresi: id
İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/payment-methods/<id>/default" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/payment/3ds/callback

Complete a 3-D Secure payment after the bank's callback (BILL-20). iyzico POSTs

Oturum

`paymentId` + `conversationId`; we finalize and settle the matching invoice.

İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/payment/3ds/callback" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
GET/api/v1/billing/profile

Change the subscription plan; an upgrade mid-period creates a proration

Oturum

invoice for the remaining days (LIC-08/BILL-02). Requires billing management. The tenant's billing profile (BILL-15) — requires `core.billing.view`.

İstek
curl -X GET "https://api.blesyum.com/api/v1/billing/profile" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
PUT/api/v1/billing/profile

Set the tenant's billing profile (BILL-15) — requires `core.billing.manage`.

Oturum
İstek
curl -X PUT "https://api.blesyum.com/api/v1/billing/profile" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/renew

**Aboneliği yenile** (LIFE-02): faturayı kes/bul → kayıtlı karttan çek → aç.

Oturum

Sıra bilinçli ve her adımı geri alınabilir: 1. Durum kapısı (`renewal_block`) — dönemi süren aboneliğe ikinci dönem sattırmaz. 2. Kart yoksa **422 `card_required`** — panel kart formunu açar, kullanıcı kapıda "bir şeyler ters gitti" görmez. 3. Fatura: **önce var olan açık fatura**, yoksa yenisi ([`open_renewal_invoice`]). 4. Sahiplenme: worker'ın `billing.charge` turu aynı faturayı çekmesin. 5. Çekim → başarı: `settle_invoice_paid` (dönem uzar, damgalar TEMİZLENİR, geri sayım durur) → adresler → bildirim → webhook → denetim. 🔴 Başarısız çekim **dunning'i İLERLETMEZ** ([`record_manual_charge_failure`]): kartını düzeltmeye çalışan müşteri üç denemede askıya alınırsa, yenilemeye çalışmak yenilemeyi imkânsız kılardı.

İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/renew" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
GET/api/v1/billing/renewal

Yenileme teklifi (LIFE-02). `core.settings.view` — abonelik özetiyle aynı kapı,

Oturum

yoksa aboneliği görebilen kullanıcı tutarı göremezdi.

İstek
curl -X GET "https://api.blesyum.com/api/v1/billing/renewal" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
POST/api/v1/billing/resume

Undo a scheduled cancellation (TADM-06 "Geri Al"). Requires `core.settings.manage`.

Oturum
İstek
curl -X POST "https://api.blesyum.com/api/v1/billing/resume" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
GET/api/v1/billing/subscription

The active tenant's subscription lifecycle/billing state (TADM-01) — plan,

Oturum

status, cycle, auto-renew, cancel-at-period-end, period bounds, coupon, add-ons. Requires billing visibility; a plain member gets 403 and the panel falls back to the read-only `/entitlements` view. 404 when the workspace has no license.

İstek
curl -X GET "https://api.blesyum.com/api/v1/billing/subscription" \
  -H "Authorization: Bearer <oturum-token>" \
  -H "Accept: application/json"
Yanıt
{
  "data": "…",
  "trace_id": "01JC…"
}
Bu sayfa işine yaradı mı?
Hâlâ takıldın mı? Destek al