Arsip dokumentasi v2.0.0. Untuk package v3.x, lihat dokumentasi terbaru.

Error Handling

Tidak semua transaksi akan berhasil. Pelanggan bisa salah input, saldo tidak cukup, atau server Duitku sedang bermasalah. Halaman ini menjelaskan cara menangani semua kemungkinan error dengan baik.

🤔 Kenapa Error Handling Penting?

Tanpa error handling yang baik:

❌ Aplikasi kamu crash saat Duitku mengembalikan error
❌ User melihat halaman error yang tidak informatif
❌ Kamu tidak tahu apa yang salah (susah debugging)

Dengan error handling yang baik:

✅ Aplikasi kamu tetap berjalan normal
✅ User mendapat pesan error yang jelas
✅ Kamu bisa melacak dan memperbaiki masalah

🛡️ Custom Exceptions

SDK ini menyediakan exception spesifik agar kamu bisa menangani setiap jenis error secara berbeda.

Daftar Exceptions

Exception	Kapan Terjadi?	Contoh
`DuitkuException`	Base exception untuk semua error SDK	—
`DuitkuApiException`	API Duitku mengembalikan error	Order ID sudah dipakai, email invalid
`InsufficientFundsException`	Saldo merchant tidak cukup (Disbursement)	Mau transfer tapi saldo kosong
`InvalidSignatureException`	Signature callback tidak valid	Ada yang mengirim callback palsu

Contoh Penggunaan

php

use Duitku\Laravel\Exceptions\DuitkuApiException;
use Duitku\Laravel\Exceptions\InsufficientFundsException;
use Duitku\Laravel\Exceptions\InvalidSignatureException;

// === Contoh 1: Checkout ===
try {
    $response = Duitku::checkout($request);
    return redirect($response->paymentUrl);

} catch (DuitkuApiException $e) {
    // Error dari API Duitku (400, 401, 404, 409, dll)
    return back()->with('error', 'Gagal membuat pembayaran: ' . $e->getMessage());
}

// === Contoh 2: Disbursement ===
try {
    $result = Duitku::disbursement()
        ->transfer()
        ->execute($info)
        ->throwIfFailed();

} catch (InsufficientFundsException $e) {
    // Saldo merchant tidak cukup
    return back()->with('error', 'Transfer gagal: saldo merchant tidak cukup.');

} catch (DuitkuApiException $e) {
    // Error lainnya
    $kodeError = $e->getDuitkuCode(); // Kode error asli dari Duitku
    return back()->with('error', 'Transfer gagal: ' . $e->getMessage());
}

// === Contoh 3: Callback ===
try {
    Duitku::handleCallback($request->all());
    return response('OK');

} catch (InvalidSignatureException $e) {
    // Signature tidak valid — kemungkinan callback palsu!
    Log::warning('Duitku callback palsu terdeteksi!', $request->all());
    abort(403);
}

📋 Referensi Error Code

SDK menyediakan class ErrorCode yang berisi semua kode error dari dokumentasi resmi Duitku.

HTTP Status Codes (dari API Duitku)

HTTP Code	Constant	Penjelasan
200	`ErrorCode::HTTP_SUCCESS`	✅ Request berhasil
400	`ErrorCode::HTTP_BAD_REQUEST`	❌ Ada kesalahan di request (parameter salah)
401	`ErrorCode::HTTP_UNAUTHORIZED`	❌ Signature/credential salah
404	`ErrorCode::HTTP_NOT_FOUND`	❌ Merchant tidak ditemukan
409	`ErrorCode::HTTP_CONFLICT`	❌ Konflik (order ID duplikat, amount tidak cocok)
500	`ErrorCode::HTTP_SERVER_ERROR`	❌ Error internal server Duitku

Error Messages (dari HTTP 400 Bad Request)

