Dokumentasi API untuk Developer

1. Kredensial API

Setiap request wajib menyertakan header berikut — nilai di bawah ini milik akun Anda setelah login:

Salin API Key Salin ID Merchant Salin Webhook Secret

Base URL

2. Create Transaction

Membuat QRIS dinamis dengan kode unik. Gunakan nilai total_amount dari response sebagai nominal yang wajib dibayar pelanggan.

Kode unik kecil per tier — nilai live dari GET /api/docs/meta.

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://pay.fncreative.org/api/qris/create',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
    "order_id": "INV-123",
    "amount": 10000,
    "keterangan": "Pembayaran Invoice #123"
  }',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'x-api-key: YOUR_API_KEY',
    'id_merchant: YOUR_MERCHANT_ID'
  ),
));

Response (201)

{
  "status": true,
  "code": "transaction_created",
  "message": "Transaction Created Successfully",
  "data": {
    "order_id": "INV-123",
    "amount": "10000.00",
    "base_amount": 10000,
    "unique_code": 45,
    "amount_uniq": "45.00",
    "total_amount": "10045.00",
    "status": "PENDING",
    "expired_at": "2026-06-13 16:05:01 WIB",
    "expired_menit": "5",
    "signature": "...",
    "keterangan": "Pembayaran Invoice #123",
    "qris_image": "data:image/png;base64,...",
    "qr_string": "00020101...",
    "customer_instruction": "Scan QRIS, bayar sesuai total sampai 3 digit terakhir, lalu tunggu status SUCCESS."
  }
}

3. Masa Berlaku QR & Kode Unik

Setiap transaksi QRIS dinamis memiliki batas waktu pembayaran. Nilai aktual platform saat ini (live dari GET /api/docs/meta):

Tampilan vs backend

• UI merchant menampilkan countdown ±5 menit (sesuai expired_menit di response create).
• Backend tetap memantau ±10 menit sejak QR dibuat untuk mencocokkan mutasi bank — customer yang bayar menit ke-6–10 setelah create masih bisa masuk saldo otomatis.
• Lewat toleransi backend → status tetap EXPIRED, uang terdeteksi masuk ke log Tidak Masuk Saldo — merchant bisa minta tinjauan atau admin kredit manual.

Alur merchant

1. Panggil POST /qris/create → tampilkan QR + total_amount + countdown dari expired_at.
2. Customer bayar dalam waktu aktif → webhook PAID atau polling GET /qris/status/{order_id} → SUCCESS.
3. Lewat waktu tanpa bayar → status EXPIRED → buat QR baru (disarankan order_id baru).

4. Webhook Callback

// Node.js contoh handler
app.post("/payment/callback", async (req, res) => {
  const { order_id, status, total_amount, payment_date, signature, delivery_id, signature_v2 } = req.body;
  if (await db.isOrderPaid(order_id)) {
    return res.status(200).json({ ok: true, duplicate: true });
  }
  const legacy = hmacLegacy(order_id, status, total_amount, payment_date);
  const v2 = delivery_id ? hmacV2(delivery_id, order_id, status, total_amount, payment_date) : null;
  if (signature !== legacy && (!v2 || signature_v2 !== v2)) {
    return res.status(401).json({ ok: false, error: "invalid_signature" });
  }
  if (status !== "PAID") return res.status(200).json({ ok: true, ignored: true });
  await db.markPaid(order_id);
  return res.status(200).json({ ok: true });
});

Server merchant harus merespon HTTP 200 OK. Callback dikirim saat pembayaran sukses — field status bernilai PAID (bukan SUCCESS seperti di API status/history).

Webhook PAID vs API SUCCESS

Validasi Signature

Secret webhook akun Anda: —

signature = HMAC_SHA256(
  YOUR_WEBHOOK_SECRET,
  order_id + "|" + status + "|" + total_amount + "|" + payment_date
)

{
  "order_id": "INV-123",
  "status": "PAID",
  "amount": 10000,
  "total_amount": 10045,
  "payment_date": "2026-06-01 21:48:01",
  "created_at": "2026-06-01 21:18:01 WIB",
  "updated_at": "2026-06-01 21:48:01",
  "keterangan": "Pembayaran Invoice #123",
  "direct_url": null,
  "signature": "..."
}

5. Check Status

Header sama seperti create: x-api-key + id_merchant. Status di response API: PENDING, SUCCESS, atau EXPIRED.

6. Transaction History

Header integrasi: x-api-key + id_merchant. Mendukung filter dan paginasi.

GET https://pay.fncreative.org/api/qris/history?page=1&per_page=30&status=SUCCESS&date_from=2026-06-01&date_to=2026-06-26
x-api-key: YOUR_API_KEY
id_merchant: YOUR_MERCHANT_ID

