Spinotek
SpinoPay
Panduan Developer Aplikasi Klien (Tanpa Login)

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.

Buka API Reference (Scramble)
Langkah 1

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.
.env
ENV
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
config/services.php
PHP
// 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'),
],
Langkah 2 (Opsional)

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).

CheckoutController.php
PHP
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
Langkah 3

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.

HOSTED (Pakai Halaman SpinoPay)

Tidak perlu bikin tampilan pilih bank/QRIS sendiri. Anda cukup redirect user ke spinopay_checkout_url.

DIRECT (Bikin Halaman Custom Sendiri)

Sertakan channel_code (mis. QRIS / BCA), lalu tampilkan QR atau nomor VA langsung di UI aplikasi Anda.

INVOICE (Halaman Xendit)

Redirect user langsung ke halaman invoice bawaan Xendit lewat xendit_invoice_url.

app/Http/Controllers/CheckoutController.php
PHP
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']);
}
Langkah 4 (Penting)

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:

Opsi A • Tanpa UI Sendiri 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. 1 Kirim request HOSTED (cukup isi external_order_id & amount).
  2. 2 Simpan data.reference_id ke order lokal Anda supaya bisa dicari kembali nanti.
  3. 3 Redirect user ke data.payment_instructions.spinopay_checkout_url.
  4. 4 User pilih metode & bayar di halaman SpinoPay → otomatis kembali ke success_redirect_url Anda.
Opsi B • Halaman Custom 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. 1 Tampilkan daftar channel dari GET /api/v1/payment-channels beserta total biaya.
  2. 2 Kirim request DIRECT dengan channel_code yang dipilih user.
  3. 3 Simpan reference_id, xendit_id, dan amount (total + biaya admin) dari respon.
  4. 4 Render payment_instructions di UI Anda (QR Code, nomor VA, link e-wallet, atau kode kasir), lalu tunggu webhook order.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.
201 Created — response-hosted.json
JSON
{
  "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"
  }
}
Langkah 5

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.

Tips Laravel: Daftarkan route webhook di 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.
SpinoPayWebhookController.php
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]);
}
Langkah 6

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.
OrderStatusCheck.php
PHP
// 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