API Documentation — FR3 NEWERA

Introduction

Gambaran umum dan cara kerja API

API FR3 NEWERA memungkinkan Anda mengintegrasikan layanan pembayaran QRIS, transfer saldo, dan manajemen akun. Semua permintaan menggunakan format JSON dan mengembalikan respons JSON. Endpoint API yang memerlukan autentikasi wajib menyertakan apikey yang valid.

Design Principles

GET untuk Data & Inisiasi

Endpoint read-only dan pembuatan resource seperti topup QRIS menggunakan GET dengan query parameter.

POST untuk State Change

Endpoint yang mengubah state server secara permanen (transfer, cancel) wajib menggunakan POST dengan request body.

HTTPS Wajib

Seluruh komunikasi wajib melalui HTTPS. Request HTTP biasa akan ditolak otomatis.

Base URL: Semua endpoint menggunakan base URL https://fr3newera.com/api/v1. Contoh: GET https://fr3newera.com/api/v1/topup?apikey=...&nominal=10000

Authentication

Cara mendapatkan dan menggunakan API Key

Hampir semua endpoint memerlukan API Key. Pengecualian hanya pada POST /check-user. API Key dapat dikirim melalui query parameter pada GET request, request body pada POST request, atau header x-api-key untuk integrasi backend.

Mendapatkan API Key

1. Login Dashboard

Masuk ke dashboard FR3 NEWERA PPOB menggunakan akun Anda.

2. Buka Profil

Navigasi ke halaman Profil melalui menu akun di dashboard.

3. Generate Key

Klik tombol "Daftar Apikey Sekarang!" dan salin hasilnya.

Penting: API Key hanya dapat di-generate sekali. Jangan pernah menyimpan API Key di sisi client (frontend publik). Jika hilang atau bocor, segera hubungi admin untuk reset.

Metode 1 — Query Parameter (GET)

Query Parameter

GET /api/v1/check-saldo?apikey=AO_xxxxx221220241234abcdefghij

Metode 2 — Request Body (POST)

JSON Body

{
  "apikey":  "AO_xxxxx221220241234abcdefghij",
  "email":   "johndoe@email.com",
  "nominal": 50000
}

Metode 3 — Header (x-api-key)

HTTP Header

x-api-key: AO_xxxxx221220241234abcdefghij
atau
Authorization: Bearer AO_xxxxx221220241234abcdefghij

Semua metode diterima. Sistem akan otomatis mendeteksi API Key dari query param, body, header x-api-key, maupun Authorization: Bearer. Jika sebelumnya mendapat error 401 — pastikan API Key sudah benar dan akun tidak diblokir.

Security & Rate Limiting

Standar keamanan dan pembatasan request

Prinsip Keamanan PCI DSS

Multi-Method Auth

API Key diterima via query param, body, header x-api-key, maupun Authorization Bearer untuk fleksibilitas integrasi.

TLS Enforcement

Seluruh traffic dienkripsi menggunakan TLS 1.2+. Plain HTTP diblokir penuh.

Session & Expiry

QRIS yang dibuat memiliki masa berlaku 10 menit. Transaksi EXPIRED tidak bisa diproses.

Account Lockout

Akun yang melanggar kebijakan akan diblokir. API Key dari akun banned mengembalikan 403.

User-Agent Filtering

Request dari non-browser ditolak dengan 403 untuk mencegah penyalahgunaan otomatis.

Atomic Transactions

Operasi finansial menggunakan database transaction untuk menjamin konsistensi data.

Rate Limiting

Parameter	Nilai Default	Keterangan
limit_per_minute	60 request	Maksimum request per menit untuk setiap API Key. Jika terlampaui, server akan merespon `429 Too Many Requests`.
limit_per_day	10.000 request	Batas harian (reset setiap tengah malam). Anda dapat melihat sisa kuota di dashboard.
alert_threshold	80%	Notifikasi akan dikirim (jika diaktifkan) ketika kuota harian mencapai persentase ini.

Anda dapat menyesuaikan batas limit_per_minute, limit_per_day, dan alert_threshold melalui halaman Dashboard → Profil → API Quota. Setiap perubahan akan langsung berlaku.

Perhatian: Melebihi rate limit akan mengembalikan status 429 Too Many Requests. Implementasikan exponential backoff pada klien Anda sebelum melakukan retry.

Buat Topup

Generate QRIS untuk topup saldo via API

POST /api/v1/topup Auth Required

