Panduan Integrasi SpinoPay
Langkah-langkah menyambungkan aplikasi Laravel (maupun PHP/REST biasa) ke SpinoPay: mulai dari menyiapkan kredensial, memilih pakai halaman bayar SpinoPay atau bikin UI checkout sendiri, sampai menerima notifikasi lunas lewat webhook.
Ringkasan Alur: Apa yang Harus Disiapkan?
Ikuti urutan ini dari awal sampai status pembayaran di aplikasi Anda otomatis berubah menjadi lunas:
Daftarkan aplikasi di dashboard SpinoPay, lalu simpan key dan secret di .env.
Pilih mode HOSTED (pakai halaman SpinoPay) atau DIRECT (bikin UI bayar sendiri).
Redirect user ke spinopay_checkout_url atau render QRIS/VA dari JSON respon.
Verifikasi header X-Spinopay-Signature lalu tandai order lunas di database Anda.
Persiapan Kredensial & Setup di Laravel
Sebelum menulis kode di aplikasi Anda, minta Admin SpinoPay mendaftarkan aplikasi Anda pada menu Aplikasi Klien (atau buat sendiri jika Anda adminnya). Pastikan 4 data berikut sudah siap:
| Item | Contoh Nilai | Kegunaan |
|---|---|---|
| Base URL SpinoPay | https://pay.spinotek.com |
Alamat server API SpinoPay yang dituju aplikasi Anda. |
API Key (X-Api-Key) |
spk_sbx_... |
Dikirim di header setiap request API dari backend aplikasi Anda. |
| Webhook Secret | whsec_... |
Dipakai untuk memvalidasi tanda tangan webhook dari SpinoPay. |
| Webhook URL Aplikasi Anda | https://app-anda.id/api/webhooks/spinopay |
Disimpan di dashboard SpinoPay sebagai tujuan kirim notifikasi lunas. |
SPINOPAY_BASE_URL=https://pay.spinotek.com
SPINOPAY_API_KEY=spk_sbx_ganti_dengan_api_key_anda
SPINOPAY_WEBHOOK_SECRET=whsec_ganti_dengan_webhook_secret_anda
// Tambahkan di dalam return [...] pada config/services.php
'spinopay' => [
'base_url' => env('SPINOPAY_BASE_URL', 'https://pay.spinotek.com'),
'api_key' => env('SPINOPAY_API_KEY'),
'webhook_secret' => env('SPINOPAY_WEBHOOK_SECRET'),
],
Mengambil Daftar Metode Pembayaran Aktif
Jika Anda menggunakan halaman bayar SpinoPay (mode HOSTED), langkah ini tidak wajib karena pilihan bank/QRIS sudah tampil otomatis di halaman checkout SpinoPay. Panggil endpoint ini apabila Anda ingin membuat UI pemilihan metode bayar sendiri di aplikasi Anda (mode DIRECT).
use Illuminate\Support\Facades\Http;
// Kirim parameter amount agar SpinoPay langsung hitung biaya admin + total per metode
$response = Http::withHeaders([
'X-Api-Key' => config('services.spinopay.api_key'),
'Accept' => 'application/json',
])->get(config('services.spinopay.base_url') . '/api/v1/payment-channels', [
'amount' => 250000,
]);
$channels = $response->json('data', []);
// Tiap item berisi: code, name, category, logo_url, fee_label, calculated_fee, total_amount
Membuat Order Pembayaran dari Aplikasi
Saat pelanggan menekan tombol bayar di aplikasi Anda, buat dulu data transaksi di database lokal Anda (status belum bayar), lalu kirim request ke POST /api/v1/orders memakai external_order_id milik Anda.
Tidak perlu bikin tampilan pilih bank/QRIS sendiri. Anda cukup redirect user ke spinopay_checkout_url.
Sertakan channel_code (mis. QRIS / BCA), lalu tampilkan QR atau nomor VA langsung di UI aplikasi Anda.
Redirect user langsung ke halaman invoice bawaan Xendit lewat xendit_invoice_url.
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
public function payWithHostedLink(Request $request, Order $order)
{
$response = Http::withHeaders([
'X-Api-Key' => config('services.spinopay.api_key'),
'Accept' => 'application/json',
])->timeout(20)->post(config('services.spinopay.base_url') . '/api/v1/orders', [
'external_order_id' => $order->invoice_number,
'amount' => (int) $order->total_price,
'payment_flow' => 'HOSTED',
'description' => "Pembayaran {$order->invoice_number}",
'success_redirect_url' => route('checkout.success', $order),
'failure_redirect_url' => route('checkout.failed', $order),
'customer' => [
'name' => $order->customer_name,
'email' => $order->customer_email,
'phone' => $order->customer_phone,
],
]);
if ($response->status() === 409) {
return back()->with('info', 'Order ini sudah lunas sebelumnya.');
}
$response->throw();
$data = $response->json('data');
// Simpan reference_id SpinoPay ke order lokal agar sinkron
$order->update([
'spinopay_reference_id' => $data['reference_id'],
'checkout_url' => $data['payment_instructions']['spinopay_checkout_url'],
]);
// Langsung arahkan user ke halaman pembayaran milik SpinoPay
return redirect()->away($data['payment_instructions']['spinopay_checkout_url']);
}
Memakai Respon Order: Halaman Custom vs Link SpinoPay
Setelah memanggil POST /api/v1/orders, SpinoPay selalu mengembalikan objek data yang berisi kode sinkronisasi (reference_id, external_order_id, xendit_id), rincian biaya (subtotal_amount, fee_amount, amount), dan payment_instructions. Pilih salah satu alur di bawah ini sesuai kebutuhan aplikasi Anda:
payment_flow: "HOSTED"
Pakai Link Pembayaran SpinoPay
Cocok bila Anda ingin cepat jalan tanpa membuat tampilan pilih bank, kalkulator biaya admin, atau halaman QRIS sendiri.
-
1
Kirim request
HOSTED(cukup isiexternal_order_id&amount). -
2
Simpan
data.reference_idke order lokal Anda supaya bisa dicari kembali nanti. -
3
Redirect user ke
data.payment_instructions.spinopay_checkout_url. -
4
User pilih metode & bayar di halaman SpinoPay → otomatis kembali ke
success_redirect_urlAnda.
payment_flow: "DIRECT"
Buat Tampilan Bayar Sendiri di Aplikasi
Cocok bila Anda ingin user tetap berada di UI aplikasi Anda sendiri (mis. POS, mobile app, atau checkout custom Laravel/Vue).
-
1
Tampilkan daftar channel dari
GET /api/v1/payment-channelsbeserta total biaya. -
2
Kirim request
DIRECTdenganchannel_codeyang dipilih user. -
3
Simpan
reference_id,xendit_id, danamount(total + biaya admin) dari respon. -
4
Render
payment_instructionsdi UI Anda (QR Code, nomor VA, link e-wallet, atau kode kasir), lalu tunggu webhookorder.paid.
Field data.payment_instructions per Kategori Channel
Jika Anda membangun halaman pembayaran custom sendiri (Opsi B), gunakan field berikut untuk ditampilkan ke user:
| Kategori Channel | Key di payment_instructions |
Apa yang Harus Dilakukan Developer? |
|---|---|---|
| Semua Mode (Fallback) | spinopay_checkout_url |
Selalu tersedia. Redirect user ke URL ini bila tidak memakai UI custom. |
QRIS (QRIS) |
qr_string |
Ubah string QR menjadi gambar QR Code di halaman Anda (pakai SVG/Canvas QR generator) + tampilkan data.amount & data.expires_at. |
Virtual Account (BCA, BRI, MANDIRI, dll.) |
bank_code, virtual_account_number |
Tampilkan nama bank, nomor Virtual Account dengan tombol Salin, serta nominal tepat data.amount. |
E-Wallet (GOPAY, OVO, SHOPEEPAY) |
ewallet_redirect_url |
Sediakan tombol bayar atau redirect otomatis user ke URL aplikasi e-wallet tersebut. |
Gerai Retail (INDOMARET, ALFAMART) |
retail_outlet_name, payment_code |
Tampilkan kode bayar untuk ditunjukkan ke kasir gerai sebelum expires_at. |
{
"success": true,
"is_idempotent_replay": false,
"data": {
"reference_id": "SPN-01JABC123XYZ",
"external_order_id": "LMS-INV-2026-0091",
"xendit_id": null,
"status": "PENDING",
"payment_flow": "HOSTED",
"subtotal_amount": 250000,
"fee_amount": 0,
"amount": 250000,
"payment_instructions": {
"spinopay_checkout_url": "https://pay.spinotek.com/pay/SPN-01JABC123XYZ"
},
"expires_at": "2026-11-15T09:00:00+00:00"
}
}
Menerima Webhook Pelunasan di Aplikasi Anda
Baik Anda memakai Opsi A (Link SpinoPay) maupun Opsi B (Halaman Custom), saat pelanggan menyelesaikan pembayaran, SpinoPay otomatis mengirim HTTP POST ke webhook_url aplikasi Anda. Jika server Anda sempat timeout/error, SpinoPay otomatis mengirim ulang hingga 5 kali.
routes/api.php (misal POST /api/webhooks/spinopay) agar bebas dari pengecekan CSRF token. Jika ditaruh di routes/web.php, kecualikan path-nya pada validateCsrfTokens(except: [...]) di bootstrap/app.php.
// 1. Daftarkan di routes/api.php:
// Route::post('/webhooks/spinopay', [SpinoPayWebhookController::class, 'handle']);
// 2. Method handle() pada SpinoPayWebhookController.php:
public function handle(Request $request)
{
$timestamp = (string) $request->header('X-Spinopay-Timestamp', '');
$signature = (string) $request->header('X-Spinopay-Signature', '');
$rawBody = $request->getContent();
$secret = (string) config('services.spinopay.webhook_secret');
$expectedSignature = hash_hmac('sha256', "{$timestamp}.{$rawBody}", $secret);
if (! hash_equals($expectedSignature, $signature)) {
return response()->json(['message' => 'Invalid signature'], 401);
}
$event = $request->input('event'); // order.paid | order.expired | order.failed
$externalOrderId = $request->input('data.external_order_id');
$order = Order::where('invoice_number', $externalOrderId)->first();
if (! $order) {
return response()->json(['message' => 'Order not found'], 404);
}
// Idempotent check: abaikan bila order sudah pernah ditandai PAID
if ($event === 'order.paid' && $order->status !== 'PAID') {
$order->update([
'status' => 'PAID',
'payment_method' => $request->input('data.payment_method'),
'paid_at' => now(),
]);
// TODO: aktifkan kelas LMS / cetak struk POS / kirim notifikasi ke user
}
return response()->json(['received' => true]);
}
Cek Status Manual & Anti-Duplikasi Order
Jika user me-refresh halaman atau klik bayar berulang kali pada external_order_id yang sama, SpinoPay menjaga agar transaksi tidak ganda. Anda juga bisa memeriksa status kapan saja menggunakan GET /api/v1/orders/{identifier}?sync=1 memakai salah satu dari 3 ID (external_order_id, reference_id, atau xendit_id).
| Kondisi Saat Memanggil POST /orders | HTTP Status | Respon SpinoPay |
|---|---|---|
| Order baru | 201 Created |
Membuat tagihan baru dan mengembalikan instruksi bayar. |
| Masih PENDING (klik ulang) | 200 OK |
Mengembalikan link/instruksi bayar yang sudah ada (is_idempotent_replay: true). |
| Sudah PAID | 409 Conflict |
Menolak tagihan ulang (ORDER_ALREADY_PAID) agar tidak terjadi double payment. |
| Sudah EXPIRED | 201 Created |
Membuat sesi pembayaran baru dengan reference_id baru. |
// Cek status terbaru ke Xendit bila webhook belum masuk
$status = Http::withHeaders([
'X-Api-Key' => config('services.spinopay.api_key'),
])->get(config('services.spinopay.base_url') . "/api/v1/orders/{$order->invoice_number}", [
'sync' => 1,
])->json('data.status'); // PENDING | PAID | EXPIRED | FAILED