# SYNX Pay API

> Panduan uji Sandbox dan penerbitan QRIS Live. Setiap respons invoice memuat livemode dan rincian harga, kode unik serta biaya.

## Kredensial

- Base URL: https://synxpay.id
- Login sebagai member yang disetujui dan buka Panel member → Integrasi & API.
- Buat API key uji. Simpan nilai lengkap sebagai `SYNX_SANDBOX_API_KEY` di lingkungan server atau agen yang menjalankan tes.
- Kirim `Authorization: Bearer $SYNX_SANDBOX_API_KEY`. Alternatifnya gunakan header `X-Api-Key`.
- Satu key aktif per member. Key baru menggantikan key sebelumnya.

## Mulai cepat

Contoh membuat tagihan uji dengan cURL:
```bash
curl -sS --fail-with-body -X POST https://synxpay.id/api/member/invoices \
  -H "Authorization: Bearer $SYNX_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: uji-pesanan-001" \
  -d '{"amount":1500,"reference":"UJI-001","expire_minutes":5}'
```

Contoh Node.js 22 untuk membuat tagihan, mensimulasikan lunas, dan memeriksa status:
```js
const base = process.env.SYNX_BASE_URL || "https://synxpay.id";
const key = process.env.SYNX_SANDBOX_API_KEY;
if (!key) throw new Error("Isi SYNX_SANDBOX_API_KEY");

async function api(path, method = "GET", body, extraHeaders = {}) {
  const response = await fetch(base + path, {
    method,
    headers: { Authorization: "Bearer " + key, "Content-Type": "application/json", ...extraHeaders },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(result.code || "HTTP " + response.status);
  return result;
}

async function testSandbox() {
  const invoices = "/api/member/invoices";
  const order = "AI-TEST-" + crypto.randomUUID();
  const amount = 1000 + Math.floor(Math.random() * 9_000_000);
  const { invoice } = await api(invoices, "POST", { amount, reference: order, expire_minutes: 5 }, {
    "Idempotency-Key": order,
  });
  if (invoice.amount !== invoice.base_amount + invoice.unique_code || invoice.net_amount !== invoice.amount - invoice.service_fee) throw new Error("Rincian nominal tidak cocok");
  await api(invoices + "/" + invoice.id + "/simulate", "POST", { action: "pay" });
  const settled = await api(invoices + "/" + invoice.id);
  if (settled.invoice.livemode || settled.invoice.status !== "paid") throw new Error("Simulasi belum lunas");
  console.log({ id: invoice.id, status: settled.invoice.status, checkout: base + invoice.pay_url });
}
testSandbox().catch(error => { console.error(error.message); process.exitCode = 1; });
```

## Endpoint

| Metode | Path | Kegunaan |
| --- | --- | --- |
| POST | `/api/member/invoices` | Buat tagihan Sandbox dari nominal dan referensi pesanan. |
| GET | `/api/member/invoices` | Daftar tagihan Sandbox milik akun. |
| GET | `/api/member/invoices/:id` | Ambil status dan tautan checkout untuk satu tagihan. |
| POST | `/api/member/invoices/:id/simulate` | Uji status lunas atau kedaluwarsa lewat action pay atau expire. |
| POST | `/api/member/invoices/:id/cancel` | Batalkan tagihan yang masih menunggu. |

### Buat tagihan

- Kirim `amount` sebagai harga barang dalam rupiah. Untuk kode unik otomatis, harga yang didukung Rp1–Rp9.999.800 dan total maksimal Rp10.000.000.
- Server memilih `unique_code` Rp200–Rp350 saat membuat tagihan. Ambil angka persis dari respons. Contoh harga Rp10.000 dan kode Rp203 menghasilkan nominal bayar Rp10.203.
- Tagihan baru menyimpan biaya toko 0,7% dari harga bila harga di atas Rp500.000, dibulatkan ke rupiah terdekat. Contoh harga Rp600.000 dan kode Rp201 menghasilkan total Rp600.201, biaya SYNX Pay Rp4.401, dan penerimaan simulasi Rp595.800.
- Integrasi lama yang mengirim `discount_limit` positif memilih potongan untuk pencocokan. Untuk memakai kode tambahan otomatis, hilangkan parameter itu atau isi 0.
- `reference` opsional sampai 100 karakter. `description` opsional sampai 200 karakter.
- `expire_minutes` opsional dari 1 sampai 60. Jika kosong, server memakai masa berlaku default.
- Gunakan `Idempotency-Key` dengan input yang sama saat mencoba ulang. Respons 201 berarti baru. Respons 200 berarti hasil permintaan sebelumnya.
- Respons berisi `invoice` dengan `id`, `base_amount` (harga), `unique_code`, `amount` (total bayar), `merchant_fee` (bagian biaya yang dibebankan ke toko), `service_fee` (kode + biaya toko), `net_amount` (total bayar dikurangi biaya layanan), `status`, `livemode`, `pay_url`, dan timestamp epoch milidetik.
- Gabungkan Base URL dengan `invoice.pay_url` untuk membuka checkout publik. QR Sandbox berisi data simulasi.

