3. Resilient ERP Integration & Edge Case 'Late Payment': Mengatasi Socket Hang-Up RPC dan Pembayaran Lintas Sesi

Dalam membangun sistem Payment Middleware yang menjembatani Payment Gateway eksternal dengan Sistem Core ERP internal, kita berhadapan dengan dua sistem yang memiliki sifat dan siklus hidup yang sangat bertolak belakang:

1. Di sisi Upstream (Core ERP): Kita menggunakan koneksi RPC berbasis sesi persisten (singleton instance) yang sewaktu-waktu dapat mengalami putus koneksi sepihak (socket hang up atau ECONNRESET) ketika jaringan internal berfluktuasi atau saat worker ERP di-restart.
2. Di sisi Downstream (Payment Gateway): Setiap kanal pembayaran (Virtual Account, QRIS, E-Wallet, Kartu Kredit) memiliki durasi sesi mandiri di halaman penyedia gateway yang tidak selalu sinkron 1:1 dengan timer kedaluwarsa (expiry timer) di database lokal kita.

Artikel ketiga dari seri portofolio engineering ini membahas dua studi kasus nyata yang saya selesaikan di proyek ini:

1. Membangun Higher-Order Retry & Auto-Reconnect Wrapper untuk memulihkan koneksi soket Core ERP secara otomatis tanpa menjatuhkan transaksi.
2. Menangani Edge Case "Late Payment" pada Kanal Sesi Panjang (Kartu Kredit) ketika pengguna menyelesaikan pembayaran di sisi Gateway beberapa menit setelah transaksi di database lokal kita dinyatakan EXPIRED.

Studi Kasus 1: Mengatasi Socket Hang-Up & ECONNRESET pada Koneksi Singleton RPC

1. Masalah yang Dihadapi

Integrasi ke Core ERP menggunakan klien RPC yang diinisialisasi satu kali sebagai Singleton Instance saat aplikasi menyala. Masalah muncul setelah aplikasi berjalan selama berjam-jam:

• Reverse Proxy atau Firewall di depan server Core ERP menutup koneksi TCP yang sempat idle secara diam-diam.
• Karena state koneksi di memori aplikasi masih tercatat aktif (isConnected = true), aplikasi mengira soket masih sehat.
• Begitu ada transaksi pembayaran masuk dan sistem memanggil fungsi RPC untuk membuat invoice atau melunasi jurnal, muncul error jaringan: socket hang up, ECONNRESET, atau EPIPE.

Jika error ini tidak ditangkap dan sesi tidak di-reset, maka panggilan-panggilan berikutnya juga akan terus gagal karena aplikasi terus menggunakan sesi soket yang sudah mati.

2. Solusi: Forced Reconnect & Higher-Order Transient Retry Pattern

Untuk menyelesaikan masalah ini secara bersih dan reusable di seluruh modul, saya menerapkan pola Higher-Order Retry Function yang dikombinasikan dengan mekanisme forced reconnect.

Fungsi pembungkus (wrapper) ini secara spesifik membedakan antara Transient Network Error (yang wajib di-reconnect dan di-retry) dengan Business Logic Error dari ERP (seperti kesalahan validasi data, yang harus langsung dilempar tanpa retry):

// Prototype Konseptual: Transient Socket Retry & Auto-Reconnect Wrapper
const TRANSIENT_SOCKET_ERRORS = [
  'ECONNRESET',
  'ECONNREFUSED',
  'EPIPE',
  'ETIMEDOUT',
];

async function withRpcRetry<T>(
  operation: () => Promise<T>,
  rpcProvider: RpcConnectionProvider,
  maxRetries = 1,
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
    try {
      return await operation();
    } catch (err: any) {
      const isSocketDrop =
        TRANSIENT_SOCKET_ERRORS.includes(err?.code) ||
        /socket hang up|ECONNRESET|ETIMEDOUT/i.test(err?.message || '');

      if (isSocketDrop && attempt <= maxRetries) {
        // Paksa reset state koneksi & lakukan handshake ulang ke Core ERP
        await rpcProvider.forceReconnect();
        await sleep(1000); // Jeda 1 detik sebelum mengulang operasi
        continue;
      }
      throw err; // Lempar langsung jika merupakan error validasi bisnis
    }
  }
  throw new Error('RPC retries exhausted');
}

Dengan pola desain ini, setiap kali soket terputus di tengah malam atau saat terjadi gangguan jaringan sesaat, aplikasi secara otomatis memulihkan koneksinya sendiri (self-healing connection) dalam waktu 1 detik tanpa menggagalkan transaksi pelanggan yang sedang berlangsung.

Studi Kasus 2: Edge Case "Late Payment" pada Kanal Pembayaran Berdurasi Panjang (Kartu Kredit)

Kasus kedua ini adalah contoh nyata mengapa merancang sistem pembayaran membutuhkan pemahaman mendalam tentang perilaku pengguna dan perbedaan session lifecycle antar penyedia gateway.

1. Kronologi Masalah di Lapangan (The 35th-Minute Problem)

Pada fitur Master Payment Link, pelanggan diberikan sebuah tautan pembayaran yang memiliki masa berlaku lokal (misalnya expired_at = 30 menit). Selama 30 menit tersebut, pelanggan bebas memilih metode pembayaran (VA, QRIS, E-Wallet, atau Kartu Kredit).

Namun, saat mengintegrasikan kanal Kartu Kredit, kami menemukan skenario edge case kritis berikut:

