Bank Integrator KBI

Bab 2Konsep dasar

Enam istilah yang dipakai di seluruh buku.

Layanan standar

Integrator menyediakan tujuh layanan, sama untuk semua bank. Tidak semua bank membuka semuanya (lihat Bab 10).

Dua layanan yang mengubah sesuatu di bank wajib membawa transaction_id dan dicatat di tabel transaksi.

Status standar

Istilah lain

Bab 3Memasang dan menjalankan

Dari folder kosong sampai service menjawab di port 2034.

Prasyarat

• Go 1.25 atau lebih baru.
• MySQL dengan database CMC (icomex di lokal). Integrator membaca r_userid, r_member, r_bank, dan menulis t_log.
• OpenSSL untuk membuat kunci RSA.

Langkah

1. Buat tabel Empat tabel baru; tidak ada tabel atau baris lama yang diubah.

   mysql --default-character-set=utf8mb4 -u root icomex < sql/migration.sql

2. Isi data awal (hanya lokal) Mendaftarkan lima bank yang diarahkan ke simulator, dan tiga contoh aturan routing.

   mysql --default-character-set=utf8mb4 -u root icomex < sql/seed.sql

3. Buat kunci RSA Private key dipakai menandatangani permintaan token. Public key-nya yang diserahkan ke bank.

   openssl genrsa -out keys/kbi-private-dev.pem 2048
   openssl rsa -in keys/kbi-private-dev.pem -pubout -out keys/kbi-public-dev.pem

4. Siapkan .env Salin .env.example menjadi .env, lalu isi sekurangnya DB_USER, DB_NAME, JWT_SECRET, dan rahasia tiap bank. Untuk lokal, hidupkan simulator dengan SIM_ENABLED=1.
5. Jalankan

   go run .

   Untuk pengembangan dengan muat ulang otomatis, gunakan air (konfigurasinya di .air.toml).
6. Periksa

   curl http://localhost:2034/api

   Jawaban yang benar: BANK INTEGRATOR OK.

Isi .env

Rahasia tiap bank

Rahasia tidak disimpan di database. Semuanya dibaca dari environment dengan pola BANK_<ID>_<NAMA>, di mana <ID> adalah kode bank di integrator.

BANK_BTN_CLIENT_SECRET=…
BANK_BTN_PRIVATE_KEY_FILE=keys/kbi-private-btn.pem
BANK_BSI_PRIVATE_KEY_FILE=keys/kbi-private-bsi.pem
BANK_BSI_API_KEY=…

Bab 4Login dan hak akses

Siapa yang boleh memanggil integrator, dan boleh melakukan apa.

Login

Integrator memakai user exchange yang sama dengan cmc-api2: baris r_userid yang aktif dengan tipe A (exchange admin) atau V (surveillance).

curl -X POST http://localhost:2034/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<userid>","password":"<password>"}'

{
  "success": true,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIs…",
  "user": { "userid": "…", "name_userid": "…", "member_id": "IX", "tipe_userid": "A" }
}

Setiap rute lain butuh header Authorization: Bearer <token>. Token berlaku selama JWT_EXPIRES.

Peran

Pembatasan lain

• IP whitelist — bila IP_ALLOW diisi, hanya alamat itu yang dilayani; yang lain dijawab 403.
• Rate limit — melebihi RATE_MAX permintaan per RATE_WINDOW dijawab 429.
• Profil — GET /me menampilkan user yang sedang login dan boleh_transaksi.

Bab 5Mengatur koneksi bank

Mendaftarkan bank, mengisi identitasnya, dan menguji koneksinya.

Setiap bank yang dilayani punya satu baris di r_integrator_bank, dikelola lewat rute /intbank. Perubahan langsung berlaku tanpa restart.

Melihat adaptor yang tersedia

GET/adapter menampilkan adaptor yang ada di kode beserta endpoint bank untuk tiap layanan. Kolom confirmed menunjukkan apakah path itu sudah berasal dari dokumen bank.

