API Referansı

Aşağıdaki her uç nokta JSON konuşur, https://api.infraio.xyz (prod) veya https://api-dev.infraio.xyz (test) altında yaşar ve HMAC-SHA256 ile kimlik doğrulanır — imzalama ritüeli için Kimlik doğrulama ve hata zarf şekli için Hatalar sayfasına bakın.

Bu sayfa indekstir. Her satır mevcut en derin yazıma bağlanır; bir satır yalnızca bir yola referans veriyorsa, uç nokta bugün mevcuttur ama kendi referans sayfası yerine ilgili kavram sayfasında satır içi olarak belgelenmiştir.

Geçit yol önekleri ve auth modelleri:

/b2b/v1/* — secret anahtarınızla (sk_…) HMAC-imzalı. Satıcı backend yüzeyi.
/payment/v1/* — Bearer JWT (panel oturumları). Satıcı paneli frontend’i tarafından kullanılır; üçüncü taraf entegratörler için değil.
/pub/v1/* — yolda bearer-kanıtı (iade istekleri için rfqt_… token’ı). Kimlik bilgisi yok. Tarayıcıdan çağırmak güvenlidir.
/checkout/:key/* — Barındırılan checkout akışı için public önek. key, oluşturma zamanında döndürülen cst_… oturum anahtarıdır; alıcının tarayıcısı tek çağırandır. Kimlik bilgisi yok.

Checkout

Method	Path	Amaç	Notlar
`POST`	`/b2b/v1/checkout-sessions/quick`	Tek çağrıda bir oturum oluştur — order + checkout-session birlikte üretilir.	İstek gövdesi ve örnek için bkz. Hızlı başlangıç.
`POST`	`/b2b/v1/checkout-sessions`	Mevcut bir siparişe karşı oturum oluştur. Platformunuzun zaten kendi sipariş modeli olduğunda ve deneme başına bir oturum istediğinizde kullanın.	İki adımlı akış.
`GET`	`/b2b/v1/checkout-sessions/by-order/{order_id}`	Bir sipariş için üretilmiş tüm oturumları listele.	Bir alıcı bir oturumu terk ettiğinde ve önceki denemeleri panelinizde göstermek istediğinizde kullanışlı.
`GET`	`/checkout/{session_key}`	Public — barındırılan checkout sayfası bunu çağırır. Yalnızca alıcıya yönelik alanlar (dahili referans yok).	İmzalama yok; `session_key`’i bearer-kanıtı olarak alır.
`POST`	`/checkout/{session_key}/intent`	Public — barındırılan sayfada bir ödeme yöntemi seç. Depozito adresi ile bir `PaymentIntent` yayar.	Kullanıcı yöntem seçiminde checkout-web tarafından çağrılır.
`POST`	`/checkout/{session_key}/verify`	Public — alıcının onay beklemesini kısa devre yapması için bir tx hash yapıştırmasına izin ver.	Hash yanlışsa zincir izleyiciye düşer.

Siparişler

Siparişler zamansız faturalanabilir varlıktır. Tek bir sipariş birden fazla checkout oturumunu destekleyebilir (örn. alıcı terk eder, yeniden dener).

Method	Path	Amaç	Notlar
`POST`	`/b2b/v1/orders`	Oturumsuz bir sipariş oluştur.	Alıcıyı hemen yönlendirmek yerine daha sonra bir ödeme bağlantısı göndermek istediğinizde kullanın.
`GET`	`/b2b/v1/orders/{id}`	Line item’lar + durum ile tek bir siparişi oku.	Durum: `PENDING` → `PAID` \| `PARTIAL_PAID` \| `CANCELED`. İade sonrası: `PARTIALLY_REFUNDED` \| `REFUNDED`.
`GET`	`/b2b/v1/orders/by-merchant/{merchant_id}`	Siparişlerinizi listele, cursor-pagination ile.	Cursor protokolü için bkz. Cursor pagination.
`PATCH`	`/b2b/v1/orders/{id}/cancel`	Ödenmemiş bir siparişi iptal edildi olarak işaretle. `order.canceled` yayar.	Sipariş zaten ödenmişse başarısız olur.
`PATCH`	`/b2b/v1/orders/{id}/reopen`	Bir otomatik-iptali tersine çevir (`canceled_reason=payment_timeout`).	TTL süresi dolduktan sonra alıcı geri gelirse kullanışlı.

İadeler

Saga akışı ve token yaşam döngüsü için İadeler kavram sayfasına bakın.

Satıcı tarafından başlatılan

Method	Path	Amaç	Notlar
`POST`	`/b2b/v1/merchants/{merchant_id}/refunds`	Satıcı tarafından başlatılan iade. Otomatik onaylanır (`PENDING` atlanır).	Hemen `payment.refund.approved` yayar.

Müşteri tarafından başlatılan — iade-talep token’ları

Alıcı iade formunu bizim barındırılan sayfamızda doldurur; siz yalnızca token’ı üretir ve URL’yi iletirsiniz. İki üretim yolu (backend’ler için HMAC, panel için JWT), üç public token yolu (bağlam oku, gönder, yenileme talep et) ve yenilemeleri yönetmek için iki yalnızca-panel yolu.

Method	Path	Auth	Amaç
`POST`	`/b2b/v1/merchants/{merchant_id}/refund-requests`	HMAC (`sk_…`)	Backend’inizden bir token üret. Gövde: `{ref_type, ref_value, amount, ttl_seconds?, metadata?, hide_summary?, hide_header?}`. `ref_type` `order_id` / `order_number` / `session_id` / `session_key`’den biridir; `ref_value` eşleşen tanımlayıcıdır. `amount` gereklidir ve alıcının gönderebileceği maksimumu kilitler. Varsayılan TTL 30 dk. `refund_request.created` yayar (`source: b2b`).
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests`	JWT (panel)	Satıcı panelinin Issue Refund modal’ından bir token üret. B2B varyantı ile aynı gövde şekli. Varsayılan TTL 24 s. `refund_request.created` yayar (`source: dashboard`).
`GET`	`/pub/v1/refund-requests/{token}`	Yolda token	Public — checkout-web form bağlamını okur (sipariş özeti, kilitli tutar, mevcut etkili durum).
`POST`	`/pub/v1/refund-requests/{token}/submit`	Yolda token	Public — alıcı formu gönderir. Gövde: `{reason, refund_to_address, amount?, metadata?}`. `amount` opsiyoneldir — atlandığında satıcı tarafından kilitlenmiş bağlantı tutarı kullanılır; mevcut olduğunda sunucu `amount ≤ kilitli tutar` zorunluluğunu uygular. `Refund` satırını oluşturur, `payment.refund.requested` yayar, makbuz sayfası için `{link_token, refund_id}` döndürür.
`POST`	`/pub/v1/refund-requests/{token}/request-renewal`	Yolda token	Public — alıcı, son kullanma sonrasında yeni bir bağlantı talep eder. Gövde: `{customer_note?}`. `refund_request.renewal_requested` yayar.
`GET`	`/payment/v1/merchants/{merchant_id}/refund-requests/renewals`	JWT (panel)	Satıcının yenileme widget’ı için bekleyen `RENEWAL_REQUESTED` token’larını listele. Cursor-paginated.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/renewals/{token}/issue-new`	JWT (panel)	Bir yenilemeyi onayla — yeni bir `ACTIVE` token üretir, eskisini devre dışı bırakır. `refund_request.renewed` + `refund_request.created` yayar (`source: renewal`).
`GET`	`/payment/v1/merchants/{merchant_id}/refund-requests/by-order/{order_id}`	JWT (panel)	Bir siparişe karşı üretilmiş tüm iade-talep token’larını etkili durumu ile listele. En yeni önce.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/{token}/send-email`	JWT (panel)	İade-talep bağlantısının e-posta gönderimini müşteriye kuyruğa al. Gövde: `{to}`. `refund_request.email_send_requested` yayar.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/{token}/cancel`	JWT (panel)	Satıcı acil-durdurma anahtarı — `ACTIVE` veya `RENEWAL_REQUESTED` → `CANCELED`’a geçirir. Gövde: `{reason?}`. Idempotent: durum zaten geçtikten sonraki ikinci çağrı, yeniden yaymadan başarı döndürür. İlk geçişte `refund_request.canceled` yayar.

İade yaşam döngüsü (oluşturma-sonrası)

Her iki akış için de geçerlidir. Aşağıdaki uç noktalar, talep token’ı üzerinde değil, Refund satırı üzerinde işlem yapar (id rfn_… ile başlar).

Method	Path	Amaç	Notlar
`GET`	`/b2b/v1/refunds/{id}`	Bir iadeyi oku.	Durum: `PENDING` → `APPROVED` → `EXECUTED` \| `REJECTED`.
`GET`	`/b2b/v1/refunds/by-merchant/{merchant_id}`	İadelerinizi listele, cursor-paginated.	—
`POST`	`/b2b/v1/refunds/{id}/approve`	`PENDING` bir iadeyi onayla (yalnızca müşteri tarafından başlatılan — satıcı tarafından başlatılan zaten `APPROVED` ile gelir).	Kripto: `APPROVED`’a iner, sonrasında `/submit-tx` çağırırsınız.
`POST`	`/b2b/v1/refunds/{id}/reject`	`PENDING` bir iadeyi reddet.	`payment.refund.rejected` yayar.
`POST`	`/b2b/v1/refunds/{id}/submit-tx`	Yalnızca kripto — yaydığınız zincir üstü tx hash’i damgala.	Gövde: `{tx_hash, network, token_address}` — üçü de gereklidir.

Katalog (yalnızca-okuma)

Method	Path	Amaç
`GET`	`/v1/supported/networks`	InfraIO’nun tahsilat yapabileceği tüm zincirler (mainnet + testnet, env tarafından filtrelenmiş).
`GET`	`/v1/supported/tokens`	Bu zincirler üzerindeki tüm stablecoinler.
`GET`	`/v1/supported/currencies`	`order.currency` için kabul edilen fiat para birimleri.
`GET`	`/v1/merchants/payment-methods`	BU satıcının etkinleştirdiği yöntemler — platform kataloğu + satıcı başına geçiş anahtarlarının birleşimi. checkout-web tarafından kullanılır.
`GET`	`/v1/public/merchants/{merchant_id}/branding`	Public — checkout sayfasının kendini biçimlendirmek için okuduğu şey.

Sağlık

Method	Path	Auth	Amaç
`GET`	`/health`	Yok (public)	Düz canlılık probe — `{"status":"ok"}` döndürür. Bu (`/v1` öneki olmadan) tek doğrulanmamış sağlık uç noktasıdır — k8s / uptime monitörlerinizi buraya yönlendirin.
`GET`	`/payment/v1/merchants/{merchant_id}/health`	Panel JWT’si	Satıcı başına sağlık görünümü — son intent tahsilat oranı, sweep birikim. Kendi durum sayfalarınız için kullanışlı. Bir B2B API anahtarı değil, bir panel oturum token’ı gerektirir. Yalnızca `/payment/` geçit öneki altında erişilebilir — çıplak `/v1/...` yolu public olarak yönlendirilmez.
`GET`	`/payment/v1/stats/health`	Panel JWT’si	Bir satıcının çalışma alanı ağacı genelinde toplu sağlık. Public bir canlılık probe değildir — `/payment/` geçit öneki altında, geri kalanla aynı JWT auth’ın arkasında oturur.

Cursor pagination

Her liste uç noktası aynı query parametrelerini kabul eder, aynı zarfı döndürür. Bir satır kaydırma ortasında düştüğünde bir sayfanın asla kaymaması için offset yerine opak cursorlar (base64url-encoded (created_at, id)) kullanırız.

Query param	Tip	Varsayılan	Notlar
`cursor`	`string`	—	Opak — önceki yanıtın `next_cursor`’ını kelimesi kelimesine kopyalayın.
`limit`	`int`	`20`	`1..100`.
`sort_dir`	`'asc' \| 'desc'`	`desc`	`(created_at, id)` ile sırala.
`from` / `to`	`RFC3339`	—	Opsiyonel zaman penceresi filtresi.
`search`	`string`	—	Desteklenen yerlerde serbest metin filtresi.

Yanıt zarfı:


{
  "orders": [ /* sayfa satırları */ ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0...",
  "has_next": true
}

has_next her zaman mevcuttur. has_next false olduğunda next_cursor atlanır. Cursor’ı parse etmeye çalışmayın — şekli dahilidir ve değişecektir.

Bu sayfada eksik olan

Bu indeks, satıcıya yönelik yüzeyi kapsar — /admin/* altındaki uç noktalar (panel araçları, KYB incelemesi, ağ yönetimi) ve dahili gRPC rotaları kasıtlı olarak listelenmemiştir. swag tarafından oluşturulan OpenAPI spec tüm yüzeyi kapsar; ihtiyacınız varsa, desteğe ulaşın ve güncel bir snapshot paylaşalım.