Download the PHP package sikeu/laravel-payment without Composer

SIKEU Laravel Payment

Laravel package untuk integrasi SIKEU Payment Gateway. Package ini hanya menyediakan service layer; controller, route, dan callback handler dibuat di aplikasi Laravel Anda.

Requirements

• PHP 8.0+
• Laravel 9.x sampai 13.x
• Guzzle HTTP Client 7.x

Instalasi

Tambahkan ke .env:

Lalu refresh config:

Alur Yang Direkomendasikan

1. Ambil daftar service_category lewat getAvailableServices().
2. Ambil daftar revenue_account_code lewat getRevenueAccountCodes().
3. Simpan atau tampilkan dua daftar itu di aplikasi Anda.
4. Saat membuat payment request, kirim hanya nilai yang berasal dari dua method tersebut.
5. Cek status dengan checkPaymentRequest() atau proses notifikasi callback dari SIKEU.

service_category dan revenue_account_code tidak boleh di-hardcode berdasarkan asumsi. Dua field ini harus mengikuti master data dari SIKEU.

Implementasi Minimal

Controller paling sederhana yang siap dipakai:

Route yang direkomendasikan:

Contoh request:

Nilai UKT dan 411100 di atas hanya contoh. Ambil nilai validnya dari SIKEU melalui getAvailableServices() dan getRevenueAccountCodes().

QRIS

Jika ingin membuat payment QRIS, gunakan method khusus berikut:

Response QRIS akan mengandung data seperti paymentRequestId, qrId, qrContent, dan expiryDate/qrExpiryDate.

Callback

Setelah pembayaran diproses, SIKEU dapat mengirim HTTP POST ke endpoint callback aplikasi Anda. Callback ini dipakai untuk sinkronisasi status pembayaran tanpa harus terus melakukan polling.

Alur yang direkomendasikan:

1. Buat payment request dan simpan paymentRequestId di database lokal.
2. Tampilkan VA atau QRIS ke user.
3. Setelah user membayar, SIKEU mengirim callback ke aplikasi Anda.
4. Aplikasi Anda memverifikasi signature, mencari data berdasarkan paymentRequestId, lalu mengubah status pembayaran.
5. Jika perlu, jalankan proses lanjutan seperti aktivasi tagihan, notifikasi, atau queue job.

Tambahkan callback URL yang bisa diakses publik:

Sampaikan ke admin SIKEU bahwa URL callback ini harus didaftarkan di sisi SIKEU agar notifikasi pembayaran dapat dikirim ke aplikasi Anda.

Route yang direkomendasikan:

Header penting yang perlu divalidasi:

• X-Timestamp
• X-Signature

Contoh middleware validasi signature:

Daftarkan middleware tersebut dengan alias sikeu.signature sesuai versi Laravel yang Anda gunakan.

Contoh payload callback:

Contoh handler callback:

Hal penting saat implementasi callback:

• Endpoint callback jangan dipasang auth login biasa; cukup lindungi dengan validasi signature.
• Selalu lakukan idempotency check agar callback yang terkirim ulang tidak memproses pembayaran dua kali.
• Jika paymentRequestId tidak ditemukan, tetap balas 200 OK agar SIKEU tidak terus retry.
• Proses berat seperti sinkronisasi akademik atau kirim notifikasi sebaiknya dikirim ke queue.
• Usahakan response callback cepat; jangan menunggu proses panjang sebelum membalas 200 OK.

Method Yang Tersedia

Master Data

• getAvailableServices(): array Ambil daftar service_category yang valid dari SIKEU. Gunakan nilai code dari response.
• getRevenueAccountCodes(): array Ambil daftar revenue_account_code yang valid dari SIKEU. Gunakan nilai code dari response.

Payment Request

• createPaymentRequest(array $data): array Membuat payment request. Field utama: service_category, customer_no, customer_name, amount, description, revenue_account_code. Field opsional: provider, attributes.
• getPaymentRequest(string $paymentRequestId): array Ambil detail payment request.
• checkPaymentRequest(string $paymentRequestId): array Cek status payment request.
• cancelPaymentRequest(string $paymentRequestId): array Batalkan payment request.

QRIS

• createQrisPaymentRequest(array $data): array Membuat payment request QRIS. Jika provider tidak dikirim, package memakai SIKEU_DEFAULT_QRIS_PROVIDER.
• checkQrisPaymentStatus(string $paymentRequestId): array Cek status pembayaran QRIS.

Catatan Penting

• service_category wajib berasal dari getAvailableServices().
• revenue_account_code wajib berasal dari getRevenueAccountCodes().
• amount akan dikirim sebagai integer.
• Default provider diambil dari config/sikeu.php.
• Logging request/response aktif melalui config package.

License

MIT