Mendaftarkan bank

POST /api/intbank
{
  "id": "BTN",
  "bank_code": "200",
  "nama": "Bank BTN",
  "adapter": "BTN",
  "env": "UAT",
  "base_url": "https://devapi.btn.co.id",
  "client_key": "<client id dari bank>",
  "partner_id": "<partner id dari bank>",
  "channel_id": "<channel id>",
  "norek": "<rekening settlement KBI>",
  "nama_rek": "KLIRING BERJANGKA INDONESIA",
  "va_prefix": "6775",
  "opsi": { "origin": "https://<domain KBI>" }
}

Isian opsi per bank

Memeriksa kesiapan

GET/intbank menampilkan tiap bank beserta keadaannya:

Menguji koneksi

POST /api/intbank/BTN/ping

Integrator meminta token baru ke bank. Jawaban "ok": true berarti alamat, client key, private key, dan bentuk waktu sudah diterima bank. Ini langkah pertama setiap kali menyambung ke lingkungan baru.

Mengubah, menonaktifkan, menghapus

• PUT/intbank/:id — kirim seluruh field (bukan sebagian). Token lama dibuang; token baru diambil saat panggilan berikutnya.
• Menonaktifkan: "aktif": 0. Bank tidak lagi dipilih routing dan permintaan ke bank itu ditolak.
• DELETE/intbank/:id — hanya untuk bank yang belum punya transaksi. Bank yang sudah dipakai cukup dinonaktifkan.
• POST/intbank-reload — memuat ulang konfigurasi dan rahasia, misalnya setelah berkas kunci diganti di server.

Bab 6Mengatur routing

Bagaimana integrator memilih bank untuk satu permintaan.

Urutan pemilihan

1. Field bank di permintaan — kode integrator (BTN) atau kode bank BI (200).
2. Aturan routing di tabel r_integrator_route: yang cocok layanan dan mata uangnya, prioritas terkecil lebih dulu, dan banknya mendukung layanan itu.
3. DEFAULT_BANK di .env.
4. Bila hanya ada satu bank aktif yang mendukung layanan itu, bank itu dipakai.

Bila tidak ada yang cocok, permintaan ditolak 400 dengan pesan "bank tujuan belum ditentukan". Jalur yang dipakai muncul di jawaban sebagai route: request, route, default, atau single.

Membuat aturan

POST /api/route
{ "layanan": "TRANSFER", "mata_uang": "IDR", "bank_id": "BTN", "prioritas": 10, "ket": "Transfer rupiah lewat BTN" }

Menguji tanpa memanggil bank

GET /api/route-uji?layanan=TRANSFER&mata_uang=IDR

{ "Hasil": { "layanan": "TRANSFER", "bank": "BTN", "nama": "Bank BTN", "jalur": "route" } }

Bab 7Layanan transaksi

Tujuh layanan: apa yang dikirim dan apa yang diterima.

Semua rute di bawah /api, metode POST, badan JSON, dan hanya untuk user tipe A. Field berikut berlaku di semua layanan:

Nominal dan nomor rekening boleh dikirim sebagai teks maupun angka; integrator menyimpannya sebagai teks agar digitnya tidak berubah. Nominal memakai titik sebagai desimal, paling banyak dua angka di belakang koma.

7.1 Cek saldo

POST/trx/balance

{ "bank": "MDR", "account_no": "1150006399259" }

account_no boleh dikosongkan; integrator memakai rekening bawaan bank itu. Data yang dikembalikan: account_no, account_name, available_balance, ledger_balance, hold_amount, currency.

7.2 Inquiry rekening tujuan

POST/trx/account-inquiry

{ "bank": "MDR", "beneficiary_account": "1390094033549", "beneficiary_bank": "014" }