Perhatikan celah waktunya:

• Menit ke-0: Payment Link dibuat dengan batas waktu lokal expired_at = 30 menit.
• Menit ke-29: Pelanggan membuka link, memilih Credit Card, dan menekan tombol Pay. Pihak Payment Gateway meng-generate sesi halaman pembayaran Kartu Kredit yang aktif selama 30 menit ke depan di sisi mereka (artinya sesi di Gateway hidup sampai Menit ke-59!).
• Menit ke-30: Cron job lokal kita berjalan. Karena batas waktu lokal sudah lewat, status transaksi di database kita diubah dari ACTIVE menjadi EXPIRED. (Link pembayaran lokal sudah dikunci dan tidak bisa dibuka lagi).
• Menit ke-35: Pelanggan yang sejak menit ke-29 sudah berada di halaman input kartu kredit milik Gateway selesai memasukkan kode OTP 3D-Secure, dan dana kartu kredit pelanggan berhasil terpotong (LUNAS)!
• Detik berikutnya: Payment Gateway mengirimkan Webhook Callback SUCCESS ke backend kita.

2. Bahaya Jika Menggunakan Validasi State yang Kaku

Jika webhook handler secara kaku menolak setiap callback yang masuk ke transaksi berstatus EXPIRED:

1. Saldo kartu kredit pelanggan sudah terpotong di bank.
2. Backend menolak webhook karena status di database lokal sudah EXPIRED.
3. Invoice di Core ERP tidak terbuat dan layanan pelanggan tidak aktif (uang menggantung / unrecorded revenue).

3. Solusi Desain: State Machine yang Mengakomodasi Late Payment Override

Untuk memastikan uang pelanggan tidak pernah hilang atau menggantung, saya merancang aturan state transition pada callback handler sebagai berikut:

1. Jangan Memblokir Transaksi EXPIRED Saat Menerima Callback SUCCESS:
   • Satu-satunya kondisi yang boleh menghentikan pemrosesan callback SUCCESS adalah jika transaksi di database lokal sudah berstatus SUCCESS (untuk mencegah double processing / overpayment).
   • Status EXPIRED di menit ke-30 tetap berfungsi menjaga agar pelanggan tidak bisa membuka kembali halaman Master Payment Link untuk meng-generate metode pembayaran baru.
2. Automatic State Recovery (EXPIRED $\rightarrow$ SUCCESS):
   • Ketika Gateway mengirimkan callback terverifikasi bahwa dana telah diterima, sistem secara sah melakukan override status transaksi lokal dari EXPIRED menjadi SUCCESS, mencatat waktu lunas, dan menyimpan nomor referensi gateway.
3. Eksekusi Pipeline Penuh ke Core ERP & Partner:
   • Setelah status dipulihkan menjadi SUCCESS, sistem langsung melanjutkan eksekusi pembuatan invoice dan pencatatan pelunasan di Core ERP, serta mengirimkan notifikasi webhook ke sistem partner.

// Prototype Konseptual: State Transition dengan Dukungan Late Payment Recovery
async function onPaymentSuccessWebhook(
  orderCode: string,
  payload: WebhookPayload,
) {
  const order = await db.orders.findByCode(orderCode);

  // 1. Idempotency Guard: Hanya blokir jika transaksi MEMANG SUDAH SUKSES
  if (order.status === 'SUCCESS') {
    return { acknowledged: true, reason: 'ALREADY_SETTLED' };
  }

  // 2. Observability untuk kasus Late Payment (uang masuk saat status lokal EXPIRED)
  if (order.status === 'EXPIRED') {
    logger.warn(
      `[LatePaymentRecovery] Memulihkan order ${orderCode} dari EXPIRED ke SUCCESS`,
    );
  }

  // 3. Pulihkan status menjadi SUCCESS & jalankan sinkronisasi penuh ke ERP
  await db.orders.markAsPaid(order.id, payload.referenceNo);
  await erpSyncService.createAndSettleInvoice(order.id);
  await partnerWebhookService.notifyDownstream(order.id);

  return { acknowledged: true };
}

4. Pelajaran Utama (Key Takeaways)

1. Bungkus Koneksi Singleton RPC dengan Transient Error Detector:
   Koneksi TCP jangka panjang pasti akan terputus suatu saat. Memisahkan deteksi error jaringan (ECONNRESET, socket hang up, EPIPE) ke dalam wrapper higher-order membuat seluruh sistem tahan banting terhadap gangguan jaringan sesaat.
2. Pahami Perbedaan Timer Lokal vs Timer Sesi Payment Gateway:
   Waktu kedaluwarsa di sistem Anda hanya mengontrol kapan pengguna boleh memulai sesi pembayaran, bukan kapan pengguna menyelesaikan input OTP di halaman pihak ketiga.
3. Sumber Kebenaran Finansial Adalah Dana yang Masuk:
   Selama Payment Gateway mengonfirmasi secara kriptografis bahwa dana telah berhasil diterima (SUCCESS), sistem backend wajib memulihkan status transaksi (EXPIRED $\rightarrow$ SUCCESS) dan menyelesaikan penjurnalan akuntansi agar tidak ada dana pelanggan yang terkatung-katung.

Pada Part 4 berikutnya, kita akan membedah bagaimana saya membangun modul Two-Phase Automated Reconciliation Worker yang secara otomatis memulihkan riwayat pembayaran yang hilang di Core ERP dan menyelesaikan pelunasan tertunda dengan resolusi mode jurnal dinamis.