{
  "openapi": "3.1.0",
  "info": {
    "title": "Waffle API",
    "version": "1.1.0",
    "description": "Terima QRIS & virtual account, cairkan dana ke rekening bank. Base URL: https://api.getwaffle.id. Sandbox dan live memakai host yang sama; mode ditentukan oleh API key yang dipakai (key sandbox tidak bisa menggerakkan uang live). Setiap API key punya scope (charges:read, charges:write, payouts:read, payouts:write, balance:read) — lihat x-required-scope di tiap operasi dan deskripsi ApiKeyAuth."
  },
  "servers": [{ "url": "https://api.getwaffle.id", "description": "Production dan sandbox (mode mengikuti API key)" }],
  "security": [{ "ApiKeyAuth": [] }],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key sandbox/live dari dashboard (Developer › API key). Setiap key membawa satu preset (read_only | accept_payments | full | custom) dan sekumpulan scope granular: charges:read, charges:write, payouts:read, payouts:write, balance:read. Scope *:write TIDAK otomatis memberi *:read. Operasi yang butuh scope tertentu menandainya lewat x-required-scope; key tanpa scope itu mendapat 403 {\"error\":\"this API key lacks the <scope> permission\"}. GET /v1/whoami tidak butuh scope apa pun. Tidak ada scope atau endpoint untuk dokumen KYC, tim, pengaturan, konfigurasi webhook, branding, atau API key itu sendiri — semua itu hanya lewat sesi dashboard."
      }
    },
    "schemas": {
      "Money": { "type": "integer", "description": "Nominal dalam rupiah (satuan terkecil), mis. 50000 = Rp50.000", "example": 50000 },
      "FeeRuleSnapshot": {
        "type": "object",
        "description": "Aturan fee yang dipakai saat charge ini dihitung, disalin nilainya (bukan referensi hidup) — tidak berubah walau tarif diedit belakangan.",
        "properties": {
          "type": { "type": "string", "enum": ["percentage", "flat"] },
          "percent_bps": { "type": "integer", "description": "Basis poin (100 = 1%). 0 untuk aturan flat." },
          "flat_amount": { "$ref": "#/components/schemas/Money" }
        }
      },
      "ChargeBreakdown": {
        "type": "object",
        "description": "Rincian bagaimana fee charge ini dihitung (tampilan aman untuk merchant/API key — tidak ada biaya penyedia pembayaran atau margin). null untuk charge dua-fase yang belum dipilih channel-nya oleh payer.",
        "properties": {
          "base_amount": { "type": ["integer", "null"], "description": "null untuk charge sebelum fitur breakdown ada — jangan pernah menebak dari gross/fee/net." },
          "fee_amount": { "$ref": "#/components/schemas/Money" },
          "fee_bearer": { "type": ["string", "null"], "enum": ["merchant", "customer", null], "description": "Siapa yang menanggung fee. BUKAN \"payer\" — istilah checkout_channel_selection (\"merchant\"|\"payer\") itu konsep berbeda: siapa yang MEMILIH channel, bukan siapa yang MEMBAYAR fee." },
          "fee_rule": { "oneOf": [{ "$ref": "#/components/schemas/FeeRuleSnapshot" }, { "type": "null" }] },
          "payer_paid": { "$ref": "#/components/schemas/Money" },
          "merchant_receives": { "$ref": "#/components/schemas/Money" },
          "channel": { "type": "string" },
          "va_bank": { "type": "string" },
          "otc_channel": { "type": "string" },
          "ppn_amount": { "type": "integer", "description": "PPN yang dipungut di atas fee_amount. Hanya ada saat PPN dikenakan pada fee charge ini (fee_amount TIDAK termasuk PPN). payer_paid = merchant_receives + fee_amount + ppn_amount untuk kedua penanggung fee." },
          "ppn_rate": { "type": "number", "description": "Tarif PPN dalam persen saat charge dibuat (mis. 11). Hanya ada bersama ppn_amount." },
          "ppn_mode": { "type": "string", "enum": ["exclusive", "inclusive"], "description": "exclusive: PPN ditambahkan di atas fee yang tertulis. inclusive: fee yang tertulis sudah termasuk PPN (fee_amount + ppn_amount = fee tertulis). Hanya ada bersama ppn_amount." }
        }
      },
      "Charge": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "mode": { "type": "string", "enum": ["sandbox", "live"] },
          "status": { "type": "string", "enum": ["pending", "paid", "failed", "expired"] },
          "channel": { "type": "string", "enum": ["qris", "virtual_account", "otc"] },
          "description": { "type": "string", "maxLength": 255, "description": "Catatan bebas dari merchant untuk charge ini. Tidak pernah berisi directive uji sandbox (\"sandbox:<outcome>\") walau charge dibuat dengan directive itu di deskripsi." },
          "gross_amount": { "$ref": "#/components/schemas/Money" },
          "fee_amount": { "$ref": "#/components/schemas/Money" },
          "net_amount": { "$ref": "#/components/schemas/Money" },
          "currency": { "type": "string", "example": "IDR" },
          "qr_string": { "type": "string", "description": "Payload QRIS (channel=qris)" },
          "va_bank": { "type": "string", "example": "BCA" },
          "va_number": { "type": "string" },
          "otc_channel": { "type": "string", "enum": ["indomaret", "alfamart"], "description": "Gerai pembayaran (channel=otc)" },
          "payment_code": { "type": "string", "description": "Kode pembayaran yang ditunjukkan ke kasir gerai (channel=otc)" },
          "checkout_url": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "paid_at": { "type": "string", "format": "date-time" },
          "expires_at": { "type": "string", "format": "date-time" },
          "settled_at": { "type": "string", "format": "date-time" },
          "breakdown": { "oneOf": [{ "$ref": "#/components/schemas/ChargeBreakdown" }, { "type": "null" }] },
          "idempotency_key": { "type": "string", "description": "Idempotency-Key dari request yang membuat charge ini." },
          "provider_reference": { "type": "string", "description": "Referensi charge di sisi penyedia pembayaran (id yang Waffle kirim). Kosong sampai diketahui." },
          "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Metadata milik merchant (key/value string). Key internal Waffle tidak pernah ditampilkan; dihilangkan bila kosong." }
        }
      },
      "ChargeList": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Charge" } },
          "has_more": { "type": "boolean" }
        }
      },
      "BankAccount": {
        "type": "object",
        "description": "Rekening pencairan aktif untuk mode (sandbox/live) yang sedang dipakai. Registrasi/ganti rekening hanya lewat dashboard (butuh review manusia) — tidak ada endpoint API-key untuk itu. account_number di sini DIMASK ke 4 digit terakhir.",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "bank_code": { "type": "string", "example": "BCA" },
          "account_number": { "type": "string", "example": "••••7890", "description": "Dimask ke 4 digit terakhir untuk respons API key." },
          "account_holder_name": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "hold_reason": { "type": "string", "enum": ["payout_account_name_mismatch"], "description": "Hanya live, hanya bila ada: pencairan ke rekening ini ditahan karena nama pemilik rekening belum sesuai dengan nama pemilik di data KYC." },
          "hold_message": { "type": "string", "description": "Penjelasan berbahasa Indonesia untuk hold_reason." }
        }
      },
      "Payout": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "bank_account_id": { "type": "string", "format": "uuid" },
          "mode": { "type": "string", "enum": ["sandbox", "live"] },
          "status": { "type": "string", "enum": ["held", "pending", "processing", "completed", "failed"] },
          "amount": { "$ref": "#/components/schemas/Money" },
          "fee_amount": { "type": "integer", "description": "Total biaya pencairan (tidak termasuk PPN). amount = fee_amount + ppn_amount + net_amount." },
          "fee_transfer_amount": { "type": "integer", "description": "Bagian biaya transfer dari fee_amount. Hanya ada bersama fee_service_amount; tidak ada pada pencairan sebelum biaya dipecah atau saat fee_amount 0. fee_transfer_amount + fee_service_amount = fee_amount." },
          "fee_service_amount": { "type": "integer", "description": "Bagian biaya layanan dari fee_amount (total dikurangi biaya transfer). Hanya ada bersama fee_transfer_amount." },
          "ppn_amount": { "type": "integer", "description": "PPN yang dipungut di atas fee_amount. Hanya ada saat PPN dikenakan pada biaya pencairan." },
          "ppn_rate": { "type": "number", "description": "Tarif PPN dalam persen. Hanya ada bersama ppn_amount." },
          "ppn_mode": { "type": "string", "enum": ["exclusive", "inclusive"], "description": "Hanya ada bersama ppn_amount." },
          "net_amount": { "type": "integer", "description": "Jumlah yang diterima rekening bank." },
          "currency": { "type": "string", "example": "IDR" },
          "bank_code": { "type": "string" },
          "account_number": { "type": "string", "description": "Detail tujuan pada payout ini sendiri, TIDAK dimask (beda dari GET /v1/bank-accounts di atas)." },
          "account_holder_name": { "type": "string" },
          "failure_reason": { "type": "string" },
          "hold_reason": { "type": "string", "enum": ["payout_account_name_mismatch"], "description": "Hanya ada selama payout live ditahan karena nama pemilik rekening belum sesuai dengan nama pemilik di data KYC (status held atau pending). Payout tidak gagal dan tidak dikirim; dilepas otomatis setelah nama sesuai atau disetujui admin, atau dapat dibatalkan (saldo kembali)." },
          "hold_message": { "type": "string", "description": "Penjelasan berbahasa Indonesia untuk hold_reason." },
          "created_at": { "type": "string", "format": "date-time" },
          "completed_at": { "type": "string", "format": "date-time" },
          "idempotency_key": { "type": "string", "description": "Idempotency-Key dari request yang membuat payout ini." },
          "provider_reference": { "type": "string", "description": "Referensi payout di sisi penyedia pembayaran (id yang Waffle kirim). Kosong sampai diketahui." }
        }
      },
      "PayoutList": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } },
          "has_more": { "type": "boolean" }
        }
      },
      "WhoAmI": {
        "type": "object",
        "properties": {
          "merchant_id": { "type": "string", "format": "uuid" },
          "business_name": { "type": "string" },
          "mode": { "type": "string", "enum": ["sandbox", "live"] },
          "preset": { "type": "string", "enum": ["read_only", "accept_payments", "full", "custom"] },
          "scopes": { "type": "array", "items": { "type": "string", "enum": ["charges:read", "charges:write", "payouts:read", "payouts:write", "balance:read"] } }
        }
      },
      "Error": { "type": "object", "properties": { "error": { "type": "string" } } }
    }
  },
  "paths": {
    "/v1/charges": {
      "post": {
        "summary": "Buat charge",
        "x-required-scope": "charges:write",
        "description": "Butuh header Idempotency-Key. Channel qris/virtual_account/otc. Aturan validasi (400): virtual_account wajib va_bank; otc wajib otc_channel (indomaret atau alfamart) dan tidak boleh disertai va_bank; channel selain otc tidak boleh disertai otc_channel. Channel otc hanya tersedia jika diaktifkan untuk akun ini; hasilnya berisi payment_code yang ditunjukkan pembayar ke kasir gerai.",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "examples": {
                "qris": { "summary": "QRIS", "value": {"amount": 50000, "currency": "IDR", "channel": "qris"} },
                "virtual_account": { "summary": "Virtual account", "value": {"amount": 50000, "currency": "IDR", "channel": "virtual_account", "va_bank": "PERMATA"} }
              },
              "schema": {
                "type": "object",
                "required": ["amount"],
                "properties": {
                  "amount": { "$ref": "#/components/schemas/Money" },
                  "currency": { "type": "string", "default": "IDR" },
                  "channel": { "type": "string", "enum": ["qris", "virtual_account", "otc"] },
                  "va_bank": { "type": "string", "description": "Wajib untuk virtual_account. Harus dikosongkan untuk channel otc." },
                  "otc_channel": { "type": "string", "enum": ["indomaret", "alfamart"], "description": "Channel otc belum tersedia: nonaktif (503) sampai Waffle mengaktifkannya, jadi tidak ada di contoh. Wajib untuk channel otc (400 jika kosong atau tidak dikenal). Hanya valid untuk channel otc: channel lain menolak field ini dengan 400." },
                  "description": { "type": "string", "maxLength": 255, "description": "Catatan bebas, maksimal 255 karakter. Sisipkan sandbox:paid|failed|expired untuk hasil deterministik di sandbox — directive ini tidak pernah disimpan atau dikembalikan, hanya dipakai di sandbox." }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Charge dibuat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" } } } } }
      },
      "get": {
        "summary": "Daftar charge (cursor pagination)",
        "x-required-scope": "charges:read",
        "description": "Selalu ter-scope ke merchant + mode milik key ini. limit maksimal 100 (default 20), starting_after untuk halaman berikutnya, filter status dan created[gte]/created[lte].",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } },
          { "name": "starting_after", "in": "query", "schema": { "type": "string", "format": "uuid" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "paid", "failed", "expired"] } },
          { "name": "created[gte]", "in": "query", "schema": { "type": "string" }, "description": "RFC 3339 atau YYYY-MM-DD" },
          { "name": "created[lte]", "in": "query", "schema": { "type": "string" }, "description": "RFC 3339 atau YYYY-MM-DD" }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeList" } } } },
          "400": { "description": "created[gte]/created[lte] tidak valid, atau starting_after tidak bisa dilihat key ini", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/charges/{id}": {
      "get": {
        "summary": "Detail satu charge",
        "x-required-scope": "charges:read",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" } } } },
          "404": { "description": "Tidak ditemukan — termasuk charge milik merchant lain atau mode yang salah (sandbox key tidak bisa lihat charge live)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/sandbox/charges/{id}/simulate": {
      "post": {
        "summary": "Simulasikan hasil pembayaran charge sandbox",
        "description": "Hanya untuk API key sandbox. Charge sandbox tanpa direktif `sandbox:` tetap `pending` sampai disimulasikan. Memakai jalur yang sama dengan notifikasi dari penyedia pembayaran (ledger, webhook, SSE); mengulang hasil yang sama aman (idempotent) dan tidak mengkredit dua kali.",
        "x-required-scope": "charges:write",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": { "required": true, "content": { "application/json": { "examples": { "paid": { "summary": "Berhasil dibayar", "value": {"outcome": "paid"} }, "failed": { "summary": "Gagal", "value": {"outcome": "failed"} } }, "schema": { "type": "object", "required": ["outcome"], "properties": { "outcome": { "type": "string", "enum": ["paid", "pending", "failed", "expired"] } } } } } },
        "responses": {
          "200": { "description": "Status charge sebenarnya setelah pemanggilan", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } } } } },
          "400": { "description": "outcome tidak valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Key live (code sandbox_only) atau key tanpa scope charges:write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Tidak ditemukan — termasuk charge milik merchant lain atau charge live", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "charge_not_simulatable: charge tidak bisa pindah ke status itu (sudah final, atau metode pembayaran belum dipilih)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/charges/{id}/receipt.pdf": {
      "get": {
        "summary": "Bukti pembayaran PDF",
        "x-required-scope": "charges:read",
        "description": "Mengunduh bukti pembayaran (PDF) untuk satu charge yang sudah berhasil dibayar. Hanya untuk charge milik merchant dan mode key yang dipakai; selain itu 404. Charge yang belum berstatus paid mengembalikan 409.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "Berkas PDF (Content-Type: application/pdf)", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } },
          "404": { "description": "Tidak ditemukan, termasuk charge milik merchant lain atau mode lain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Dokumen hanya tersedia untuk pembayaran yang berhasil", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/fees/calculate": {
      "post": {
        "summary": "Preview fee (tanpa membuat charge)",
        "x-required-scope": "charges:read",
        "description": "Preview-only: tidak membuat charge, tidak mengubah saldo, tidak menghubungi penyedia pembayaran, tidak butuh Idempotency-Key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "examples": {
                "qris": { "summary": "QRIS", "value": {"amount": 50000, "currency": "IDR", "channel": "qris"} },
                "virtual_account": { "summary": "Virtual account", "value": {"amount": 50000, "currency": "IDR", "channel": "virtual_account", "va_bank": "PERMATA"} }
              },
              "schema": {
                "type": "object",
                "required": ["amount"],
                "properties": {
                  "amount": { "$ref": "#/components/schemas/Money" },
                  "currency": { "type": "string", "default": "IDR" },
                  "channel": { "type": "string", "enum": ["qris", "virtual_account", "otc"] },
                  "va_bank": { "type": "string", "description": "Wajib untuk virtual_account. Harus dikosongkan untuk channel otc." },
                  "otc_channel": { "type": "string", "enum": ["indomaret", "alfamart"], "description": "Channel otc belum tersedia: nonaktif (503) sampai Waffle mengaktifkannya, jadi tidak ada di contoh. Wajib untuk channel otc (400 jika kosong atau tidak dikenal). Hanya valid untuk channel otc: channel lain menolak field ini dengan 400." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "gross_amount": { "$ref": "#/components/schemas/Money" },
                    "fee_amount": { "$ref": "#/components/schemas/Money" },
                    "net_amount": { "$ref": "#/components/schemas/Money" },
                    "currency": { "type": "string" },
                    "ppn_amount": { "type": "integer", "description": "Hanya ada saat PPN dikenakan pada fee ini. fee_amount tidak termasuk PPN; gross_amount = net_amount + fee_amount + ppn_amount." },
                    "ppn_rate": { "type": "number", "description": "Tarif PPN dalam persen. Hanya ada bersama ppn_amount." },
                    "ppn_mode": { "type": "string", "enum": ["exclusive", "inclusive"], "description": "Hanya ada bersama ppn_amount." }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/balance": {
      "get": {
        "summary": "Saldo tersedia",
        "x-required-scope": "balance:read",
        "parameters": [{ "name": "currency", "in": "query", "schema": { "type": "string", "default": "IDR" } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/v1/bank-accounts": {
      "get": {
        "summary": "Rekening pencairan aktif (dimask)",
        "x-required-scope": "payouts:read",
        "description": "Baca id rekening yang sudah aktif untuk mode ini, dipakai sebagai bank_account_id saat mencairkan dana. account_number dimask ke 4 digit terakhir. Registrasi rekening baru HANYA lewat dashboard (POST /v1/merchants/me/bank-accounts, sesi login) — tidak ada lagi endpoint API-key untuk registrasi (perlindungan: API key yang bocor tidak bisa mengalihkan tujuan pencairan dana). POST /v1/bank-accounts sudah dihapus dari permukaan API key.",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccount" } } } },
          "404": { "description": "Belum ada rekening aktif untuk mode ini — daftarkan dulu lewat dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/payouts": {
      "post": {
        "summary": "Cairkan dana",
        "x-required-scope": "payouts:write",
        "description": "Butuh header Idempotency-Key. Minimal Rp10.000, maksimal = saldo available. bank_account_id dari GET /v1/bank-accounts.",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "examples": {
                "payout": { "summary": "Pencairan ke rekening terdaftar", "value": {"bank_account_id": "11111111-2222-3333-4444-555555555555", "amount": 150000, "currency": "IDR"} }
              },
              "schema": {
                "type": "object",
                "required": ["bank_account_id", "amount"],
                "properties": {
                  "bank_account_id": { "type": "string", "format": "uuid" },
                  "amount": { "$ref": "#/components/schemas/Money" },
                  "currency": { "type": "string", "default": "IDR" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Payout dibuat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } },
          "422": { "description": "Saldo tidak cukup / di bawah minimal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "get": {
        "summary": "Daftar payout (cursor pagination)",
        "x-required-scope": "payouts:read",
        "description": "Sama seperti GET /v1/charges: limit maksimal 100 (default 20), starting_after, filter status dan created[gte]/created[lte]. Selalu ter-scope ke merchant + mode milik key ini.",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } },
          { "name": "starting_after", "in": "query", "schema": { "type": "string", "format": "uuid" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "held", "processing", "completed", "failed"] } },
          { "name": "created[gte]", "in": "query", "schema": { "type": "string" } },
          { "name": "created[lte]", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutList" } } } }
        }
      }
    },
    "/v1/payouts/{id}/cancel": {
      "post": {
        "summary": "Batalkan payout yang masih ditahan",
        "x-required-scope": "payouts:write",
        "description": "Membatalkan payout berstatus held (masa penahanan setelah rekening pencairan diganti) dan mengembalikan saldo. Payout dengan status lain tidak bisa dibatalkan. Hanya menyentuh mode key yang dipakai.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "Payout setelah dibatalkan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } },
          "404": { "description": "Tidak ditemukan, termasuk payout milik merchant lain atau mode lain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "payout_not_cancellable: hanya payout berstatus held yang bisa dibatalkan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/payouts/{id}/receipt.pdf": {
      "get": {
        "summary": "Bukti pencairan PDF",
        "x-required-scope": "payouts:read",
        "description": "Mengunduh bukti pencairan (PDF) untuk payout yang sudah selesai. Payout yang belum selesai mengembalikan 409.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "Berkas PDF (Content-Type: application/pdf)", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } },
          "404": { "description": "Tidak ditemukan, termasuk payout milik merchant lain atau mode lain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Dokumen hanya tersedia untuk pencairan yang sudah selesai", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/payouts/{id}": {
      "get": {
        "summary": "Detail satu payout",
        "x-required-scope": "payouts:read",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } },
          "404": { "description": "Tidak ditemukan — termasuk payout milik merchant lain atau mode yang salah", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/sandbox/balance/topup": {
      "post": {
        "summary": "Tambah saldo sandbox",
        "x-required-scope": "payouts:write",
        "description": "Menambah saldo SANDBOX dengan uang uji agar payout bisa dicoba tanpa membayar charge dulu. Key live ditolak dengan 403; rute ini tidak pernah menyentuh uang live.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["amount", "currency"], "properties": { "amount": { "type": "integer", "format": "int64", "description": "Rupiah, bilangan bulat." }, "currency": { "type": "string", "enum": ["IDR"] } } }, "example": { "amount": 500000, "currency": "IDR" } } } },
        "responses": {
          "200": { "description": "Saldo sandbox setelah penambahan", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "amount": { "type": "integer", "format": "int64" } } } } } },
          "400": { "description": "Nominal atau body tidak valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Key live (hanya key sandbox yang boleh)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/v1/whoami": {
      "get": {
        "summary": "Siapa saya (merchant, mode, preset, scope) — tidak butuh scope",
        "description": "Bisa dipanggil key manapun, scope apapun. Dipakai MCP client untuk tahu tool mana yang boleh ditawarkan sebelum mencoba dan kena 403.",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmI" } } } }
        }
      }
    },
    "/v1/banks": {
      "get": {
        "summary": "Daftar bank",
        "description": "Butuh API key (header Authorization: Bearer), tanpa scope tertentu. Data referensi statis; tidak berubah oleh scope key.",
        "responses": {
          "200": { "description": "OK" },
          "401": { "description": "API key tidak ada atau tidak valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  }
}