Bila beneficiary_bank kosong atau sama dengan bank eksekutor, integrator memakai inquiry internal; selain itu inquiry antarbank. Data: account_no, account_name, bank_code, bank_name, account_status, currency.

7.3 Transfer

POST/trx/transfer

{
  "transaction_id": "TRX-20261007-0001",
  "bank": "BTN",
  "member_id": "IX",
  "beneficiary_account": "1150010883959",
  "beneficiary_bank": "008",
  "beneficiary_name": "PT ANGGOTA KLIRING",
  "amount": "1250000.00",
  "remark": "Pencairan dana"
}

Data yang dikembalikan: bank_reference_no, amount, currency, source_account, beneficiary_account, transaction_date.

7.4 Konfirmasi status

POST/trx/status

{ "transaction_id": "TRX-20261007-0001" }

Berlaku untuk transfer maupun pembuatan VA. Bila transaksi masih PENDING, integrator menanyakan bank dan menerapkan hasilnya. Bila sudah berstatus akhir, jawaban diambil dari catatan tanpa memanggil bank. Untuk sekadar membaca tanpa menanyakan bank, gunakan GET /trx/:transaction_id.

7.5 Mutasi rekening

POST/trx/statement

{ "bank": "MDR", "from_date": "2026-10-01", "to_date": "2026-10-07" }

Rentang paling lama 31 hari. Tanggal tanpa jam pada to_date berarti sampai akhir hari itu. Data: entries (tiap entri berisi date, amount, currency, type = DEBIT/CREDIT, remark, reference_no), total_debit, total_credit.

7.6 Membuat virtual account

POST/trx/va

{
  "transaction_id": "VA-20261007-0001",
  "bank": "BNI",
  "customer_no": "0000001234",
  "va_name": "Anggota Kliring 017",
  "amount": "50000000",
  "va_type": "CLOSED",
  "expired_at": "2026-10-14"
}

Data: va_no, va_name, amount, currency, va_type, expired_at.

7.7 Inquiry virtual account

POST/trx/va-inquiry

{ "bank": "BNI", "va_no": "988291720000001234" }

Data: isi VA ditambah found, paid (sudah dibayar atau belum), dan bila ada paid_amount serta payment_date. VA yang tidak ada dijawab REJECTED dengan found: false.

Bab 8Membaca jawaban

Satu bentuk jawaban untuk semua bank dan semua layanan.

{
  "success": true,
  "message": "Berhasil",
  "Hasil": {
    "request_id": "ITG26100716331629117164",
    "transaction_id": "TRX-20261007-0001",
    "service": "TRANSFER",
    "bank": "BTN",
    "route": "request",
    "bank_service": "transfer-interbank",
    "method": "INTERBANK",
    "status": "SUCCESS",
    "reason": "SUCCESS",
    "retryable": false,
    "bank_response_code": "2001800",
    "bank_response_message": "Successful",
    "bank_reference_no": "…",
    "external_id": "202610071633167457838676493552",
    "http_status": 200,
    "attempts": 1,
    "latency_ms": 184,
    "duplicate": false,
    "timestamp": "2026-10-07T16:33:16+07:00",
    "data": { "amount": "1250000.00", "currency": "IDR", "beneficiary_account": "1150010883959" }
  }
}

Kode HTTP

HTTP 200 berarti integrator berhasil memberi jawaban standar — bukan berarti transaksinya berhasil. Kode lain hanya untuk kesalahan di tingkat integrator, sebelum bank disentuh.

Kode alasan yang sering muncul

Daftar lengkap pemetaan kode bank ke status tersedia di GET /ref/status.

Bab 9Idempotency, retry, dan PENDING

Aturan yang mencegah transaksi ganda. Bab terpenting bagi pengembang Aplikasi Kliring.

Apa yang harus dilakukan Aplikasi Kliring

Bagaimana ulangan ditangani

Mengirim ulang transaction_id yang sama tidak pernah menghasilkan instruksi kedua ke bank, kecuali percobaan sebelumnya terbukti belum diproses.