Response mencakup status_counts (jumlah per status), total_pages, dan array data berisi transaksi.

Export CSV

Query filter sama seperti history. Mengembalikan file CSV (maks. 5.000 baris) dengan kolom: order_id, created_at, base_amount, unique_code, total_amount, status, paid_at, expired_at, keterangan.

7. Ringkasan Harian

Menampilkan total transaksi sukses dan pendapatan per hari (zona Asia/Jakarta). Parameter date opsional — default hari ini.

8. Login & Dashboard

Dashboard web memakai session token (Bearer). API integrasi tetap memakai x-api-key.

{
  "email": "dev@tokoabc.com",
  "password": "password-anda"
}

Response berisi session_token. Kredensial API lihat via GET /merchants/me setelah login (bukan di body login).

Header: Authorization: Bearer <session_token>

9. Dompet & Penarikan

Fee platform: 1,2% dari total pembayaran (termasuk kode unik) per transaksi SUCCESS. Penarikan minimum Rp 25.000, maksimal 3 kali per hari (zona WIB).

Notifikasi Telegram & email merchant diatur lewat dashboard web. Admin platform tetap menerima alert operasional.

10. Pembayaran Tidak Masuk Saldo (Payment Issues)

Kasus di mana mutasi bank terdeteksi sistem tetapi tidak otomatis masuk saldo merchant. Biasanya terjadi karena customer transfer setelah QR EXPIRED di tampilan (±5 menit) dan melewati toleransi auto-match backend (±10 menit sejak QR dibuat).

Alur kasus

1. Sistem mendeteksi transfer masuk tetapi tidak bisa dicocokkan otomatis → kasus tercatat (needs_action: true).
2. Merchant melihat kasus di dashboard atau via GET /merchants/payment-issues.
3. Jika customer sudah bayar, merchant ajukan tinjauan → POST .../claim.
4. Tim FN CREATIVE memproses dari panel admin: kredit manual ke order atau tutup kasus (refund/ditutup).
5. Setelah selesai, merchant menerima notifikasi Telegram + Gmail (jika diaktifkan) dan riwayat tersedia di notification_history.

Jenis kasus (result)

Status penyelesaian (resolution_status)

Daftar kasus

GET https://pay.fncreative.org/api/merchants/payment-issues?page=1&per_page=20&include_resolved=1
Authorization: Bearer YOUR_SESSION_TOKEN

Response:

{
  "status": true,
  "data": {
    "current_page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1,
    "grace_minutes": 10,
    "display_expire_minutes": 5,
    "data": [
      {
        "id": 218,
        "amount": 237063,
        "created_at": "2026-06-26 20:15:42 WIB",
        "result": "no_match",
        "result_label": "Tidak cocok",
        "reason": "Tidak ada order PENDING yang cocok.",
        "recommendation": "Pembayaran terdeteksi tetapi tidak masuk saldo Anda — ...",
        "needs_action": false,
        "is_resolved": true,
        "resolution_status": "refunded",
        "resolution_label": "Sudah direfund",
        "resolution_note": "Sudah direfund ke merchant / tidak jadi kredit.",
        "resolved_at": "2026-06-26 20:22:15 WIB",
        "resolved_order_id": "",
        "merchant_claimed_at": "2026-06-26 20:18:00 WIB",
        "merchant_claim_note": "Customer transfer jam 20:14 WIB, Order ORDER-76250626114",
        "related_orders": [
          {
            "order_id": "ORDER-76250626114",
            "status": "EXPIRED",
            "base_amount": 237000,
            "unique_code": 63,
            "expected_amount": 237063,
            "total_amount": 237063,
            "created_at": "2026-06-26 20:05:12 WIB",
            "expired_at": "2026-06-26 20:10:12 WIB",
            "keterangan": "Topup saldo"
          }
        ],
        "notification_history": [
          {
            "id": 12,
            "log_id": 218,
            "audience": "merchant",
            "channel": "telegram",
            "event": "Pembayaran sudah direfund",
            "recipient_masked": "***8546",
            "status": "sent",
            "created_at": "2026-06-26 20:31:05 WIB"
          },
          {
            "id": 13,
            "log_id": 218,
            "audience": "merchant",
            "channel": "email",
            "event": "Pembayaran sudah direfund",
            "recipient_masked": "pi***@gmail.com",
            "status": "sent",
            "created_at": "2026-06-26 20:31:06 WIB"
          }
        ]
      }
    ]
  }
}

Field objek kasus

Field related_orders[]

Ajukan tinjauan (claim)

Merchant melaporkan bahwa customer sudah transfer. Satu kasus hanya bisa di-claim sekali. Wajib sertakan Order ID & kapan customer transfer di note.

POST https://pay.fncreative.org/api/merchants/payment-issues/218/claim
Authorization: Bearer YOUR_SESSION_TOKEN
Content-Type: application/json