### Daftar, detail, dan simulasi

- Respons daftar berisi `invoices` dan `total`. Filter tersedia melalui `status`, `q`, `from`, `to`, `limit`, dan `offset`.
- Tanggal filter memakai format ISO 8601. `limit` dapat diisi 1–200.
- Status `pending` menjadi `paid` saat `{"action":"pay"}` diterima oleh endpoint simulasi. Gunakan `{"action":"expire"}` untuk `expired`.
- Pembatalan mengubah tagihan yang menunggu ke `cancelled`. Gunakan detail untuk memeriksa status terakhir.

## Tagihan QRIS Live

- Buat key Live dari tab Integrasi & API dan simpan sebagai `SYNX_LIVE_API_KEY`. Kirim `Authorization: Bearer $SYNX_LIVE_API_KEY`.
- Buat tagihan dengan `POST /api/member/live/invoices`. Contoh body `{"amount":10000,"reference":"ORDER-001","description":"Pesanan toko"}`.
- Live menambahkan kode unik Rp200–Rp350 otomatis. Pembeli membayar harga barang dan kode. Kode menjadi pendapatan gateway.
- Contoh respons dengan kode 203 memuat `base_amount=10000`, `unique_code=203`, `amount=10203`, `service_fee=203`, `net_amount=10000`, `livemode=true`. Angka kode dipilih server dan harus dibaca dari respons.
- Harga di atas Rp500.000 memiliki biaya toko 0,7% dari harga awal. Harga Rp600.000 dan kode Rp201 memberi total bayar Rp600.201, biaya Rp4.401 dan neto Rp595.800.
- Baca detail melalui `GET /api/member/live/invoices/:id`, daftar melalui `GET /api/member/live/invoices`, dan pembayaran lunas melalui `GET /api/member/live/payments`.
- Batalkan tagihan menunggu melalui `POST /api/member/live/invoices/:id/cancel`. Status lunas mengikuti mutasi GoPay.
- Server memesan total bayar secara atomik untuk seluruh member pada outlet. Bila semua total pada rentang kode dipakai, API mengembalikan `409 unique_code_unavailable`. Ulangi dengan jeda memakai Idempotency-Key dan input yang sama.
- Gunakan `invoice.amount` untuk checkout dan pencocokan webhook. Simpan referensi pesanan beserta ID invoice. Kode dan biaya dikunci ketika tagihan diterbitkan.
- Simpan URL dan secret webhook Live pada bagian Live di Integrasi. Verifikasi event Live dengan secret Live dan `livemode=true`. Cara verifikasi tanda tangan sama dengan contoh Sandbox di bawah.

## Webhook Sandbox

- Simpan URL HTTPS publik milikmu di tab Integrasi. URL dipakai pada tagihan baru. Bila mengisi `callback_url` atau `webhook_url` di request, gunakan URL Sandbox yang sama.
- Tombol **Kirim tes** mengirim event `webhook.test`. Hasil simulasi tagihan mengirim event `payment.success`, `payment.expired`, atau `payment.cancelled` bila URL aktif saat pembuatan.
- Verifikasi nilai hex `X-Webhook-Signature` dengan HMAC-SHA256 atas `X-Webhook-Timestamp + "." + rawBody` menggunakan secret Sandbox. Timestamp adalah detik Unix.
- Periksa umur timestamp, deduplikasi `X-Webhook-Id`, simpan event, lalu balas HTTP 2xx. Gunakan `livemode=false` untuk memproses event sebagai simulasi.
- Riwayat pengiriman tersedia di tab Integrasi. Ganti secret pada penerima setelah melakukan rotasi.

## Error dan batasan

| HTTP | Penanganan |
| --- | --- |
| 400 | Periksa format input, opsi simulasi, atau URL webhook yang terdaftar. |
| 401 | Periksa key Sandbox aktif dan header autentikasi. |
| 403 | Gunakan mode Sandbox dan akun member yang disetujui. |
| 404 | Periksa identitas tagihan milik akun. |
| 409 | Periksa status final atau konflik idempotensi. Bila semua kode untuk harga tersebut terpakai, tunggu atau gunakan harga uji lain. |
| 429 | Tunggu sebelum mengulangi permintaan. Perubahan tagihan dibatasi 30 per menit per akun. |