Retry otomatis

Integrator mengulang sendiri hingga RETRY_MAX kali, dengan jeda yang berlipat, hanya bila bank pasti belum menerima instruksi: koneksi gagal sebelum permintaan terkirim, token tidak diperoleh, atau bank menjawab 429. Timeout setelah permintaan terkirim tidak pernah diulang.

Konfirmasi otomatis

• Transaksi PENDING dijadwalkan untuk dikonfirmasi menurut PENDING_CHECK_SCHEDULE (bawaan: 30 detik, 1 menit, 2, 5, 10, 30 menit, lalu tiap jam).
• Transfer dikonfirmasi lewat cek status transfer; pembuatan VA lewat inquiry VA.
• Jawaban "tidak ditemukan" baru dianggap final setelah NOT_FOUND_GRACE (5 menit) sejak pengiriman terakhir. Saat itu transaksi menjadi FAILED NOT_FOUND_AT_BANK dan boleh dikirim ulang.
• Setelah PENDING_CHECK_MAX kali tanpa kepastian, konfirmasi otomatis berhenti. Transaksi tetap PENDING dan terhitung pada perlu_cek_manual di monitoring — operator menanyakannya ke bank.
• Bila service mati di tengah panggilan ke bank, transaksinya dipulihkan menjadi PENDING INTERRUPTED lalu dikonfirmasi seperti biasa.

Bab 10Adaptor tiap bank

Layanan yang dibuka dan kekhususan yang sudah ditangani.

Layanan per bank

✓ path dari dokumen bank · ○ tersedia tetapi path belum terkonfirmasi · — tidak dibuka

Kekhususan yang ditangani adaptor

Menimpa path

PUT /api/intbank/BTN
{ …seluruh field…, "path_override": { "transfer-status": "/snap/v1/transfer/status" } }

Kunci endpoint yang berlaku: balance-inquiry, account-inquiry-internal, account-inquiry-external, transfer-intrabank, transfer-interbank, transfer-skn, transfer-rtgs, transfer-status, bank-statement, va-create, va-inquiry.

Mengirim field khusus bank

Field yang hanya dikenal satu bank dikirim lewat extra; integrator meneruskannya sebagai additionalInfo. Contoh: BI-FAST di BRI memakai "extra": {"serviceCode": "80", …}; field VA Billing BSI seperti biaya, jadwal, dan KYC juga lewat extra. Isian dari Kliring menang atas bawaan adaptor.

Bab 11Log, audit, dan monitoring

Menelusuri satu transaksi dan memantau kesehatan integrasi.

Daftar transaksi

GET/trx — transfer dan pembuatan VA, terbaru di atas.

Rincian satu transaksi — audit trail

GET/trx/:transaction_id menampilkan transaksi beserta panggilan: seluruh panggilan ke bank yang pernah dilakukan untuknya, berurutan — token, transfer, dan setiap cek status. Kolom penting:

Log panggilan ke bank

GET/log — setiap panggilan HTTP ke bank, termasuk permintaan token. Saringan: bank, layanan (nama layanan bank, mis. transfer-intrabank), status, transaction_id, request_id, dari, sampai, gagal=1, limit.

GET/log/:id menampilkan header dan badan permintaan serta jawaban. http_status = 0 berarti bank tidak menjawab.

Monitoring

GET/monitor?menit=60 — ringkasan dalam jendela waktu terakhir (1 sampai 1440 menit).

Yang perlu diperhatikan operator setiap hari

• pending.perlu_cek_manual lebih dari nol — ada transaksi yang tidak bisa dipastikan otomatis. Tanyakan ke bank dengan transaction_id dan external_id-nya.
• pending.tertua sudah lama — periksa apakah bank itu sedang bermasalah.
• tingkat_galat_persen atau timeout naik pada satu bank — pertimbangkan mengalihkan routing sementara.
• keadaan.configured = false — bank itu tidak bisa dipanggil sampai konfigurasinya dilengkapi.