Membuat permintaan TopUp saldo baru dan menghasilkan QRIS untuk pembayaran. Parameter dikirim melalui request body (JSON) — metode POST digunakan untuk mencegah spam dan menjaga keamanan parameter. Sistem menggunakan kode unik sekuensial (0–999) untuk membedakan setiap transaksi. Setelah QRIS dibuat, gunakan GET /check-status untuk memantau statusnya secara real-time.

Request Body

Parameter	Type	Status	Deskripsi
apikey	String	Wajib	API Key Anda
nominal	Number	Wajib	Nominal topup dalam Rupiah. Minimal Rp 1.000

Contoh Request

JSON Body

POST /api/v1/topup
Content-Type: application/json

{
  "apikey":  "AO_xxxxx221220241234abcdefghij",
  "nominal": 10000
}

Response (Success)

200 OK

{
  "status":  200,
  "message": "Topup Created",
  "data": {
    "trxId":         "TOPUP-1743000000000",
    "user_email":   "user@email.com",
    "type":          "TOPUP",
    "item":          "Top Up Saldo API",
    "amount":        10000,
    "fee":           3,
    "uniqueCode":    3,
    "totalTransfer": 10003,
    "expiry":        1735723200000,
    "qr_string":     "000201010211..."
  }
}

Status transaksi selalu PENDING saat pertama dibuat. Gunakan GET /check-status?idTransaksi=trxId untuk memantau perkembangan secara real-time. totalTransfer adalah jumlah yang harus dibayar via QRIS (nominal + kode unik).

Total Bayar adalah totalTransfer. Pembayaran kurang dari jumlah ini tidak akan terdeteksi. QRIS kadaluarsa setelah 10 menit. Kode unik akan dikreditkan kembali ke saldo saat pembayaran berhasil.

Cancel Topup

Membatalkan transaksi topup yang masih PENDING

POST /api/v1/topup/cancel Auth Required

Membatalkan transaksi topup milik Anda yang berstatus PENDING. Hanya transaksi yang belum dibayar dan belum kadaluarsa yang bisa dibatalkan. Status akan berubah menjadi CANCELED dan kode unik dibebaskan untuk transaksi berikutnya.

Request Body

JSON

{
  "apikey": "AO_xxxxx221220241234abcdefghij",
  "trxId":  "674a3b8c9d0e1f2a"
}

Parameters

Parameter	Type	Status	Deskripsi
apikey	String	Wajib	API Key Anda
trxId	String	Wajib	Nilai `trxId` yang didapat dari response `POST /topup`. Contoh: `TOPUP-1743000000000`

Response

200 OK

{
  "status":  200,
  "message": "Transaksi berhasil dibatalkan"
}

Endpoint ini hanya bisa membatalkan transaksi milik akun Anda sendiri (berdasarkan API Key). Mencoba membatalkan transaksi akun lain akan mengembalikan error 400.

Check Status

Mengecek status pembayaran berdasarkan ID transaksi

GET /api/v1/check-status?apikey=&idTransaksi= Auth Required

Mengecek status pembayaran TopUp secara real-time dengan menghubungi gateway QRIS secara langsung. Lakukan polling dengan interval minimal 3 detik untuk menghindari rate limit.

Query Parameters

Parameter	Type	Status	Deskripsi
apikey	String	Wajib	API Key Anda
idTransaksi	String	Wajib	Nilai `trxId` yang didapat dari response `POST /topup`. Contoh: `TOPUP-1743000000000`

Contoh Request

URL

GET /api/v1/check-status?apikey=AO_xxxxx...&idTransaksi=TOPUP-1743000000000

Response

200 OK

{
  "status": 200,
  "data": {
    "trxId":         "TOPUP-1743000000000",
    "status":        "SUCCESS",
    "amount":        10000,
    "totalTransfer": 10003,
    "uniqueCode":    3,
    "type":          "TOPUP",
    "item":          "Top Up Saldo API",
    "expiry":        1743003600000
  }
}

Nilai Status

SUCCESS PENDING EXPIRED CANCELED

Check Saldo

Mengecek saldo terkini akun Anda

GET /api/v1/check-saldo?apikey= Auth Required

Mengambil saldo terkini berdasarkan API Key. Endpoint ini adalah read-only murni, sehingga menggunakan GET. Disarankan untuk melakukan cache lokal selama 30 detik untuk efisiensi.

Query Parameters

Parameter	Type	Status	Deskripsi
apikey	String	Wajib	API Key Anda

Contoh Request

URL

GET /api/v1/check-saldo?apikey=AO_xxxxx221220241234abcdefghij

Response

200 OK

