Dokumentasi API Merchant

Integrasikan pembayaran QRIS, DANA, OVO, dan ShopeePay ke website atau aplikasi Anda. Semua request memakai POST (form-urlencoded atau JSON), dan setiap request wajib ditandatangani.

1. Informasi Dasar

Item	Nilai
Base URL	`https://idragonpay.com/pay/api`
Format Request	`POST` — `application/x-www-form-urlencoded` atau JSON
Format Response	`application/json`
Kredensial	`merchant_id` + `secret_key` (diberikan saat pendaftaran)

2. Skema Signature

Setiap request API harus menyertakan parameter sign yang dihitung dengan algoritma:

1. Ambil semua parameter (KECUALI "sign")
2. Urutkan key secara ascending (ksort)
3. Gabung: key=value&key=value&...
   (abaikan parameter yang kosong/null)
4. Tambahkan: key=SECRET_KEY di akhir
5. sign = MD5(string) dalam HURUF BESAR

Contoh dengan secret key MySecret123:

params = {merchant_id: "MER01", merchant_no: "INV-001", amount: "50000", channel: "QRIS"}
urutan: amount=50000&channel=QRIS&merchant_id=MER01&merchant_no=INV-001
string: amount=50000&channel=QRIS&merchant_id=MER01&merchant_no=INV-001&key=MySecret123
sign  : strtoupper(md5(string))

Contoh PHP

function sign(array $params, string $key): string {
    ksort($params);
    $str = '';
    foreach ($params as $k => $v) {
        if ($v === '' || $v === null) continue;
        $str .= $k . '=' . $v . '&';
    }
    $str .= 'key=' . $key;
    return strtoupper(md5($str));
}

3. Endpoint

3.1 Buat Order Pembayaran — POST `/create.php`

Membuat order deposit baru dan mengembalikan URL pembayaran (cashier) untuk pelanggan.

Parameter	Wajib	Keterangan
`merchant_id`	Ya	ID merchant Anda
`merchant_no`	Ya	Nomor order unik dari sistem Anda (tidak boleh duplikat)
`amount`	Ya	Jumlah dalam IDR, minimal 10.000
`channel`	Tidak	`QRIS` (default), `DANA`, `OVO`, `SHOPEEPAY`, `LINKAJA`
`phone`	Tidak	Nomor HP pelanggan (opsional)
`name`	Tidak	Nama pelanggan (opsional)
`email`	Tidak	Email pelanggan (opsional)
`product_info`	Tidak	Deskripsi produk
`sign`	Ya	Signature (lihat bagian 2)

Contoh request:

curl -X POST https://idragonpay.com/pay/api/create.php \
  -d "merchant_id=MER01" \
  -d "merchant_no=INV-20260811-001" \
  -d "amount=50000" \
  -d "channel=QRIS" \
  -d "sign=ABC123..."

Contoh respons sukses:

{
  "code": 0,
  "msg": "success",
  "data": {
    "order_id": "R260811A1B2C3D4E5F6",
    "merchant_no": "INV-20260811-001",
    "amount": 50000,
    "channel": "QRIS",
    "qr_code": "",
    "pay_url": "https://pre-g-idn-cashier.bestpay.uk/payment/idn/cashier/redirect?sn=...",
    "status": "pending"
  }
}

💡 Arahkan pelanggan ke pay_url (halaman cashier) atau tampilkan qr_code untuk scan.

3.2 Cek Status Order — POST `/query.php`

Parameter	Wajib	Keterangan
`merchant_id`	Ya	ID merchant
`order_id`	*	Order ID dari sistem kami (atau pakai `merchant_no`)
`merchant_no`	*	Nomor order Anda (atau pakai `order_id`)
`sign`	Ya	Signature

Respons: status = pending | paid | failed

3.3 Verifikasi Kebenaran — POST `/verify.php`

Sama seperti query, tapi hasilnya diverifikasi langsung ke upstream BestPay (sumber kebenaran). Berguna saat ada pelanggan mengklaim sudah bayar — sistem akan membuktikan status aslinya. Parameter sama dengan query.

3.4 Penarikan Saldo — POST `/withdraw.php`

Parameter	Wajib	Keterangan
`merchant_id`	Ya	ID merchant
`amount`	Ya	Jumlah ditarik (min 10.000)
`bank_name`	Ya	Nama bank, contoh: BCA
`bank_account`	Ya	Nomor rekening
`bank_holder`	Ya	Atas nama rekening
`type`	Tidak	`bankcard` (default) atau `ewallet`
`sign`	Ya	Signature

Biaya penarikan Rp 5.000 per transaksi, dipotong otomatis. Saldo dibekukan saat pengajuan dan dikembalikan penuh jika ditolak.

4. Callback (Notifikasi Pembayaran)

Setelah pelanggan membayar, kami mengirim notifikasi POST ke callback_url merchant Anda (didaftarkan saat pembuatan akun).

Parameter	Keterangan
`orderId`	Order ID sistem kami
`merchantNo`	Nomor order Anda
`amount`	Jumlah pembayaran (IDR)
`channel`	Channel pembayaran
`status`	`paid` \| `failed`
`tradeTime`	Waktu transaksi
`sign`	Signature — verifikasi dengan algoritma di bagian 2 (pakai secret key Anda)

⚠️ PENTING: Selalu verifikasi sign callback sebelum memproses — ini mencegah notifikasi palsu. Balas dengan teks OK atau SUCCESS. Jika callback gagal, kami retry otomatis hingga 5 kali.

Contoh verifikasi callback (PHP)

$raw = file_get_contents('php://input');
parse_str($raw, $p);
$sign = $p['sign'];
unset($p['sign']);
$calc = sign($p, $SECRET_KEY);
if (!hash_equals($calc, strtoupper($sign))) {
    http_response_code(403); exit('bad sign');
}
// sign valid — proses order sesuai status
echo 'OK';

5. Kode Error

Code	Keterangan
`0`	Sukses
`1401`	merchant_id & sign wajib
`1402`	Parameter tidak valid / amount minimal 10.000
`1403`	Signature tidak valid
`1404`	Merchant tidak ditemukan / nonaktif
`1406`	Order duplikat (merchant_no sudah dipakai)
`1407`	Order tidak ditemukan
`1429`	Terlalu banyak request (rate limit)
`1501`	Saldo tidak cukup (penarikan)

6. Batas & Kebijakan

Rate limit API: 30 request/menit per IP
Amount minimal 10.000 IDR per transaksi
Merchant_no harus unik per merchant (duplikat ditolak)
Setiap transaksi tercatat lengkap (log audit) dan bisa diverifikasi ke upstream
Saldo dapat ditarik kapan saja (fee Rp 5.000/penarikan)

Butuh bantuan integrasi? Hubungi kami via Telegram: @gudang168_bot · Syarat & Ketentuan