Jejak audit pengguna

Login, logout, dan setiap perubahan konfigurasi bank atau routing dicatat ke t_log, sama seperti cmc-api2. Jejak transaksi tidak ditulis ke sana; semuanya ada di t_integrator_trx dan t_integrator_log.

Bab 12Simulator dan pengujian

Mencoba semua layanan dan semua skenario tanpa koneksi ke bank.

Dengan SIM_ENABLED=1, service juga berperan sebagai kelima bank di /sim/<BANK>/…. Simulator memakai profil yang sama dengan adaptor (path, bentuk waktu, panjang X-EXTERNAL-ID, cara tanda tangan) dan memeriksa token serta tanda tangan sungguhan. Adaptor yang salah menandatangani langsung ditolak.

Skenario

Dipilih dari empat digit terakhir rekening tujuan (transfer, inquiry) atau nomor pelanggan (VA).

Saldo awal tiap bank simulator Rp 10 miliar; nominal di atasnya dijawab saldo tidak cukup. GET /sim menampilkan keadaan simulator, DELETE /sim meresetnya.

Uji otomatis

go test ./internal/...

Uji unit: tanda tangan dicocokkan dengan hasil hitung di luar Go (Python dan OpenSSL), transformasi tiap bank, dan pemetaan status.

python tools/e2e.py

Uji ujung-ke-ujung, 94 pemeriksaan: keamanan, routing, ketujuh layanan di lima bank, idempotency (termasuk permintaan serentak), timeout, konfirmasi, retry, log, dan monitoring. Service harus hidup dengan batas waktu pendek supaya uji selesai dalam sekitar dua menit:

BANK_TRANSFER_TIMEOUT=4s SIM_TIMEOUT_DELAY=7s SIM_PENDING_DELAY=6s \
PENDING_CHECK_INTERVAL=2s PENDING_CHECK_SCHEDULE=3s,3s,4s NOT_FOUND_GRACE=10s \
./tmp/integrator.exe

Skrip membuat token sendiri dari JWT_SECRET di .env, jadi tidak butuh password.

Bab 13Menuju UAT dan produksi

Urutan kerja dari lokal ke lingkungan bank.

1. Siapkan database Cadangkan database, lalu jalankan sql/migration.sql. Isinya hanya CREATE TABLE IF NOT EXISTS. Jangan memuat sql/seed.sql.
2. Siapkan environment APP_ENV=production (atau uat), SIM_ENABLED=0, JWT_SECRET baru, IP_ALLOW berisi IP server Aplikasi Kliring, CORS_ORIGINS sesuai kebutuhan.
3. Buat kunci per bank dan serahkan public key-nya Simpan private key di server dengan hak baca terbatas. Daftarkan public key ke bank lewat jalur resmi masing-masing.
4. Daftarkan bank POST /intbank dengan base URL, client key, partner id, channel id, rekening, prefix VA, dan opsi dari bank. Isi rahasianya di .env, lalu restart.
5. Pastikan koneksi jaringan IP server integrator didaftarkan di whitelist bank; sertifikat mTLS dipasang bila diminta; jam server tersinkron (bank menolak X-TIMESTAMP yang meleset).
6. Uji bertahap POST /intbank/:id/ping → cek saldo → inquiry rekening → transfer bernominal kecil → cek status transfer itu. Periksa GET /log pada tiap langkah.
7. Atur routing Buat aturan di /route atau wajibkan Aplikasi Kliring mengirim bank.

Yang perlu dikonfirmasi ke tiap bank