{
  "status": 200,
  "data": {
    "saldo": 150000
  }
}

History Transaksi

Mengambil riwayat transaksi dengan filter dan pagination

GET /api/v1/history?apikey=&page=&filter=&limit= Auth Required

Mengambil riwayat seluruh transaksi akun Anda. Mendukung pagination dan filter berdasarkan status. Transaksi PENDING yang telah melewati waktu expiry akan otomatis diperbarui menjadi EXPIRED.

Query Parameters

Parameter	Type	Status	Deskripsi
apikey	String	Wajib	API Key Anda
page	Number	Opsional	Halaman ke-N. Default: 1
limit	Number	Opsional	Jumlah data per halaman. Default: 10, Maks: 50
filter	String	Opsional	Filter: all \| success \| pending \| canceled. Default: all

Contoh Request

URL

GET /api/v1/history?apikey=AO_xxxxx...&page=1&limit=10&filter=success

Response

200 OK

{
  "status":  200,
  "hasMore": false,
  "data": [
    {
      "trxId":         "674a3b8c9d0e1f2a",
      "type":          "TOPUP",
      "item":          "Top Up Saldo API",
      "amount":        10000,
      "totalTransfer": 10003,
      "date":          "2024-01-01T12:00:00Z",
      "status":        "SUCCESS"
    },
    {
      "trxId":         "TF-API-1735723200000",
      "type":          "TF_OUT",
      "item":          "Transfer API ke John Doe",
      "amount":        50000,
      "totalTransfer": 50000,
      "date":          "2024-01-01T11:30:00Z",
      "status":        "SUCCESS",
      "note":          "Penerima: johndoe@email.com"
    }
  ]
}

Nilai Type

TOPUP TF_IN TF_OUT BUY WD ADJUST_IN ADJUST_OUT

Check User

Validasi keberadaan akun sebelum transfer

POST /api/v1/check-user No Auth

Memeriksa apakah email terdaftar di sistem FR3 NEWERA dan mengembalikan informasi dasar pengguna. Endpoint ini tidak memerlukan API Key. Email dikirim di body (POST) untuk menjaga privasi pengguna agar tidak terekam di server log URL.

Request Body

JSON

{
  "email": "johndoe@email.com"
}

Parameters

Parameter	Type	Status	Deskripsi
email	String	Wajib	Alamat email user yang akan dicek

Response

200 OK

{
  "status": 200,
  "data": {
    "username":    "John Doe",
    "email":       "johndoe@email.com",
    "verified":    false,
    "profile_pic": "https://ui-avatars.com/api/?name=John+Doe&..."
  }
}

Field verified bernilai true jika user sudah memiliki API Key. Gunakan endpoint ini untuk validasi penerima sebelum melakukan POST /transfer.

Transfer Saldo

Kirim saldo ke sesama pengguna FR3 NEWERA

POST /api/v1/transfer Auth Required

Mentransfer saldo dari akun Anda ke akun penerima berdasarkan email. Transfer menggunakan database transaction (BEGIN/COMMIT) untuk menjamin atomisitas — saldo pengirim tidak akan berkurang jika saldo penerima gagal bertambah. Transfer tidak dapat dibatalkan setelah berhasil.

Request Body

JSON

{
  "apikey":  "AO_xxxxx221220241234abcdefghij",
  "email":   "johndoe@email.com",
  "nominal": 50000
}

Parameters

Parameter	Type	Status	Deskripsi
apikey	String	Wajib	API Key Anda (pengirim)
email	String	Wajib	Email penerima transfer
nominal	Number	Wajib	Jumlah saldo yang ditransfer. Harus bilangan bulat positif

Response

200 OK

{
  "status":  200,
  "message": "Transfer Berhasil"
}

Transfer tidak dapat dibatalkan setelah berhasil. Selalu gunakan POST /check-user terlebih dahulu untuk memverifikasi email penerima sebelum melakukan transfer.

Withdraw Instant (E-Wallet)

Tarik saldo ke E-Wallet secara otomatis dan realtime

GET /withdraw2?apikey=&ewallet=&nomor=&kode= Auth Required

Endpoint ini memungkinkan Anda melakukan penarikan saldo (Withdraw) ke berbagai E-Wallet secara instan melalui sistem otomatis. Saldo akun akan dipotong sesuai harga produk yang dipilih. Response dapat berupa status SUCCESS (langsung atau akan diproses) atau PENDING (memerlukan pengecekan ulang).

Query Parameters