{
  "note": "Customer transfer jam 22:05 WIB, Order ORDER-76250626114, bukti sudah dikirim via WA"
}

Response sukses:

{
  "status": true,
  "message": "Permintaan tinjauan dikirim. Tim FN CREATIVE akan mengecek bukti transfer.",
  "data": {
    "log_id": 218,
    "amount": 237063,
    "detected_at": "2026-06-26 20:15:42 WIB",
    "merchant_claimed_at": "2026-06-26 22:06:10 WIB",
    "merchant_claim_note": "Customer transfer jam 22:05 WIB, ..."
  }
}

Error umum (HTTP 400):

• Kasus ini bukan milik merchant Anda.
• Kasus ini sudah diselesaikan.
• Anda sudah mengajukan tinjauan untuk kasus ini.

Riwayat notifikasi kasus

Mengembalikan riwayat pengiriman notifikasi untuk merchant yang login (Telegram + Gmail). Notifikasi admin/ops tidak ditampilkan di endpoint ini.

GET https://pay.fncreative.org/api/merchants/payment-issues/218/notifications
Authorization: Bearer YOUR_SESSION_TOKEN

Notifikasi otomatis

Merchant menerima Telegram dan/atau Gmail (jika diaktifkan di dashboard) pada event berikut:

Aktifkan notifikasi: Webhook Log & Email (Telegram + Gmail).

Endpoint admin (FN CREATIVE Ops)

11. Webhook Log & Notifikasi Email

Log pengiriman webhook

Header: Authorization: Bearer <session_token>. Menampilkan riwayat callback ke URL merchant: order_id, target_url, status_code, success, error_text, created_at.

Notifikasi email merchant

Selain Telegram, merchant bisa menerima email untuk event pembayaran, penarikan, kasus tidak masuk saldo, dan penyelesaian kasus (kredit/refund/tutup). Aktifkan di dashboard atau via API:

PUT https://pay.fncreative.org/api/merchants/email-notify
Authorization: Bearer YOUR_SESSION_TOKEN
Content-Type: application/json

{ "enabled": true }

Tes kirim: POST /merchants/email-notify/test

12. Kredensial & Registrasi OTP

Manajemen API key (session)

POST https://pay.fncreative.org/api/merchants/regenerate-api-key
Authorization: Bearer YOUR_SESSION_TOKEN

Registrasi dengan OTP email

Jika server mengaktifkan verifikasi OTP (lihat email.otp_register_required di GET /api/docs/meta):

1. POST /merchants/register/send-otp — kirim kode ke email (body sama seperti register)
2. POST /merchants/register/confirm — konfirmasi dengan verification_id + otp_code

{
  "verification_id": "dari response send-otp",
  "otp_code": "123456"
}

Jika OTP tidak aktif, gunakan POST /merchants/register langsung (lihat Onboarding Partner).

Best Practice Integrasi (Produksi)

• Auth ganda: integrasi bot/website pakai x-api-key + id_merchant; dashboard, kasus tidak masuk saldo & riwayat notifikasi pakai Bearer session_token.
• Jika customer klaim sudah transfer tetapi saldo belum masuk, cek Payment Issues → ajukan claim dengan Order ID & bukti.
• Tampilkan total_amount besar di checkout — bukan hanya amount.
• Countdown dari expired_at — semua timestamp API dalam format WIB (Asia/Jakarta).
• Satu order_id = satu invoice. Jangan create ulang berkali-kali tanpa perlu.
• Jika masih PENDING, API mengembalikan QR yang sama — cek status dulu sebelum create baru.
• Setelah EXPIRED, create dengan order_id baru atau hapus record expired (reuse order_id diperbolehkan setelah expired).
• Validasi webhook dengan webhook_secret + HMAC — abaikan callback tanpa signature valid.
• Fee platform (1,2%) hanya pada transaksi SUCCESS — EXPIRED tidak dikenai fee.

Status Types

Onboarding Partner

User bisa daftar sendiri tanpa hubungi admin:

1. Buka https://pay.fncreative.org/register/
2. Isi nama, email, password, dan opsional callback_url webhook HTTPS
3. Setujui Syarat & Ketentuan dan Kebijakan Privasi
4. Akun menunggu persetujuan admin — setelah disetujui, kredensial API tersedia di dashboard
5. Login kapan saja di /login/ — API key yang sama terlihat di dashboard

API Registrasi (opsional)

Detail OTP & manajemen kredensial: lihat Kredensial & Registrasi OTP.

{
  "name": "Toko ABC",
  "email": "dev@tokoabc.com",
  "password": "password-min-8",
  "password_confirm": "password-min-8",
  "store_name": "Toko ABC",
  "callback_url": "https://tokoabc.com/webhook/fn-payment",
  "terms_accepted": true
}