• Path setiap endpoint yang bertanda ○ di Bab 10.
• Bentuk dan panjang X-EXTERNAL-ID, dan bentuk X-TIMESTAMP.
• Aturan idempotency bank: per partnerReferenceNo atau per X-EXTERNAL-ID, dan berapa lama berlaku.
• Karakter yang diterima pada partnerReferenceNo — menentukan bentuk transaction_id yang aman dipakai Kliring.
• Batas waktu jawaban transfer, untuk menyetel timeout_transfer_ms bank itu.
• Kode jawaban yang tidak ada di daftar GET /ref/status.

Bab 14Pemecahan masalah

Gejala, penyebab yang paling mungkin, dan tindakannya.

Service tidak mau jalan

Permintaan ditolak integrator

Masalah dengan bank

Menelusuri satu transaksi

1. GET /trx/<transaction_id> — lihat status, alasan, dan daftar panggilan.
2. Ambil id panggilan yang bermasalah, buka GET /log/<id> — lihat apa yang dikirim dan apa jawaban bank.
3. Saat menghubungi bank, sertakan transaction_id (di bank: partnerReferenceNo), external_id, waktu, dan bank_response_code.

Bab 15Menambah bank baru

Untuk pengembang integrator. Aplikasi Kliring tidak berubah.

Bank berskema SNAP

Buat satu berkas di internal/bank/ berisi profil bank itu:

package bank

func init() {
    registerSNAP(&Profile{
        Adapter:   "XYZ",
        BankCode:  "999",
        Name:      "Bank XYZ",
        TokenPath: "/snap/v1.0/access-token/b2b",
        Endpoints: map[string]Endpoint{
            EpBalanceInquiry:    {"/snap/v1.0/balance-inquiry", "11", true, "Dokumen API XYZ v1.0"},
            EpTransferIntrabank: {"/snap/v1.0/transfer-intrabank", "17", true, "Dokumen API XYZ v1.0"},
            EpTransferStatus:    {"/snap/v1.0/transfer/status", "36", true, "Dokumen API XYZ v1.0"},
        },
    })
}

Bank bukan SNAP

Implementasikan interface bank.Adapter (ID, Info, Conn, Supports, Do, Ping, State) lalu daftarkan dengan bank.Register. Do menerima *bank.Request dan harus mengembalikan bank.Result dengan empat status standar. Aturan yang wajib dijaga: layanan yang mengubah sesuatu dan hasilnya tidak pasti harus menjadi PENDING, dan Sent harus jujur menyatakan apakah permintaan sempat terkirim.

Sesudah kode

1. Tambahkan uji transformasi bank itu di internal/bank/bank_test.go.
2. Build ulang dan deploy.
3. Daftarkan koneksinya lewat POST /intbank, isi BANK_<ID>_*, lalu ping.

LampiranAcuan cepat

Daftar rute, tabel, dan susunan folder.

A. Daftar rute

Semua di bawah /api. Kolom "Peran" menyebut tipe user yang boleh.

Buku ini sendiri disajikan service di /panduan/ (di luar /api).

Simulator (di luar /api, hanya bila SIM_ENABLED=1): GET /sim, DELETE /sim, POST /sim/<BANK>/….

B. Tabel database

Tabel CMC yang dibaca: r_userid, r_member, r_bank. Yang ditulis: t_log (login dan perubahan konfigurasi saja).

C. Susunan folder

api-integrator/
  main.go                 titik masuk
  .env.example            contoh konfigurasi
  internal/
    config/               pembacaan .env
    db/                   koneksi MySQL
    middleware/           JWT, peran, IP whitelist, CORS, rate limit
    response/  audit/  utils/
    snap/                 protokol SNAP: tanda tangan, kode respons, penyamaran log
    bank/                 antarmuka standar + adaptor bri, bni, btn, bsi, mandiri
    integrator/           routing, idempotency, retry, konfirmasi status
    routes/               rute HTTP dan simulator
  sql/                    migration.sql, seed.sql
  tools/e2e.py            uji ujung-ke-ujung
  keys/                   kunci (tidak masuk git)
  doc/                    dokumen arsitektur dan buku ini

D. Port service di lingkungan KBI