openapi: 3.1.0
info:
  title: Nadipay Dealer API
  version: 1.0.0
  summary: Pesan produk digital (pulsa, data, token PLN, voucher game) lewat API dan pantau ordernya sampai selesai.
  description: |
    Pesan produk digital untuk pelangganmu lewat satu API: pulsa, paket data, token PLN, dan
    voucher game. Kamu isi deposit, tiap order memotong saldo, dan hasilnya kami kirim ke
    servermu lewat callback.

    ## Mulai cepat
    1. **Dapatkan akses.** Tim Nadipay membuat akun dealer dan memberimu **API key**
       (`dlr_...`) dan **API secret**. Secret hanya tampil sekali dan tidak kami simpan, jadi
       simpan baik-baik. Kalau hilang, kami buatkan yang baru.
    2. **Isi deposit.** Setiap order memotong saldo sebesar harga jualmu. Order yang gagal
       dikembalikan penuh dan otomatis.
    3. **Pilih produk.** `GET /api/v1/dealer/products` menampilkan kode produk beserta harga
       jual untukmu.
    4. **Buat order.** `POST /api/v1/dealer/orders` dengan `productId`, `customerNo`, dan
       `dealerReferenceNo` milikmu sendiri.
    5. **Terima hasil.** Kami mengirim callback ke URL-mu saat order selesai. Kamu juga bisa
       memanggil `GET /api/v1/dealer/orders/{orderId}` kapan saja.

    ## Lingkungan
    | Lingkungan | Base URL | Fungsi |
    |---|---|---|
    | **Sandbox** | `https://sandbox.getnadi.id` | Uji integrasi. Tanpa uang asli. Daftar sendiri dan dapat kredensial + saldo Rp1.000.000 |
    | **Production** | `https://nadipay.getnadi.id` | Transaksi sungguhan. Akun dibuat tim Nadipay |

    Sandbox memakai API, signature, dan format yang sama dengan production. Bedanya semua hasil
    disimulasikan: produk selalu sukses, dan top up bisa dipaksa gagal atau pending lewat
    akhiran nomor (lihat **Top up saldo DANA**). Kredensial sandbox **tidak berlaku** di production
    dan sebaliknya. Callback di sandbox pun wajib `https` dengan host publik (pakai tunnel
    seperti ngrok bila servermu masih lokal).

    Daftar akun sandbox lewat `POST /api/sandbox/register` atau form di
    `https://sandbox.getnadi.id/partner/`. Isi ulang saldo uji kapan saja dengan
    `POST /api/sandbox/deposit` (maksimal Rp5.000.000 per panggilan).

    ## Portal laporan partner
    Login di `/partner/` (sandbox maupun production) dengan **Dealer ID** (API key) dan
    **password portal** yang diberikan bersama API secret. Isinya: saldo deposit, ringkasan hari ini,
    daftar transaksi (order dan top up), mutasi saldo, unduh CSV, dan pengaturan URL callback.
    Portal bersifat baca-saja untuk saldo; isi deposit dilakukan lewat transfer ke rekening Nadipay
    dan dicatat oleh tim kami.

    ## Isi deposit (production)
    Transfer dari bank mana pun ke rekening BNI atas nama PT Nadi Teknologi Indonesia, lalu
    konfirmasi ke tim Nadipay. Saldo bertambah setelah mutasi kami verifikasi. Gunakan nominal
    unik (tambah kode 3 digit) supaya pencocokan cepat.

    ## Autentikasi dan signature
    Setiap request membawa tiga header dan harus ditandatangani dengan **HMAC-SHA256**.

    | Header | Isi |
    |---|---|
    | `X-DEALER-ID` | API key dealer |
    | `X-TIMESTAMP` | Waktu sekarang dalam **detik Unix** (integer). Selisih maksimal ±5 menit dari waktu server |
    | `X-SIGNATURE` | Hex huruf kecil dari HMAC-SHA256 (rumus di bawah) |

    ```
    stringToSign = METHOD + ":" + PATH + ":" + TIMESTAMP + ":" + BODY_HASH
    key          = SHA256(apiSecret)                // 32 byte mentah, BUKAN teks hex
    signature    = HEX( HMAC_SHA256(key, stringToSign) )
    ```

    - `METHOD` huruf besar. `PATH` tanpa domain dan **tanpa query string**, misalnya
      `/api/v1/dealer/orders`.
    - `BODY_HASH` adalah `SHA256hex(body)` untuk request ber-body, dan **string kosong** untuk `GET`.
    - Body dihitung dari **JSON ringkas** (tanpa spasi). Kirim body persis sama dengan yang
      kamu hash, dengan urutan key yang sama.

    Contoh Node.js:

    ```js
    const crypto = require('crypto');
    const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');

    function headers(apiKey, apiSecret, method, path, bodyStr) {
      const ts = Math.floor(Date.now() / 1000);
      const toSign = `${method}:${path}:${ts}:${bodyStr ? sha(bodyStr) : ''}`;
      const key = crypto.createHash('sha256').update(apiSecret).digest();
      return {
        'Content-Type': 'application/json',
        'X-DEALER-ID': apiKey,
        'X-TIMESTAMP': String(ts),
        'X-SIGNATURE': crypto.createHmac('sha256', key).update(toSign).digest('hex'),
      };
    }
    ```

    Contoh Python (pakai `separators` dan `ensure_ascii=False` supaya body sama dengan yang di-hash):

    ```python
    import hashlib, hmac, json, time

    def headers(api_key, secret, method, path, body_str=""):
        ts = str(int(time.time()))
        body_hash = hashlib.sha256(body_str.encode()).hexdigest() if body_str else ""
        key = hashlib.sha256(secret.encode()).digest()
        sig = hmac.new(key, f"{method}:{path}:{ts}:{body_hash}".encode(), hashlib.sha256).hexdigest()
        return {"Content-Type": "application/json", "X-DEALER-ID": api_key,
                "X-TIMESTAMP": ts, "X-SIGNATURE": sig}

    body = json.dumps({"dealerReferenceNo": "INV-0001", "productId": "pulsa-telkomsel-10k",
                       "customerNo": "081234567890"}, separators=(",", ":"), ensure_ascii=False)
    ```

    Contoh PHP:

    ```php
    function dealerHeaders($apiKey, $secret, $method, $path, $body = '') {
      $ts = (string) time();
      $toSign = "$method:$path:$ts:" . ($body !== '' ? hash('sha256', $body) : '');
      $key = hash('sha256', $secret, true);
      return ["Content-Type: application/json", "X-DEALER-ID: $apiKey", "X-TIMESTAMP: $ts",
              "X-SIGNATURE: " . hash_hmac('sha256', $toSign, $key)];
    }
    // json_encode(..., JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
    ```

    Signature salah, timestamp kedaluwarsa, atau API key tidak dikenal menghasilkan `401`.
    Akun yang ditangguhkan menghasilkan `403`.

    ## Konvensi
    - Key JSON memakai `camelCase`. Request dan respons berformat JSON.
    - Semua nominal dalam **Rupiah, bilangan bulat** (bukan sen), `currency` selalu `IDR`.
    - Waktu berformat ISO 8601 UTC, misalnya `2026-11-19T08:00:03.000Z`.
    - Batas **60 request per menit** per dealer.
    - Respons sukses langsung berisi data. Respons gagal selalu berbentuk:

    ```json
    { "error": "Saldo deposit dealer tidak cukup", "code": "INSUFFICIENT_BALANCE" }
    ```

    ## Status order
    | `status` | Arti |
    |---|---|
    | `PAID` | Saldo terpotong dan order diterima, belum diproses |
    | `PROCESSING` | Sedang diproses provider. **Belum final**, tunggu callback atau cek berkala |
    | `COMPLETED` | Sukses. `sn` berisi serial number atau token bila ada |
    | `FAILED` | Gagal. Saldo dikembalikan penuh secara otomatis |

    ## Idempotensi dan timeout
    `dealerReferenceNo` adalah kunci idempotensi per dealer. Mengirim ulang nilai yang sama
    mengembalikan order lama dengan `duplicate: true` dan **tidak memotong saldo lagi**.
    Kalau request timeout atau koneksi putus, **jangan membuat order baru**: kirim ulang
    dengan `dealerReferenceNo` yang sama, atau cek lewat `GET /api/v1/dealer/orders/{orderId}`.

    ## Callback
    Saat order mencapai `COMPLETED` atau `FAILED`, kami mengirim `POST` bertanda tangan ke
    URL callback-mu (lihat **Callback order** di bawah). Balas `2xx` bila diterima. Selain itu
    kami mengulang sampai 5 kali dengan jeda 5, 15, 30, 60, dan 120 detik. Callback bisa
    terkirim lebih dari sekali, jadi proses secara idempoten memakai `orderId`. Kegagalan
    callback tidak mengubah status order. Di production, URL wajib `https` dengan host publik.

    ## Kode error
    | HTTP | `code` | Penyebab |
    |---|---|---|
    | 400 | `VALIDATION_ERROR` | Field kurang atau format nomor tujuan salah |
    | 400 | `PRODUCT_NOT_FOUND` | `productId` tidak ada |
    | 401 | `UNAUTHORIZED` | Header kurang, API key tidak dikenal, signature salah, atau timestamp kedaluwarsa |
    | 402 | `INSUFFICIENT_BALANCE` | Saldo kurang. Respons memuat `balance` dan `required` |
    | 403 | `DEALER_SUSPENDED` | Akun ditangguhkan |
    | 404 | `NOT_FOUND` | Order tidak ditemukan |
    | 429 | `RATE_LIMITED` | Lebih dari 60 request per menit |

