{"openapi":"3.1.0","info":{"title":"Efespay API v1","version":"v1","description":"İşletme sunucusundan çağrılan ödeme API'si. Kimlik: `Authorization: Bearer efp_test_sk_…` (test) / `efp_live_sk_…` (canlı). Gövde ve yanıtlar snake_case, tutarlar kuruş (`amount_minor`). Hata: `{ error: { code, message, request_id, param? } }`. Yazma uçlarında `Idempotency-Key` önerilir. Sonuç bildirimleri imzalı webhook ile gelir (`Efespay-Signature`)."},"servers":[{"url":"https://api.efespay.com"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Efespay API anahtarı (efp_{test|live}_{sk|rk}_…)"}}},"security":[{"apiKey":[]}],"paths":{"/v1/mcp":{"post":{"summary":"MCP sunucusu (JSON-RPC 2.0, Streamable HTTP, durumsuz)","tags":["v1"],"description":"Model Context Protocol uç noktası: initialize, ping, tools/list, tools/call. Araçlar: get_payment, list_payments (payments:read), create_payment_link (payment_links:write), request_refund ve get_refund_request (refund_requests:write). Kısıtlı anahtarda tools/list yalnız izinli araçları listeler. request_refund iade yapmaz; panelde insan onayına düşen iade talebi (rq_…) açar. Araç çağrısı anahtar başına dakikada 60; aşımda 429 ve JSON-RPC hata kodu -32029."}},"/v1/payment-links":{"post":{"summary":"Ödeme linki oluştur","tags":["v1"],"description":"Gövde { title, description?, amount_mode: fixed|open, amount_minor (fixed), amount_min_minor?/amount_max_minor? (open), installment_options?, expires_at? (ISO), usage_limit?, customer_fields?: { name, email, phone: required|optional|hidden }, return_url?, metadata? }. Idempotency-Key önerilir. Yanıt 201 payment_link { id: pl_…, code, url }."},"get":{"summary":"Ödeme linkleri (yeniden eskiye)","tags":["v1"],"description":"Sorgu: status, limit (1–100), starting_after (pl_…)."}},"/v1/payment-links/{id}":{"get":{"summary":"Ödeme linki","tags":["v1"]}},"/v1/payment-links/{id}/deactivate":{"post":{"summary":"Linki kapat (açık oturumlar etkilenmez)","tags":["v1"]}},"/v1/payment-links/{id}/qr":{"get":{"summary":"Link adresinin QR kodu (image/svg+xml)","tags":["v1"]}},"/v1/payment-methods":{"get":{"summary":"Müşterinin kayıtlı kartları","tags":["v1"],"description":"Kapsam payment_methods:read. Sorgu: customer (cus_…) ya da customer_external_reference (oturumda verdiğiniz müşteri kimliği); all=1 süresi dolmuş ve silinmişleri de getirir. Yanıt { object: list, data: [payment_method { id: pm_…, status: active | expired | deleted, card: { network, bank, last4, type, exp_month, exp_year }, connection_id, provider, customer_id }] }."}},"/v1/payment-methods/{id}":{"get":{"summary":"Kayıtlı kart","tags":["v1"]},"delete":{"summary":"Kayıtlı kartı sil","tags":["v1"],"description":"Kapsam payment_methods:write. Efespay kaydı kapanır (status deleted), sağlayıcı kasasından silme denenir. Etkin abonelikte kullanılan kart 409 payment_method_in_use."}},"/v1/payments":{"get":{"summary":"Ödemeler (yeniden eskiye)","tags":["v1"],"description":"Sorgu: status (virgüllü), order_reference, link_id (pl_…), created_gte, created_lte (ISO), limit (1–100, 25), starting_after (pay_…). Yanıt { object: list, data, has_more }."},"post":{"summary":"Kayıtlı kartla tahsilat (işletme başlatmalı, MIT)","tags":["v1"],"description":"Kapsam payments:charge. Gövde { payment_method: pm_…, order_reference, amount_minor, currency?: TRY, description?, metadata? }. Idempotency-Key zorunlu (yoksa 400 idempotency_key_required). Tahsilat kartın kaydedildiği bağlantıdan yapılır (yönlendirme yok), 3D Secure yok. Yanıt 201 payment { status: succeeded | failed | uncertain, initiator: merchant, payment_method_id }; kart reddi HTTP hatası değildir (status failed, failure dolu). uncertain: sağlayıcıdan yanıt alınamadı, Efespay sorgular; sonuç payment.succeeded / payment.failed webhook'uyla gelir. 404 payment_method_not_found, 409 payment_method_inactive | payment_method_connection_unavailable | order_reference_in_use."}},"/v1/payments/{id}":{"get":{"summary":"Ödeme","tags":["v1"],"description":"Doğrulanmış durum: pending | processing | uncertain | failed | succeeded | cancelled | expired. Tarayıcı dönüşü ödemenin başarılı sayılması için yeterli değildir; siparişi bu uç ya da webhook ile güncelleyin."}},"/v1/payments/{id}/attempts":{"get":{"summary":"Ödeme denemeleri (her sağlayıcı çağrısı)","tags":["v1"]}},"/v1/payments/{id}/refunds":{"post":{"summary":"İade (tam ya da kısmi)","tags":["v1"],"description":"Gövde: { amount_minor? (yoksa iade edilebilir tutarın tamamı), reason?, item_id? (pazaryeri kalemi pit_…; kalemin kalanını aşamaz — pazaryeri ödemesinde item_id yoksa yalnız kalanın tamamı) }. Idempotency-Key önerilir. Yanıt 201 refund { status: succeeded | failed | uncertain }. uncertain: sağlayıcıdan yanıt alınamadı, Efespay sorgular; sonuç refund.succeeded / refund.failed webhook'uyla gelir. 409 payment_not_refundable | refund_exceeds_available | partial_refund_not_supported."},"get":{"summary":"Ödemenin iadeleri","tags":["v1"]}},"/v1/payments/{id}/capture":{"post":{"summary":"Provizyonu tahsil et","tags":["v1"],"description":"Yalnız capture manual ile açılmış ve status authorized ödemede. Gövde: { amount_minor? (yoksa provizyonun tamamı; kısmi tahsilde kalan serbest kalır) }. Tek tahsil; Idempotency-Key önerilir. Kapsam payments:refund (para hareketi başlatan işlem). Yanıt payment { status: succeeded } ya da sonuç bilinmiyorsa authorized + authorization.operation.status uncertain (sonuç payment.captured webhook'uyla gelir). Provizyonu iptal etmek için /cancel. 409 payment_not_authorized | capture_exceeds_authorized | authorization_expired | authorization_operation_in_progress | capture_failed."}},"/v1/payments/{id}/cancel":{"post":{"summary":"İptal","tags":["v1"],"description":"Ödeme başlamadıysa oturum kapanır (payment.cancelled). Başarılı ödeme sağlayıcı destekliyorsa iptal edilir (void, tamamı); desteklemiyorsa 409 cancel_not_supported — iade kullanın. Provizyondaki (authorized) ödemede provizyon iptal edilir, tutar serbest kalır (payment.cancelled). Müşteri ödeme adımındaysa 409 payment_in_progress."}},"/v1/payment-sessions":{"post":{"summary":"Ödeme oturumu oluştur","tags":["v1"],"description":"Gövde: { order_reference, amount_minor, currency?: TRY, description?, installment_options?: [1..12], customer?: { name, email, phone, external_reference }, return_url?, expires_in_minutes?: 5–10080 (60), metadata?, locale?: tr|en, items?: [{ id, name, category?, amount_minor, sub_merchant: smr_…, sub_merchant_amount_minor }] (pazaryeri, docs/PAYMENTS.md §1.18: amount_minor yoksa kalem toplamı; verilirse eşit olmalı; capture manual ile birleşmez) }. Idempotency-Key önerilir. Yanıt 201 payment_session { id: ps_…, url, payment_id: pay_…, installment_options: [{ installments, total_minor, fee_minor }] }. Hata: 400 invalid_order_reference | invalid_amount | unsupported_currency | return_url_not_allowed | items_amount_mismatch | sub_merchant_not_found …, 409 order_reference_in_use | idempotency_conflict | sub_merchant_suspended | marketplace_not_available."}},"/v1/payment-sessions/{id}":{"get":{"summary":"Ödeme oturumu","tags":["v1"]}},"/v1/provider-connections":{"get":{"summary":"Sağlayıcı bağlantıları","tags":["v1"],"description":"Yanıt { object: list, data: [provider_connection { id: pc_…, provider, label, status, priority, allowed_installments, capabilities, last_test, health }] }."}},"/v1":{"get":{"summary":"API bilgisi (anahtar doğrulaması)","tags":["v1"]}},"/v1/sub_merchants":{"post":{"summary":"Alt üye işyeri (pazaryeri satıcısı) ekle","tags":["v1"],"description":"Kapsam sub_merchants:write. Gövde { type: individual | private_company | limited_or_joint_stock, name, legal_name?, tax_office?, email, phone?, address, city?, iban (TR, mod-97), identity_number? (TCKN; individual ve private_company zorunlu), tax_number? (VKN; limited_or_joint_stock zorunlu), external_reference?, notes? }. Kayıt pazaryeri destekleyen her etkin bağlantıya gönderilir. Yanıt 201 sub_merchant { id: smr_…, status: active | pending | suspended, iban (maskeli), identity_number (maskeli), tax_number (maskeli), registrations: [{ connection_id, provider, status: registered | failed, error }] }."},"get":{"summary":"Alt üye işyerleri (yeniden eskiye)","tags":["v1"],"description":"Kapsam sub_merchants:read. Sorgu: status, search, limit (1–100, 25), starting_after (smr_…). Yanıt { object: list, data, has_more }."}},"/v1/sub_merchants/{id}":{"get":{"summary":"Alt üye işyeri","tags":["v1"]},"post":{"summary":"Alt üye işyerini güncelle","tags":["v1"],"description":"Kapsam sub_merchants:write. Gövde oluşturmayla aynı alanlar (hepsi isteğe bağlı) + status: active | suspended. Boş gönderilen iban, identity_number ya da tax_number kayıtlı değeri korur."}},"/v1/payments/{id}/items/{item_id}/approve":{"post":{"summary":"Pazaryeri kalemini onayla","tags":["v1"],"description":"Kapsam payments:refund. Ödeme succeeded, kalem pending_approval ya da disapproved olmalı. Yanıt payment_item { status: approved } (payment_item.approved olayı); sonuç bilinmiyorsa operation.status uncertain ve sonuç olayla gelir. 409 item_operation_in_progress | item_not_approvable | item_fully_refunded | item_approve_failed. Idempotency-Key önerilir."}},"/v1/payments/{id}/items/{item_id}/disapprove":{"post":{"summary":"Pazaryeri kalemini onaylama / onayı geri çek","tags":["v1"],"description":"Kapsam payments:refund. Kalem pending_approval ya da approved olmalı (sağlayıcı satıcıya ödemeyi yapmadan önce). Yanıt payment_item { status: disapproved } (payment_item.disapproved olayı); satıcı payı tutulur."}},"/v1/subscriptions":{"post":{"summary":"Abonelik aç","tags":["v1"],"description":"Kapsam subscriptions:write. Gövde { customer: cus_…, payment_method: pm_… (müşterinin etkin kartı), amount_minor, currency?: TRY, description?, interval: day | week | month | year, interval_count? (1), start_at? (ISO; varsayılan şimdi), max_charges? (1–1000), retry_days? (varsayılan [1,3,5]; en çok 3, 1–6 gün, artan, dönemden kısa), final_action?: cancel | pause, metadata? }. Aylık/yıllıkta gün ayın sonuna kırpılır (31 Ocak → 28/29 Şubat → 31 Mart). Başarısız tahsilatta status past_due, yeniden denemeler; sonuncusu da başarısızsa final_action. Yanıt 201 subscription. Idempotency-Key önerilir."},"get":{"summary":"Abonelikler (yeniden eskiye)","tags":["v1"],"description":"Kapsam subscriptions:read. Sorgu: status, customer (cus_…), limit (1–100, 25), page."}},"/v1/subscriptions/{id}":{"get":{"summary":"Abonelik","tags":["v1"]},"post":{"summary":"Aboneliği güncelle (kart, açıklama, metadata)","tags":["v1"],"description":"Kapsam subscriptions:write. Gövde { payment_method?, description?, metadata? }."}},"/v1/subscriptions/{id}/pause":{"post":{"summary":"Duraklat","tags":["v1"]}},"/v1/subscriptions/{id}/resume":{"post":{"summary":"Devam ettir","tags":["v1"],"description":"Ödenmemiş dönem varsa hemen yeniden denenir; yoksa sıradaki gelecek dönemden faturalanır. Kart kullanılamıyorsa 409 payment_method_inactive."}},"/v1/subscriptions/{id}/cancel":{"post":{"summary":"İptal et","tags":["v1"],"description":"Gövde { reason? }. Geri alınamaz; ödenmemiş dönemin ödeme sayfası kapanır."}},"/v1/webhook-endpoints":{"post":{"summary":"Webhook uç noktası oluştur","tags":["v1"],"description":"Gövde { url (https), events?: [payment.succeeded, …] | [\"*\"], description? }. Yanıt 201 webhook_endpoint + secret (whsec_…, yalnız bu yanıtta). İmza: Efespay-Signature: t=<unix>,v1=<hex HMAC_SHA256(secret, t + \".\" + gövde)>."},"get":{"summary":"Webhook uç noktaları","tags":["v1"]}},"/v1/webhook-endpoints/{id}":{"get":{"summary":"Webhook uç noktası","tags":["v1"]},"patch":{"summary":"Güncelle — { url, events, description, status: enabled|disabled }","tags":["v1"]},"delete":{"summary":"Kaldır","tags":["v1"]}},"/v1/webhook-endpoints/{id}/rotate-secret":{"post":{"summary":"İmza sırrını yenile — yanıt webhook_endpoint + secret","tags":["v1"]}},"/v1/webhook-endpoints/{id}/test":{"post":{"summary":"Test olayı (ping) — yanıt webhook_delivery","tags":["v1"]}}},"tags":[]}