Constant	Pesan	Solusi
`ErrorCode::MIN_PAYMENT`	Minimum Payment 10000 IDR	Naikkan nominal minimal Rp 10.000
`ErrorCode::MAX_PAYMENT`	Maximum Payment exceeded	Turunkan nominal di bawah batas
`ErrorCode::PAYMENT_METHOD_REQUIRED`	paymentMethod is mandatory	Isi parameter paymentMethod
`ErrorCode::ORDER_ID_REQUIRED`	merchantOrderId is mandatory	Isi parameter merchantOrderId
`ErrorCode::ORDER_ID_TOO_LONG`	length of merchantOrderId can't > 50	Pendekkan order ID (max 50 char)
`ErrorCode::INVALID_EMAIL`	Invalid Email Address	Perbaiki format email
`ErrorCode::EMAIL_TOO_LONG`	length of email can't > 50	Pendekkan email (max 50 char)
`ErrorCode::PHONE_TOO_LONG`	length of phoneNumber can't > 50	Pendekkan nomor HP (max 50 char)
`ErrorCode::VA_NAME_REQUIRED`	Customer VA Name must not be empty...	Isi parameter customerVaName

Error Messages Lainnya

Constant	HTTP	Pesan	Solusi
`ErrorCode::WRONG_SIGNATURE`	401	Wrong signature	Cek API Key dan Merchant Code
`ErrorCode::MERCHANT_NOT_FOUND`	404	Merchant not found	Cek Merchant Code
`ErrorCode::PAYMENT_CHANNEL_NOT_AVAILABLE`	404	Payment channel not available	Metode bayar belum aktif, hubungi Duitku
`ErrorCode::AMOUNT_MISMATCH`	409	Payment amount must be equal to all item price	Total itemDetails harus = amount

Error Khusus POP

Constant	Pesan	Solusi
`ErrorCode::POP_AMOUNT_DIFFERENT`	Amount is different please try again later	Jangan kirim request ulang dengan nominal berbeda tapi order ID sama
`ErrorCode::POP_SAVE_CARD_NOT_AVAILABLE`	SaveCardToken is not available	Akun belum mendukung tokenisasi, hubungi Duitku
`ErrorCode::POP_TRANSACTION_IN_PROGRESS`	The transaction is still in progress	Request sebelumnya masih diproses, tunggu sebentar

API Response Codes (Callback & Redirect)

Constant	Kode	Context	Arti
`ErrorCode::SUCCESS`	`'00'`	Callback & Redirect	✅ Transaksi berhasil
`ErrorCode::PENDING`	`'01'`	Redirect	⏳ Belum terbayar (pending)
`ErrorCode::FAILED`	`'02'`	Callback & Redirect	❌ Gagal / dibatalkan

Helper Methods

php

use Duitku\Laravel\Enums\ErrorCode;

// Cek status code
ErrorCode::isSuccess('00');   // true
ErrorCode::isPending('01');   // true
ErrorCode::isFailed('02');    // true

// Deskripsi HTTP code
ErrorCode::describeHttp(400);
// → 'Ada kesalahan pada saat mengirimkan permohonan pada API.'

// Deskripsi status code
ErrorCode::describeStatus('00', 'callback');
// → 'Transaksi telah sukses terbayarkan.'

ErrorCode::describeStatus('01', 'redirect');
// → 'Transaksi belum terbayar (Pending).'

🔍 Debugging Tips

1. Aktifkan Logging

Set DUITKU_LOG_CHANNEL di .env untuk mencatat semua request:

env

DUITKU_LOG_CHANNEL=duitku

Semua request ke Duitku API akan dicatat di log file, termasuk URL dan body request.

2. Cek Response Asli

Jika menggunakan try-catch dengan DuitkuApiException:

php

catch (DuitkuApiException $e) {
    $kodeAsli = $e->getDuitkuCode();  // Kode error dari Duitku
    $pesan = $e->getMessage();         // Pesan error
    Log::error('Duitku error', ['code' => $kodeAsli, 'message' => $pesan]);
}

3. Gunakan Sandbox

Selalu test di Sandbox terlebih dahulu. Duitku menyediakan kredensial test untuk berbagai skenario (sukses, gagal, pending).

Lanjut ke fitur transfer dana di Disbursement. 💸

Error Handling ​

🤔 Kenapa Error Handling Penting? ​

🛡️ Custom Exceptions ​

Daftar Exceptions ​

Contoh Penggunaan ​

📋 Referensi Error Code ​

HTTP Status Codes (dari API Duitku) ​

Error Messages (dari HTTP 400 Bad Request) ​

Error Messages Lainnya ​

Error Khusus POP ​

API Response Codes (Callback & Redirect) ​

Helper Methods ​

🔍 Debugging Tips ​

1. Aktifkan Logging ​

2. Cek Response Asli ​

3. Gunakan Sandbox ​