Parameter	Type	Status	Deskripsi
apikey	String	Wajib	API Key Anda
ewallet	String	Wajib	Jenis E-Wallet: dana, gopay, ovo, shopee, linkaja, dll
nomor	String	Wajib	Nomor HP tujuan E-Wallet (contoh: 08123456789)
kode	String	Wajib	Kode produk (contoh: d1 untuk Dana 1rb). Masukkan kode asal untuk melihat daftar produk

Contoh Request

URL

GET /withdraw2?apikey=YOUR_APIKEY&ewallet=dana&nomor=08123456789&kode=d1

Response (Contoh Sukses Langsung)

200 OK

{
  "status":  200,
  "message": "Transaksi withdraw2 langsung sukses.",
  "trxId":   "WD2-171123456789",
  "detail": {
    "ewallet":      "dana",
    "nomor":        "08123456789",
    "namaEwallet":  "Budi Santoso",
    "product":      "Dana 1.000",
    "harga":        1038,
    "status":        "SUCCESS"
  }
}

Response (Akan Diproses / PENDING)

200 OK

{
  "status":  200,
  "message": "Transaksi withdraw2 sedang diproses.",
  "trxId":   "WD2-171123456789",
  "detail": {
    "ewallet":      "dana",
    "nomor":        "08123456789",
    "namaEwallet":  "Budi Santoso",
    "product":      "Dana 1.000",
    "harga":        1038,
    "status":        "PENDING"
  }
}

Jika Anda memasukkan kode yang salah, API akan mengembalikan daftar kode produk yang tersedia beserta harganya dalam field available_products.

Request Log

Lihat riwayat semua request yang menggunakan API Key Anda

GET /api/profile/api-requests Session Required

Mengembalikan daftar seluruh request yang pernah dilakukan menggunakan API Key milik akun Anda. Setiap kali endpoint API dipanggil dengan API Key yang valid, sistem secara otomatis mencatat endpoint, metode, IP, dan waktu ke file database/mutasi-api.json. Akses endpoint ini memerlukan sesi login aktif (bukan API Key), sehingga hanya bisa diakses melalui dashboard. Tombol » di halaman Profil akan membuka daftar ini secara langsung.

Query Parameters

Parameter	Type	Status	Deskripsi
page	Number	Opsional	Halaman pagination. Default: 1. Setiap halaman berisi 20 entri.

Response

200 OK

{
  "status":  200,
  "data": [
    {
      "id":         "REQ-1735723200001",
      "apikey":    "AO_xxxxx...",
      "user_email": "user@email.com",
      "username": "John",
      "endpoint": "/api/v1/check-saldo",
      "method":   "GET",
      "ip":       "180.244.x.x",
      "date":     "2025-01-01T11:00:00.000Z"
    }
  ],
  "total":   1,
  "hasMore": false
}

Struktur Data

Field	Type	Deskripsi
id	String	ID unik request dengan prefix REQ-
apikey	String	API Key yang digunakan untuk request
user_email	String	Email pemilik API Key
username	String	Username pemilik API Key
endpoint	String	Path endpoint yang dipanggil, contoh: /api/v1/topup
method	String	Metode HTTP: GET atau POST
ip	String	Alamat IP pemanggil request
date	String	Timestamp ISO 8601 saat request masuk

Request Log hanya bisa diakses melalui sesi login, bukan via API Key. Endpoint ini tidak termasuk dalam sistem checkApiKey sehingga tidak akan tercatat sebagai request API. Data disimpan di database/mutasi-api.json dan dapat dipantau oleh Admin dari panel.

Cek E-Wallet (Inquiry)

Validasi nomor tujuan berbagai layanan dompet digital

POST /api/v1/cek Auth Required

Informasi Biaya Penggunaan

Administrator — Pengguna dengan role Admin tidak dikenakan biaya apapun saat menggunakan endpoint inquiry ini.

Gratis

Member / User Reguler — Setiap pemanggilan endpoint inquiry ini akan dikenakan biaya sebesar Rp 1 per request, dipotong langsung dari saldo akun Anda.

Rp 1 / req

Melakukan validasi (inquiry) nomor tujuan untuk berbagai layanan dompet digital (E-Wallet). Gunakan endpoint ini untuk memverifikasi keberadaan akun E-Wallet penerima sebelum melakukan top-up atau transfer.

Daftar Kode E-Wallet