servers:
  - url: https://nadipay.getnadi.id
    description: Production
  - url: https://sandbox.getnadi.id
    description: Sandbox (uji integrasi, tanpa uang asli)

security:
  - dealerId: []
    timestamp: []
    signature: []

tags:
  - name: Produk dan saldo
    description: Lihat katalog beserta harga jualmu dan cek saldo deposit.
  - name: Order
    description: |
      Buat order dan pantau statusnya. Order dibuat dengan memotong saldo deposit dan langsung
      diteruskan ke provider.
  - name: Top up saldo DANA
    description: |
      Kirim saldo ke akun DANA pengguna akhir. Deposit dipotong **nominal + fee**. Bila gagal,
      seluruh potongan dikembalikan. Fitur ini aktif per akun (hubungi Nadipay).

      Di **sandbox**, hasil ditentukan akhiran nomor tujuan: `...9999` gagal, `...8888` pending
      (saldo tertahan), selain itu sukses.
  - name: Sandbox
    description: Hanya ada di `https://sandbox.getnadi.id`.

paths:
  /api/v1/dealer/products:
    get:
      tags: [Produk dan saldo]
      operationId: listProducts
      summary: Daftar produk
      description: |
        Katalog beserta **harga jual untukmu**. Bila kamu punya harga khusus, harga itu yang
        tampil. Gunakan `id` sebagai `productId` saat membuat order.
      responses:
        '200':
          description: Daftar produk.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProductList' }
              example:
                currency: IDR
                products:
                  - id: pulsa-telkomsel-10k
                    name: Pulsa Telkomsel 10.000
                    category: Pulsa
                    price: 11000
                    targetLabel: Nomor HP tujuan
                    targetPlaceholder: 0812xxxxxxx
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Suspended' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /api/v1/dealer/balance:
    get:
      tags: [Produk dan saldo]
      operationId: getBalance
      summary: Cek saldo
      description: Saldo deposit dealer saat ini, dalam Rupiah.
      responses:
        '200':
          description: Saldo.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Balance' }
              example: { dealerId: DLR-MWNBP0OG1GLO, name: Toko Maju, balance: 250000, currency: IDR }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Suspended' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /api/v1/dealer/orders:
    post:
      tags: [Order]
      operationId: createOrder
      summary: Buat order
      description: |
        Memotong saldo sebesar harga jualmu, lalu meneruskan order ke provider. Respons
        berisi status terkini. Bila `PROCESSING`, tunggu callback atau cek berkala.

        Mengirim ulang `dealerReferenceNo` yang sama mengembalikan order lama (`200`,
        `duplicate: true`) tanpa memotong saldo lagi.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateOrderRequest' }
            example:
              dealerReferenceNo: INV-0001
              productId: pulsa-telkomsel-10k
              customerNo: '081234567890'
      responses:
        '201':
          description: Order dibuat.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderResponse' }
              examples:
                completed:
                  summary: Sukses
                  value:
                    duplicate: false
                    order:
                      orderId: ORD-MWNBP3LVGNB1
                      dealerReferenceNo: INV-0001
                      productId: pulsa-telkomsel-10k
                      productName: Pulsa Telkomsel 10.000
                      customerNo: '081234567890'
                      amount: 11000
                      status: COMPLETED
                      fulfillmentStatus: SUCCESS
                      sn: '1234567890'
                      createdAt: '2026-11-19T08:00:00.000Z'
                      updatedAt: '2026-11-19T08:00:03.000Z'
                      callback: { attempts: 0, delivered: false, lastStatus: null }
                    balance: 239000
                processing:
                  summary: Masih diproses
                  value:
                    duplicate: false
                    order:
                      orderId: ORD-MWNBP3LVGNB2
                      dealerReferenceNo: INV-0002
                      productId: pulsa-telkomsel-10k
                      productName: Pulsa Telkomsel 10.000
                      customerNo: '081234567890'
                      amount: 11000
                      status: PROCESSING
                      fulfillmentStatus: PENDING
                      sn: null
                      createdAt: '2026-11-19T08:05:00.000Z'
                      updatedAt: '2026-11-19T08:05:01.000Z'
                      callback: { attempts: 0, delivered: false, lastStatus: null }
                    balance: 228000
        '200':
          description: '`dealerReferenceNo` sudah pernah dipakai. Mengembalikan order lama dengan `duplicate: true`. Saldo tidak dipotong.'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderResponse' }
        '400':
          description: Field kurang, format nomor tujuan salah, atau produk tidak ditemukan.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              examples:
                validation:
                  value: { error: 'Nomor HP tujuan tidak valid (contoh: 0812xxxxxxx)', code: VALIDATION_ERROR }
                product:
                  value: { error: Produk tidak ditemukan, code: PRODUCT_NOT_FOUND, productId: xxx }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Saldo deposit kurang. Isi deposit dulu.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example:
                error: 'Saldo deposit dealer tidak cukup (saldo Rp5.000, butuh Rp11.000) — isi deposit dulu'
                code: INSUFFICIENT_BALANCE
                balance: 5000
                required: 11000
        '403': { $ref: '#/components/responses/Suspended' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /api/v1/dealer/orders/{orderId}:
    get:
      tags: [Order]
      operationId: getOrder
      summary: Cek order
      description: |
        Status terkini sebuah order. Kamu hanya bisa melihat order milikmu; order dealer lain
        atau yang tidak ada menghasilkan `404`.
      parameters:
        - name: orderId
          in: path
          required: true
          description: '`orderId` dari respons buat order.'
          schema: { type: string }
          example: ORD-MWNBP3LVGNB1
      responses:
        '200':
          description: Order ditemukan.
          content:
            application/json:
              schema:
                type: object
                required: [order]
                properties:
                  order: { $ref: '#/components/schemas/Order' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Suspended' }
        '404':
          description: Order tidak ditemukan.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example: { error: Order tidak ditemukan, code: NOT_FOUND }
        '429': { $ref: '#/components/responses/RateLimited' }

  /api/v1/dealer/topups:
    post:
      tags: [Top up saldo DANA]
      operationId: createTopup
      summary: Buat top up
      description: |
        Memotong deposit sebesar `amount` + `fee`, lalu mengirim saldo ke akun DANA tujuan.

        - `customerNumber` boleh `08...`, `+62...`, atau `62...`; kami menormalkan ke `62...`.
        - `amount` bilangan bulat Rupiah, 1.000 sampai 20.000.000.
        - `COMPLETED`: saldo sudah masuk. `FAILED`: potongan dikembalikan penuh. `PENDING`:
          menunggu konfirmasi, **saldo tetap tertahan**; cek dengan `GET /api/v1/dealer/topups/{topupId}`.
        - `dealerReferenceNo` adalah kunci idempotensi, sama seperti order. Kirim ulang dengan
          nilai yang sama bila timeout; jangan membuat top up baru.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateTopupRequest' }
            example:
              dealerReferenceNo: TOPUP-0001
              customerNumber: '081234567890'
              amount: 100000
      responses:
        '201':
          description: Top up dibuat.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TopupResponse' }
              example:
                duplicate: false
                topup:
                  topupId: TUP-MWNBP3LVGNB1
                  dealerReferenceNo: TOPUP-0001
                  customerNumber: '6281234567890'
                  amount: 100000
                  fee: 350
                  total: 100350
                  status: COMPLETED
                  createdAt: '2026-11-19T08:00:00.000Z'
                  updatedAt: '2026-11-19T08:00:02.000Z'
                balance: 899650
        '200':
          description: '`dealerReferenceNo` sudah pernah dipakai. Mengembalikan top up lama. Saldo tidak dipotong lagi.'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TopupResponse' }
        '400':
          description: Field kurang atau format salah.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example: { error: 'customerNumber tidak valid (nomor DANA pengguna, mis. 081234567890)', code: VALIDATION_ERROR }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Saldo deposit kurang untuk `amount` + `fee`.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example: { error: 'Saldo deposit tidak cukup (saldo Rp5.000, butuh Rp100.350) — isi deposit dulu', code: INSUFFICIENT_BALANCE }
        '403':
          description: Akun ditangguhkan, atau top up belum diaktifkan untuk akunmu (`TOPUP_DISABLED`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /api/v1/dealer/topups/{topupId}:
    get:
      tags: [Top up saldo DANA]
      operationId: getTopup
      summary: Cek top up
      description: |
        Status terkini sebuah top up milikmu. Untuk status `PENDING`, kami menanyakan hasil
        terbaru ke DANA sebelum menjawab. Top up milik dealer lain menghasilkan `404`.
      parameters:
        - name: topupId
          in: path
          required: true
          schema: { type: string }
          example: TUP-MWNBP3LVGNB1
      responses:
        '200':
          description: Top up ditemukan.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TopupResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Suspended' }
        '404':
          description: Top up tidak ditemukan.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
              example: { error: Top up tidak ditemukan, code: NOT_FOUND }
        '429': { $ref: '#/components/responses/RateLimited' }

  /api/sandbox/register:
    post:
      tags: [Sandbox]
      operationId: sandboxRegister
      summary: Daftar akun sandbox
      description: |
        Membuat akun uji dan langsung mengembalikan kredensial. **Tanpa signature.**
        `apiSecret` dan `portalPassword` hanya tampil sekali. Batas 5 pendaftaran per jam per alamat IP.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, maxLength: 80, example: PT Contoh Partner }
                callbackUrl: { type: string, format: uri, description: Opsional. Wajib https dengan host publik., example: 'https://contoh.com/nadipay/callback' }
      responses:
        '201':
          description: Akun sandbox dibuat dengan saldo Rp1.000.000.
          content:
            application/json:
              schema:
                type: object
                properties:
                  dealerId: { type: string, description: Dipakai sebagai `X-DEALER-ID`., example: dlr_0123456789abcdef0123456789abcdef }
                  apiSecret: { type: string }
                  portalPassword: { type: string }
                  balance: { type: integer, example: 1000000 }
                  note: { type: string }
        '400':
          description: Nama kosong atau URL callback ditolak.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429':
          description: Terlalu banyak pendaftaran dari alamat ini.

  /api/sandbox/deposit:
    post:
      tags: [Sandbox]
      operationId: sandboxDeposit
      summary: Isi ulang saldo uji
      description: Menambah saldo uji sebesar `amount` (maksimal Rp5.000.000 per panggilan). Ditandatangani seperti endpoint dealer lain.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                amount: { type: integer, minimum: 1, maximum: 5000000, example: 500000 }
      responses:
        '200':
          description: Saldo bertambah.
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance: { type: integer }
                  currency: { type: string, example: IDR }
        '400':
          description: '`amount` tidak valid.'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '401': { $ref: '#/components/responses/Unauthorized' }

webhooks:
  orderCallback:
    post:
      tags: [Order]
      operationId: orderCallback
      summary: Callback order
      description: |
        Kami mengirim request ini ke **URL callback dealer** saat order mencapai `COMPLETED`
        atau `FAILED`.

        Header-nya sama dengan request biasa (`X-DEALER-ID`, `X-TIMESTAMP`, `X-SIGNATURE`),
        dihitung dengan API secret-mu dan rumus yang sama. `PATH` adalah path URL callback-mu.
        **Verifikasi signature sebelum memercayai isinya.**

        Balas `2xx` bila diterima. Selain itu kami mengulang sampai 5 kali.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CallbackPayload' }
            example:
              dealerReferenceNo: INV-0001
              orderId: ORD-MWNBP3LVGNB1
              productId: pulsa-telkomsel-10k
              customerNo: '081234567890'
              status: COMPLETED
              sn: '1234567890'
              sellPrice: 11000
              completedAt: '2026-11-19T08:00:03.000Z'
      responses:
        '200':
          description: Diterima. Status 2xx apa pun menghentikan pengulangan.

components:
  securitySchemes:
    dealerId:
      type: apiKey
      in: header
      name: X-DEALER-ID
      description: API key dealer (`dlr_...`).
    timestamp:
      type: apiKey
      in: header
      name: X-TIMESTAMP
      description: Detik Unix saat ini. Toleransi ±5 menit.
    signature:
      type: apiKey
      in: header
      name: X-SIGNATURE
      description: 'Hex HMAC-SHA256. Lihat bagian **Autentikasi dan signature**.'

  responses:
    Unauthorized:
      description: Header kurang, API key tidak dikenal, signature salah, atau timestamp kedaluwarsa.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { error: 'Unauthorized: X-SIGNATURE tidak cocok', code: UNAUTHORIZED }
    Suspended:
      description: Akun dealer ditangguhkan.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { error: Dealer berstatus suspended, code: DEALER_SUSPENDED }
    RateLimited:
      description: Lebih dari 60 request per menit.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { error: 'Terlalu banyak request dealer, coba lagi sebentar', code: RATE_LIMITED }

  schemas:
    CreateTopupRequest:
      type: object
      required: [dealerReferenceNo, customerNumber, amount]
      properties:
        dealerReferenceNo: { type: string, description: Kunci idempotensi milikmu. Unik per dealer., example: TOPUP-0001 }
        customerNumber: { type: string, description: 'Nomor DANA tujuan. `08...`, `+62...`, atau `62...`.', example: '081234567890' }
        amount: { type: integer, minimum: 1000, maximum: 20000000, description: Nominal yang diterima pengguna (Rupiah)., example: 100000 }
    Topup:
      type: object
      properties:
        topupId: { type: string, example: TUP-MWNBP3LVGNB1 }
        dealerReferenceNo: { type: string }
        customerNumber: { type: string, description: Dinormalkan ke format `62...`., example: '6281234567890' }
        amount: { type: integer, description: Nominal ke pengguna., example: 100000 }
        fee: { type: integer, description: Biaya layanan untukmu., example: 350 }
        total: { type: integer, description: Total potongan deposit (`amount` + `fee`)., example: 100350 }
        status: { type: string, enum: [PROCESSING, PENDING, COMPLETED, FAILED], description: '`FAILED` = potongan sudah dikembalikan penuh. `PENDING` = saldo tertahan sampai ada kepastian.' }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    TopupResponse:
      type: object
      required: [topup]
      properties:
        duplicate: { type: boolean }
        topup: { $ref: '#/components/schemas/Topup' }
        balance: { type: integer, description: Saldo deposit setelah transaksi. }
    Error:
      type: object
      required: [error, code]
      properties:
        error: { type: string, description: Pesan untuk manusia. Bisa berubah, jangan dipakai untuk logika. }
        code:
          type: string
          description: Kode yang stabil untuk logika program.
          enum: [VALIDATION_ERROR, PRODUCT_NOT_FOUND, UNAUTHORIZED, INSUFFICIENT_BALANCE, DEALER_SUSPENDED, NOT_FOUND, RATE_LIMITED, TOPUP_DISABLED, INTERNAL_ERROR]
        balance: { type: integer, description: 'Hanya pada `INSUFFICIENT_BALANCE`: saldo saat ini.' }
        required: { type: integer, description: 'Hanya pada `INSUFFICIENT_BALANCE`: saldo yang dibutuhkan.' }

    Product:
      type: object
      required: [id, name, category, price]
      properties:
        id: { type: string, description: Dipakai sebagai `productId`., example: pulsa-telkomsel-10k }
        name: { type: string, example: Pulsa Telkomsel 10.000 }
        category: { type: string, example: Pulsa }
        price: { type: integer, description: Harga jual untukmu, Rupiah., example: 11000 }
        targetLabel: { type: [string, 'null'], description: Nama isian tujuan., example: Nomor HP tujuan }
        targetPlaceholder: { type: [string, 'null'], example: 0812xxxxxxx }

    ProductList:
      type: object
      required: [currency, products]
      properties:
        currency: { type: string, example: IDR }
        products:
          type: array
          items: { $ref: '#/components/schemas/Product' }

    Balance:
      type: object
      required: [dealerId, name, balance, currency]
      properties:
        dealerId: { type: string }
        name: { type: string }
        balance: { type: integer, description: Rupiah. }
        currency: { type: string, example: IDR }

    CreateOrderRequest:
      type: object
      required: [dealerReferenceNo, productId, customerNo]
      properties:
        dealerReferenceNo:
          type: string
          description: ID unik dari sistemmu untuk order ini. **Kunci idempotensi.**
          example: INV-0001
        productId: { type: string, description: '`id` dari daftar produk.', example: pulsa-telkomsel-10k }
        customerNo:
          type: string
          description: Nomor tujuan (nomor HP atau ID pelanggan). Formatnya divalidasi sesuai produk.
          example: '081234567890'

    Order:
      type: object
      required: [orderId, productId, customerNo, amount, status]
      properties:
        orderId: { type: string, description: ID order dari Nadipay. }
        dealerReferenceNo: { type: [string, 'null'] }
        productId: { type: string }
        productName: { type: string }
        customerNo: { type: string }
        amount: { type: integer, description: Harga jual yang dipotong dari saldo, Rupiah. }
        status:
          type: string
          enum: [PAID, PROCESSING, COMPLETED, FAILED]
          description: '`PAID` dan `PROCESSING` belum final. `COMPLETED` dan `FAILED` final.'
        fulfillmentStatus: { type: [string, 'null'], description: Status dari sisi provider, hanya informasi. }
        sn: { type: [string, 'null'], description: Serial number atau token, bila ada. }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        callback:
          type: object
          description: Status pengiriman callback untuk order ini.
          properties:
            attempts: { type: integer }
            delivered: { type: boolean }
            lastStatus: { description: 'Kode HTTP terakhir, atau teks seperti `no-callback-url`.' }

    OrderResponse:
      type: object
      required: [duplicate, order, balance]
      properties:
        duplicate: { type: boolean, description: '`true` bila `dealerReferenceNo` sudah pernah dipakai.' }
        order: { $ref: '#/components/schemas/Order' }
        balance: { type: integer, description: Saldo setelah order, Rupiah. }

    CallbackPayload:
      type: object
      required: [orderId, status]
      properties:
        dealerReferenceNo: { type: [string, 'null'] }
        orderId: { type: string }
        productId: { type: string }
        customerNo: { type: string }
        status: { type: string, enum: [COMPLETED, FAILED] }
        sn: { type: [string, 'null'] }
        sellPrice: { type: integer, description: Rupiah. }
        completedAt: { type: string, format: date-time }
