Dokumentasi REST API & Panduan Integrasi
Panduan integrasi teknis MixToko: Payment Gateway QRIS Dinamis, WhatsApp Gateway, AI Models API, Game ID Checker, dan License Guard Helper.
MixToko Pay: Panduan Integrasi REST API (Get Started)
Panduan lengkap integrasi sistem pembayaran digital: QRIS Dinamis All Payment (BCA, Mandiri, BRI, BNI, ShopeePay, DANA, OVO, GoPay), Hosted Checkout URL, Webhook IPN realtime, dan API Cek Status Transaksi.
A. Persiapan (Setup & Kredensial)
Pertama, pastikan Anda telah mendaftar akun di MixToko dan mengaktifkan toko/merchant Anda di menu Portal Gateway. Setelah disetujui (Approved), Anda akan mendapatkan identitas kredensial berikut:
Identitas unik toko/proyek Anda di sistem MixToko.
Kunci otentikasi wajib dikirim pada header setiap request API.
Kunci rahasia untuk tanda tangan digital request & verifikasi Webhook.
Autentikasi Header & Tanda Tangan Digital (HMAC-SHA256)
Setiap request POST wajib menyertakan header x-api-key dan tanda tangan digital x-signature yang dihitung dari Raw Body JSON menggunakan Private Key Anda.
// Contoh Pembuatan Signature di PHP:
$rawJsonBody = json_encode([
'amount' => 50000,
'order_id' => 'INV-20261027-001'
]);
$signature = hash_hmac('sha256', $rawJsonBody, $privateKey);
// Request Headers yang Dikirim:
// Content-Type: application/json
// x-api-key: mtk_live_xxxxxxxxxxxxxxxx
// x-signature: [hasil_hash_hmac_sha256]
B. Integrasi Via URL (Hosted Checkout)
Untuk mengarahkan pelanggan Anda langsung ke halaman pembayaran instan tanpa perlu repot mengelola string QRIS sendiri di aplikasi Anda, gunakan URL pembayaran hosted:
ref_id: ID referensi transaksi unik yang didapat saat server Anda memanggil endpoint POST /api/v1/pg/checkout. Contoh:TRX8A9F1B2C.redirect: (Opsional) URL tujuan untuk mengarahkan pembeli kembali ke website toko Anda setelah pembayaran lunas. Contoh:https://tokoanda.com/invoices/success.
Contoh URL Penggunaan yang Benar:
https://mixtoko.net/pay/gateway/TRX8A9F1B2C?redirect=https://app.tokoanda.com/invoices/240910HDE7C9
C. Integrasi Via API (Direct QRIS Dinamis)
Integrasi via API (Headless) memungkinkan server Anda menerima detail lengkap berupa URL gambar QRIS, string QRIS baku, nominal akhir, dan waktu kadaluarsa. Anda bebas menampilkan QR code di aplikasi mobile atau website checkout Anda sendiri.
C.1. Endpoint Create QRIS Dinamis
Endpoint ini langsung mengembalikan objek QRIS dinamis yang siap di-scan pembeli.
Body Request (JSON):
{
"amount": 25000,
"order_id": "INV-20261027-002",
"expiry_minutes": 30,
"callback_url": "https://website-anda.com/api/payment-webhook"
}
Contoh Eksekusi Menggunakan cURL:
curl -X POST "https://mixtoko.net/api/v1/pg/create-qris" -H "Content-Type: application/json" -H "x-api-key: mtk_live_xxxxxxxxxxxxxxxx" -d '{
"amount": 25000,
"order_id": "INV-20261027-002",
"expiry_minutes": 30,
"callback_url": "https://website-anda.com/api/payment-webhook"
}'
Contoh Response Sukses (HTTP 200 OK):
{
"success": true,
"merchant_code": "MTK001",
"data": {
"ref_id": "TRX9A4B1C2D",
"order_id": "INV-20261027-002",
"amount": 25000,
"fee": 175,
"total": 25175,
"fee_bearer": "buyer",
"qr_image": "https://mixtoko.net/api/v1/pg/qr-image/TRX9A4B1C2D",
"qris_url": "https://mixtoko.net/qr/TRX9A4B1C2D",
"checkout_url": "https://mixtoko.net/pay/gateway/TRX9A4B1C2D",
"expires_at": "2026-10-27T14:30:00+07:00"
}
}
C.2. Endpoint Unified Hosted Checkout
Gunakan endpoint ini bila Anda ingin server mengembalikan checkout_url untuk langsung di-redirect ke halaman pembayaran MixToko.
// Request:
{
"amount": 50000,
"order_id": "INV-20261027-003",
"expiry_minutes": 30
}
// Response (HTTP 200 OK):
{
"success": true,
"merchant_code": "MTK001",
"data": {
"mode": "redirect",
"ref_id": "TRX8A9F1B2C",
"order_id": "INV-20261027-003",
"amount": 50000,
"fee": 350,
"total": 50350,
"checkout_url": "https://mixtoko.net/pay/gateway/TRX8A9F1B2C",
"expires_at": "2026-10-27T14:30:00+07:00"
}
}
D. Pilihan Metode Pembayaran (Payment Channels)
Anda dapat memeriksa channel pembayaran aktif kapan saja melalui endpoint publik berikut:
Contoh Response JSON:
{
"success": true,
"channels": [
{
"id": "qris",
"name": "QRIS Dinamis (All Bank & E-Wallet)",
"type": "qris",
"enabled": true,
"fee_percent": 0.70,
"currencies": ["IDR"]
}
]
}
Kompatibilitas QRIS All Payment:
BCA Mobile / myBCA, Livin' by Mandiri, BRImo (BRI), BNI Mobile, CIMB Octo, PermataMobile, Jenius BTPN, BSI Mobile, SeaBank, Bank Jago.
ShopeePay, GoPay, DANA, OVO, LinkAja, AstraPay, i.Saku.
E. Cek Status Transaksi (Transaction Status)
Untuk mengetahui status realtime transaksi secara manual atau polling dari sistem backend Anda, gunakan endpoint berikut:
Body Request (JSON):
{
"ref_id": "TRX9A4B1C2D"
}
Contoh Request dengan cURL:
curl -X POST "https://mixtoko.net/api/v1/pg/status" -H "Content-Type: application/json" -H "x-api-key: mtk_live_xxxxxxxxxxxxxxxx" -d '{"ref_id": "TRX9A4B1C2D"}'
Contoh Response JSON (Status Lunas):
{
"success": true,
"paid": true,
"data": {
"ref_id": "TRX9A4B1C2D",
"order_id": "INV-20261027-002",
"amount": 25000,
"fee": 175,
"total": 25175,
"status": "success",
"is_paid": true,
"paid_at": "2026-10-27 14:05:12"
}
}
F. Simulasi Pembayaran / Testing Webhook (Payment Simulation)
Untuk mempermudah developer menguji alur integrasi dan webhook tanpa harus mentransfer uang sungguhan, MixToko menyediakan API simulasi pembayaran:
Ketika API ini dipanggil, status transaksi ref_id akan seketika diubah menjadi success dan sistem langsung menembakkan Webhook IPN ke server Anda.
Contoh Request Simulasi cURL:
curl -X POST "https://mixtoko.net/api/v1/pg/settle" -H "Content-Type: application/json" -H "x-api-key: mtk_live_xxxxxxxxxxxxxxxx" -d '{"ref_id": "TRX9A4B1C2D"}'
Response Simulasi:
{
"success": true,
"message": "Simulasi pembayaran berhasil! Webhook IPN telah dikirimkan ke server merchant Anda.",
"ref_id": "TRX9A4B1C2D",
"status": "success"
}
G. Webhook Instant Payment Notification (IPN)
Ketika pembeli berhasil menyelesaikan pembayaran QRIS dan dana masuk, server MixToko akan otomatis mengirimkan notifikasi HTTP POST ke Webhook URL yang Anda daftarkan di form merchant.
Struktur Payload Webhook (JSON):
// Headers yang Dikirim MixToko ke Server Anda:
// Content-Type: application/json
// X-Callback-Signature: [hash_hmac_sha256]
// Body (JSON):
{
"event": "payment.success",
"ref_id": "TRX9A4B1C2D",
"order_id": "INV-20261027-002",
"amount": 25000,
"fee": 175,
"total": 25175,
"status": "success",
"paid_at": "2026-10-27 14:05:12"
}
1. Pastikan server Anda merespons dengan HTTP status
200 OK dan body {"status":"ok"} segera setelah menerima webhook.2. Selalu validasi tanda tangan
X-Callback-Signature menggunakan Private Key Anda untuk memastikan webhook asli dari MixToko dan bukan upaya manipulasi.
Contoh Script Handler Webhook di PHP:
<?php
// file: webhook_handler.php
header('Content-Type: application/json');
$privateKey = 'pk_live_xxxxxxxxxxxxxxxxxxxxxxxx';
// 1. Ambil payload mentah & header signature
$rawPayload = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_CALLBACK_SIGNATURE'] ?? '';
// 2. Hitung dan cocokkan tanda tangan HMAC
$expectedSignature = hash_hmac('sha256', $rawPayload, $privateKey);
if (!hash_equals($expectedSignature, $signatureHeader)) {
http_response_code(403);
echo json_encode(['success' => false, 'error' => 'Invalid signature']);
exit;
}
// 3. Parse JSON data transaksi
$data = json_decode($rawPayload, true);
$orderId = $data['order_id'] ?? '';
$refId = $data['ref_id'] ?? '';
$status = $data['status'] ?? '';
$amount = (int)($data['amount'] ?? 0);
if ($status === 'success') {
// UPDATE STATUS PESANAN DI DATABASE ANDA MENJADI LUNAS
// misal: $db->query("UPDATE orders SET status = 'paid' WHERE id = '$orderId'");
}
// 4. Beri balasan 200 OK ke MixToko
http_response_code(200);
echo json_encode(['status' => 'ok']);
exit;
H. Contoh Kode Integrasi Lengkap (Multi-Bahasa)
Contoh siap pakai untuk membuat transaksi pembayaran QRIS dari backend aplikasi Anda:
1. PHP Native (cURL)
<?php
$apiKey = 'mtk_live_xxxxxxxxxxxxxxxx';
$privateKey = 'pk_live_xxxxxxxxxxxxxxxx';
$payload = [
'amount' => 50000,
'order_id' => 'INV-' . time(),
'expiry_minutes' => 30,
'callback_url' => 'https://website-anda.com/webhook'
];
$jsonBody = json_encode($payload);
$signature = hash_hmac('sha256', $jsonBody, $privateKey);
$ch = curl_init('https://mixtoko.net/api/v1/pg/create-qris');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $jsonBody,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'x-api-key: ' . $apiKey,
'x-signature: ' . $signature
]
]);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
if (!empty($result['success'])) {
// Tampilkan QR Code kepada pembeli
$qrImage = $result['data']['qr_image'];
$total = $result['data']['total'];
echo "Silakan scan QR: <img src='{$qrImage}'> Total: Rp " . number_format($total);
} else {
echo "Gagal membuat QRIS: " . ($result['error'] ?? 'Unknown error');
}
2. Node.js (Fetch / Axios)
const crypto = require('crypto');
const apiKey = 'mtk_live_xxxxxxxxxxxxxxxx';
const privateKey = 'pk_live_xxxxxxxxxxxxxxxx';
const payload = {
amount: 50000,
order_id: `INV-${Date.now()}`,
expiry_minutes: 30,
callback_url: 'https://website-anda.com/webhook'
};
const rawBody = JSON.stringify(payload);
const signature = crypto.createHmac('sha256', privateKey).update(rawBody).digest('hex');
async function createQris() {
const response = await fetch('https://mixtoko.net/api/v1/pg/create-qris', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': apiKey,
'x-signature': signature
},
body: rawBody
});
const data = await response.json();
if (data.success) {
console.log('Ref ID:', data.data.ref_id);
console.log('QR Image URL:', data.data.qr_image);
console.log('Total Tagihan:', data.data.total);
} else {
console.error('Error:', data.error);
}
}
createQris();
3. Python (requests)
import requests
import json
import hmac
import hashlib
import time
api_key = 'mtk_live_xxxxxxxxxxxxxxxx'
private_key = 'pk_live_xxxxxxxxxxxxxxxx'
payload = {
'amount': 50000,
'order_id': f'INV-{int(time.time())}',
'expiry_minutes': 30,
'callback_url': 'https://website-anda.com/webhook'
}
raw_body = json.dumps(payload, separators=(',', ':'))
signature = hmac.new(private_key.encode('utf-8'), raw_body.encode('utf-8'), hashlib.sha256).hexdigest()
headers = {
'Content-Type': 'application/json',
'x-api-key': api_key,
'x-signature': signature
}
res = requests.post('https://mixtoko.net/api/v1/pg/create-qris', headers=headers, data=raw_body)
print(res.json())
I. Kliring Dana & Penarikan Saldo (/saldo)
Semua pembayaran QRIS yang berhasil lunas diproses secara otomatis oleh sistem kliring MixToko:
- Masa Kliring 24 Jam: Dana hasil pembayaran QRIS masuk ke saldo tertahan (
pending_balance) selama 24 jam untuk melindungi merchant dari sengketa/fraud. - Saldo Tersedia (Available): Setelah melewati 24 jam, dana otomatis dilepas ke saldo utama Anda dan siap ditarik kapan saja melalui menu Saldo Dompet.
- Ketentuan Penarikan (Withdrawal): Minimal penarikan Rp 100.000 dengan biaya admin flat Rp 4.000 ke rekening Bank (BCA, Mandiri, BRI, BNI) atau E-Wallet (DANA, OVO, GoPay, ShopeePay).