Dokumentasi API

Ringkasan

Gateway ini menjembatani toko Anda dengan ShopeePay Partner API. Ada tiga tugas utama: membuat QRIS dinamis dari nominal, memantau transaksi masuk, dan memberi tahu toko ketika pembayaran terverifikasi.

Ringkasan endpoint

Quick start

Butuh Bun 1.1 atau lebih baru. State pembayaran aktif disimpan di memori proses, sedangkan riwayat transaksi untuk dashboard ditulis ke SQLite lokal secara otomatis.

bun install
cp .env.example .env
# isi API_KEY, SHOPEE_TOKEN, dan QRIS_STATIC
bun run dev

Environment minimal

PORT=3001
API_KEY=minimal-32-karakter-acak
SHOPEE_TOKEN=B:token-dari-partner-portal
QRIS_STATIC=000201010211...

API_KEY minimal 32 karakter. Generate dengan openssl rand -hex 32. Token Shopee diambil dari Partner Portal: DevTools → Network → request get-transaction-list → data.metadata.token.

Cek gateway

curl http://localhost:3001/api/health

{
  "success": true,
  "message": "ShopeePay API Service is running",
  "timestamp": "2026-10-31T12:00:00.000Z"
}

Halaman ini tersedia di /docs. Endpoint API yang dilindungi memerlukan header X-API-Key.

Autentikasi

Semua endpoint sensitif memakai header X-API-Key. API key pada query string tidak diterima.

curl http://localhost:3001/transactions \
  -H "X-API-Key: $API_KEY"

Multi-store

Jika Anda mengelola beberapa merchant, kirim token Shopee per request melalui header X-Shopee-Token. Tanpa header ini, gateway memakai token default dari SHOPEE_TOKEN atau hasil POST /update-token.

curl http://localhost:3001/token-status \
  -H "X-API-Key: $API_KEY" \
  -H "X-Shopee-Token: B:token-merchant-lain"

POST /create-qris

Membuat QRIS dinamis. Gateway memilih suffix terendah yang belum dipakai untuk nominal dasar tersebut, lalu menyisipkan nominal final ke payload QRIS.

Request

curl -X POST http://localhost:3001/create-qris \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "order_id": "ORD-2026-00123",
    "webhook_url": "https://shop.example.com/payments/webhook"
  }'

Response

{
  "success": true,
  "data": {
    "qris": "00020101021226...6304A1B2",
    "amount": 50017,
    "order_id": "ORD-2026-00123",
    "start_time": 1761912000,
    "expires_at": "2026-10-31T12:15:00.000Z",
    "expires_in_seconds": 900,
    "poll_interval_seconds": 7,
    "webhook_enabled": true
  }
}

Render QR

Gateway hanya mengembalikan string QRIS. Gambar QR dibuat oleh client, misalnya dengan library qrcode.

import QRCode from "qrcode";

await QRCode.toCanvas(canvasElement, data.qris);

POST /check-payment

Membaca status pembayaran dari store in-memory. Verifikasi transaksi tetap dilakukan oleh poller; endpoint ini tidak memanggil Shopee secara langsung.

curl -X POST http://localhost:3001/check-payment \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50017}'

Gunakan nominal final dari /create-qris. Response saat belum lunas:

{
  "success": true,
  "paid": false
}

Response saat sudah lunas:

{
  "success": true,
  "paid": true,
  "transaction": {
    "transactionId": "TX123",
    "amount": 50017,
    "status": "success",
    "time": "2026-10-31 19:00:05",
    "issuer": "Seabank"
  }
}

POST /cancel

Membatalkan pembayaran yang masih pending. Setelah dibatalkan, poller berhenti mengecek transaksi tersebut ke Shopee dan tidak akan mengirim webhook payment.paid. Gunakan nominal final dari /create-qris.

curl -X POST http://localhost:3001/cancel \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50017, "order_id": "ORD-2026-00123"}'

{
  "success": true,
  "data": {
    "amount": 50017,
    "order_id": "ORD-2026-00123",
    "status": "cancelled",
    "already_cancelled": false
  }
}

Transaksi

Dua endpoint untuk melihat transaksi langsung dari Shopee. Keduanya menerima X-Shopee-Token opsional.

curl http://localhost:3001/transactions \
  -H "X-API-Key: $API_KEY"

{
  "success": true,
  "total_amount": "150.017",
  "data": {
    "transactions": [
      {
        "transactionId": "TX123",
        "amount": 50017,
        "status": "success",
        "time": "2026-10-31 19:00:05"
      }
    ]
  }
}

Jika token kedaluwarsa, response 401 menyertakan instruksi untuk memanggil POST /update-token. Error upstream lain dikembalikan sebagai 502.

Token

Token Shopee disimpan di memori. Setelah restart, gateway kembali memakai nilai SHOPEE_TOKEN dari environment.

GET /token-status

curl http://localhost:3001/token-status \
  -H "X-API-Key: $API_KEY"

{
  "success": true,
  "data": {
    "token_status": "valid",
    "message": "Token is working"
  }
}

POST /update-token

curl -X POST http://localhost:3001/update-token \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "B:token-baru"}'

Token divalidasi sebelum disimpan. Jika validasi tidak memungkinkan, tambahkan "skipValidation": true untuk memaksa update.

Log

GET /api/logs mengembalikan ring buffer log in-memory. Secret seperti API key dan token disamarkan sebelum ditampilkan.

curl http://localhost:3001/api/logs \
  -H "X-API-Key: $API_KEY"