Kode	Layanan	Deskripsi
CEKD	Dana	Cek nama akun Dana berdasarkan nomor HP
CEKGJK	Gojek / GoPay	Cek nama akun Gojek Customer berdasarkan nomor HP
CEKISAKU	iSaku	Cek nama akun iSaku berdasarkan nomor HP
CEKLINK	LinkAja	Cek nama akun LinkAja berdasarkan nomor HP
CEKOVO	OVO	Cek nama akun OVO berdasarkan nomor HP
CEKSHP	ShopeePay	Cek nama akun ShopeePay berdasarkan nomor HP

Request Body

Parameter	Type	Status	Deskripsi
apikey	String	Wajib	API Key Anda
code	String	Wajib	Kode inquiry, contoh: CEKD
dest	String	Wajib	Nomor HP tujuan sesuai layanan E-Wallet yang dipilih

Contoh Request

JSON Body

POST /api/v1/cek
Content-Type: application/json

{
  "apikey": "AO_xxxxx221220241234abcdefghij",
  "code":   "CEKD",
  "dest":   "08123456789"
}

Response (Sukses)

200 OK

{
  "status": 200,
  "code":   "CEKD",
  "dest":   "08123456789",
  "result": "Budi Santoso | 08123456789"
}

Endpoint CEK E-Wallet menggunakan path POST /api/v1/cek. Pembeda antar layanan hanya pada nilai parameter code yang dikirimkan.

Error Codes

Referensi lengkap kode error dan cara penanganannya

Semua error mengembalikan JSON dengan field status (HTTP status code) dan error berisi pesan deskriptif.

Format Error

Error Response

{
  "status": 401,
  "error":  "API Key tidak valid atau tidak ditemukan"
}

Kode HTTP

200

OK

Request berhasil diproses.

400

Bad Request

Parameter tidak valid atau tidak lengkap.

401

Unauthorized

API Key tidak ada, tidak valid, atau tidak ditemukan.

403

Forbidden

Akun diblokir atau akses ditolak.

404

Not Found

Resource (user/transaksi) tidak ditemukan.

429

Too Many Requests

Rate limit terlampaui. Terapkan exponential backoff.

500

Server Error

Kesalahan internal server. Coba lagi dalam beberapa saat.

Pesan Error Umum

Error Message	HTTP	Endpoint	Penanganan
API Key diperlukan	401	Semua (kecuali check-user)	Sertakan parameter apikey
API Key tidak valid atau tidak ditemukan	401	Semua	Periksa kembali nilai API Key — pastikan sudah ter-generate di Profil
Akun Anda dibekukan	403	Semua	Hubungi admin
Minimum topup 1000	400	POST /topup	Nominal minimal Rp 1.000
Saldo tidak mencukupi	400	POST /transfer	Topup saldo terlebih dahulu
Email penerima tidak ditemukan	404	POST /transfer	Verifikasi dengan POST /check-user
Tidak bisa transfer ke diri sendiri	400	POST /transfer	Email penerima harus berbeda
Transaksi tidak ditemukan	404	GET /check-status	Periksa nilai idTransaksi
Internal server error	500	Semua	Retry dengan exponential backoff
code dan dest diperlukan	400	POST /cek	Lengkapi kedua parameter
Nomor tidak ditemukan atau tidak valid	404	POST /cek	Pastikan nomor benar dan terdaftar di layanan terkait

Integrasi Pembayaran
Cepat & Aman

Introduction

GET untuk Data & Inisiasi

POST untuk State Change

HTTPS Wajib

Authentication

1. Login Dashboard

2. Buka Profil

3. Generate Key

Security & Rate Limiting

Multi-Method Auth

TLS Enforcement

Session & Expiry

Account Lockout

User-Agent Filtering

Atomic Transactions

Buat Topup

Cancel Topup

Check Status

Check Saldo

History Transaksi

Check User

Transfer Saldo

Withdraw Instant (E-Wallet)

Request Log

Cek E-Wallet (Inquiry)

Error Codes

Siap Mengintegrasikan API?

API Tester

Integrasi PembayaranCepat & Aman

Introduction

GET untuk Data & Inisiasi

POST untuk State Change

HTTPS Wajib

Authentication

1. Login Dashboard

2. Buka Profil

3. Generate Key

Security & Rate Limiting

Multi-Method Auth

TLS Enforcement

Session & Expiry

Account Lockout

User-Agent Filtering

Atomic Transactions

Buat Topup

Cancel Topup

Check Status

Check Saldo

History Transaksi

Check User

Transfer Saldo

Withdraw Instant (E-Wallet)

Request Log

Cek E-Wallet (Inquiry)

Error Codes

Siap Mengintegrasikan API?

API Tester

Integrasi Pembayaran
Cepat & Aman