{
  "success": true,
  "data": {
    "logs": [
      {
        "level": "info",
        "message": "QRIS created for base Rp 50000 -> final Rp 50017 (suffix +17)",
        "timestamp": "2026-10-31T12:00:00.000Z"
      }
    ]
  }
}

Dashboard

GET /dashboard menyajikan dashboard transaksi read-only. Shell HTML-nya publik dan tidak memuat data; Anda memasukkan API_KEY sekali, lalu key disimpan di sessionStorage tab tersebut dan dikirim lewat header X-API-Key. Key tidak pernah masuk URL atau query string.

Dashboard membaca ledger SQLite yang ditulis gateway saat QRIS dibuat, dibatalkan, atau lunas. Store pembayaran aktif tetap in-memory; ledger inilah yang bertahan setelah restart dan mengisi grafik 7/30/90 hari.

Rentang yang didukung: 24h, 7d (default), 30d, dan 90d. Tanggal grafik dikelompokkan memakai zona Jakarta (UTC+7). Total KPI mengikuti rentang yang dipilih; pending adalah snapshot saat ini untuk QRIS yang masih dalam TTL, dan breakdown status mencerminkan seluruh ledger.

curl "http://localhost:3001/api/dashboard/overview?range=7d" \
  -H "X-API-Key: $API_KEY"

curl "http://localhost:3001/api/dashboard/payments?status=paid&limit=50" \
  -H "X-API-Key: $API_KEY"

overview mengembalikan total KPI (paid_count, paid_amount, pending_count, pending_amount, cancelled_count, expired_count, created_count, success_rate, average_ticket), series harian, status_breakdown, dan issuers.

payments mengembalikan maksimum 200 baris (default 50), terbaru lebih dulu, dengan next_cursor. Filter yang tersedia: status, range, q (mencari order_id atau transaction_id), limit, dan cursor.

{
  "success": true,
  "data": {
    "payments": [
      {
        "id": 42,
        "order_id": "ORD-2026-00123",
        "base_amount": 50000,
        "suffix": 17,
        "final_amount": 50017,
        "status": "paid",
        "created_at": 1793491200,
        "expires_at": 1793492100,
        "paid_at": 1793491260,
        "transaction_id": "TX123",
        "issuer": "Seabank"
      }
    ],
    "next_cursor": "40"
  }
}

Webhook payment.paid

Webhook dikirim satu kali ketika poller memverifikasi pembayaran dan markPaid() berhasil. Client tidak perlu memanggil /check-payment untuk memicu webhook.

Kapan dikirim

• Transaksi dari Shopee berstatus sukses dan nominalnya cocok dengan record pending.
• Record belum pernah berstatus paid.
• Pengiriman berjalan asynchronous, jadi tidak memperlambat siklus polling.

Tujuan pengiriman

Environment webhook

Payload

{
  "event": "payment.paid",
  "event_id": "0f1c2d3e-4b5a-4c6d-8e9f-123456789abc",
  "created_at": "2026-10-31T12:00:05.000Z",
  "data": {
    "order_id": "ORD-2026-00123",
    "amount": 50017,
    "base_amount": 50000,
    "suffix": 17,
    "status": "paid",
    "paid_at": "2026-10-31T12:00:05.000Z",
    "transaction": {
      "transactionId": "TX123",
      "amount": 50017,
      "status": "success",
      "time": "2026-10-31 19:00:05",
      "issuer": "Seabank"
    }
  }
}

Header & signature

Signature adalah HMAC-SHA256 dari timestamp + "." + rawBody. Verifikasi memakai raw body persis seperti yang diterima, bukan hasil parse lalu stringify ulang.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const received = (headers["x-webhook-signature"] || "").replace(/^sha256=/, "");
  const expected = createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;

  return (
    fresh &&
    received.length === expected.length &&
    timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
}

Retry, idempotensi, keamanan

Semantik pengiriman adalah at-least-once. Jika endpoint Anda sudah memproses event tetapi response gagal diterima gateway, event yang sama bisa dikirim lagi. Karena itu, selalu deduplikasi.

Checklist integrasi

1. Verifikasi signature sebelum memproses payload.
2. Balas 2xx secepat mungkin; proses bisnis boleh dilakukan setelah response.
3. Deduplikasi berdasarkan event_id atau transactionId.
4. Cocokkan order_id dan nominal dengan order di database.
5. Sediakan jalur rekonsiliasi manual atau polling.

Konfigurasi

Semua konfigurasi dibaca dari environment saat proses start. Lihat .env.example untuk daftar lengkap.

Error & limit

Batas body request adalah 16 KB. Rate limit default 60 request per 60 detik.

Checklist produksi

1. Pasang TLS di reverse proxy; jangan ekspos gateway tanpa HTTPS.
2. Gunakan API_KEY acak minimal 32 karakter dan rotasi secara berkala.
3. Set TRUST_PROXY=1 hanya di belakang proxy yang Anda kendalikan.
4. Batasi CORS_ORIGINS ke domain toko yang benar-benar dipakai.
5. Isi WEBHOOK_SECRET dan aktifkan WEBHOOK_ALLOWED_HOSTS untuk URL per order.
6. Simpan transactionId dan event_id unik di database toko.
7. Sediakan rekonsiliasi lewat /check-payment atau laporan transaksi.
8. Pantau /api/health, /api/logs, dan peringatan Telegram.
9. Pahami bahwa ini gateway tidak resmi dan dapat terpengaruh perubahan API Shopee.