Documentation Center

Panduan integrasi berlapis: konteks bisnis → arsitektur koneksi → implementasi teknis

Mulai dari sini

Ekosistem API Bank ABC

Platform H2H (Host-to-Host) berbasis standar SNAP BI: sistem backend Anda berkomunikasi langsung ke server Bank ABC tanpa browser, tanpa redirect, dan tanpa interaksi manual. Setiap request ditandatangani secara kriptografis menggunakan RSA dan diverifikasi di kedua sisi.

Arsitektur koneksi

Navigasi dokumentasi

Mulai dari mana?
Baru di sini?
Sudah setup credential?
Ada error atau masalah?
Fondasi

Open Banking: Mengapa Bank Jadi Pusat Ekosistem?

Selama puluhan tahun, data keuangan hidup secara tertutup di dalam sistem bank; tidak ada cara bagi pihak luar untuk mengaksesnya secara terprogram. Open Banking mengubah paradigma ini: bank membuka akses ke infrastruktur keuangan mereka melalui API terstandar, sehingga developer dapat membangun layanan di atas data dan kapabilitas bank dengan izin yang jelas.

Di Indonesia, kerangka ini diatur oleh Bank Indonesia melalui regulasi SNAP BI (Standar Nasional Open API Pembayaran). SNAP BI mendefinisikan format request/response, mekanisme autentikasi, dan standar keamanan yang wajib diikuti oleh seluruh bank dan fintech yang beroperasi dalam ekosistem pembayaran nasional. Bank ABC mengikuti standar ini sepenuhnya.

Mengapa bank berada di pusat ekosistem?

Data Keuangan Terverifikasi Bank memegang saldo, histori transaksi, dan identitas rekening yang sudah divalidasi secara legal. Tidak ada institusi lain yang memiliki data ini dengan tingkat kepercayaan yang sama.
Otoritas Settlement Hanya bank yang dapat menyelesaikan transaksi keuangan secara definitif: memindahkan dana, melakukan kliring, dan menjamin finalitas pembayaran. Ini tidak bisa didelegasikan ke pihak lain.
Kepercayaan Regulasi Bank beroperasi di bawah pengawasan OJK dan tunduk pada Peraturan Bank Indonesia (PBI). Standar kepatuhan ini menjadikan bank sebagai titik kepercayaan yang diakui semua pihak dalam ekosistem.

Ekosistem Open Banking: siapa berbicara ke siapa

Selanjutnya: Konsep H2H Bank ABC mengimplementasikan Open Banking melalui pola Host-to-Host (H2H): sistem Anda berkomunikasi langsung ke server Bank ABC menggunakan standar SNAP BI, tanpa perantara browser. Pelajari cara kerjanya.
Fondasi

Konsep H2H (Host-to-Host)

Layanan transaksi berbasis Host-to-Host (H2H) memberikan Anda akses komunikasi langsung ke sistem Bank ABC melalui aturan bahasa dan respons yang disepakati, tanpa perantara browser atau interaksi manual. Setiap request ditandatangani secara kriptografis menggunakan RSA key pair dan diverifikasi di kedua sisi; itulah yang membedakannya dari REST API pada umumnya.

H2H vs integrasi berbasis browser

Prasyarat teknis

IP Publik StatisServer Anda harus memiliki IP publik yang tidak berubah. IP ini didaftarkan ke Bank ABC sebelum produksi. Di sandbox, gunakan fitur Integrasi Langsung untuk pendaftaran IP.
HTTPS / TLS 1.2+Semua request wajib HTTPS. Koneksi HTTP ditolak otomatis. Pastikan sertifikat SSL server Anda valid dan tidak expired.
Endpoint CallbackAnda wajib menyediakan URL HTTPS yang bisa menerima POST request dari Bank ABC sebagai notifikasi status transaksi. URL ini didaftarkan di halaman Credentials.
Timeout HandlingTimeout maksimum 30 detik. Implementasikan retry dengan exponential backoff untuk timeout. Jangan retry langsung untuk 5xx error.

Alur koneksi

1Sistem Anda menginisiasi request HTTPS POST ke server Bank ABC dengan payload transaksi.
2Setiap request disertai Bearer token OAuth 2.0 di header Authorization dan tanda tangan RSA di header X-SIGNATURE.
3Bank ABC memverifikasi tanda tangan menggunakan RSA public key Anda yang terdaftar, memproses instruksi, dan mengembalikan response dalam 30 detik.
4Untuk konfirmasi asinkron (mis. settlement), Bank ABC mengirim POST ke callback URL yang Anda daftarkan di Credentials.

Langkah berikutnya: Daftarkan RSA public key Anda (Signing Key) untuk mulai menandatangani request.

Fondasi

Signing Key

Setiap request API ke Bank ABC harus disertai tanda tangan digital. Ini membuktikan bahwa request benar-benar datang dari server Anda, bukan dari pihak lain yang berpura-pura menjadi Anda.

Signing Key adalah mekanisme untuk membuat tanda tangan tersebut. Teknologi di baliknya adalah RSA, standar kriptografi yang sama dipakai oleh HTTPS, SSH, dan JWT di seluruh internet. Anda tidak perlu memahami matematikanya. Yang perlu dipahami adalah cara kerjanya: ada dua kunci dengan fungsi yang berbeda.

Dua kunci, dua fungsi yang berbeda

Private Key

private_key.pem
  • Dibuat di terminal server Anda
  • Disimpan hanya di server Anda
  • Digunakan untuk menandatangani setiap request
Jangan pernah unggah, kirim, atau bagikan file ini

Public Key

public_key.pem
  • Diekstrak otomatis dari private key
  • Diunggah ke Bank ABC sekali saat setup
  • Bank ABC menggunakannya untuk verifikasi tanda tangan
Aman dibagikan. Tidak bisa digunakan untuk signing

Setup: 2 langkah, sekali seumur proyek

1

Generate RSA key pair di terminal

Jalankan dua perintah ini satu kali di server Anda. Hasilnya dua file .pem.

Terminal 
openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem
2

Daftarkan public key di portal

Buka halaman Credentials, masuk ke tab Signing Key, paste seluruh isi file public_key.pem termasuk baris BEGIN dan END, lalu simpan. Tidak perlu diulang kecuali Anda merotasi key.

Buka Credentials
Dua hal yang sering tertukar
RSA Key Pair

Tidak punya tanggal kedaluwarsa. Dibuat dan didaftarkan sekali, berlaku selamanya kecuali Anda memilih untuk merotasi. Ini yang baru saja Anda generate di langkah 1.

Access Token (JWT)

Kedaluwarsa setiap 15 menit. Dibuat otomatis oleh kode Anda dari client_id dan client_secret. Ini bukan RSA, ini OAuth 2.0 token biasa.

Yang terjadi di setiap request API

Contoh implementasi signing

import jwt, time, hashlib, base64
from cryptography.hazmat.primitives import serialization

with open("private_key.pem", "rb") as f:
    private_key = serialization.load_pem_private_key(f.read(), password=None)

def get_access_token(client_id, client_secret):
    payload = {"iss": client_id, "sub": client_id,
               "iat": int(time.time()), "exp": int(time.time()) + 900}
    return jwt.encode(payload, private_key, algorithm="RS256")

def sign_request(method, path, body, timestamp):
    body_hash = base64.b64encode(hashlib.sha256(body.encode()).digest()).decode()
    string_to_sign = f"{method}:{path}:{body_hash}:{timestamp}"
    return jwt.encode({"data": string_to_sign}, private_key, algorithm="RS256")
const jose = require('jose');
const fs = require('fs'), crypto = require('crypto');
const privateKey = crypto.createPrivateKey(fs.readFileSync('private_key.pem'));

async function getAccessToken(clientId) {
  return new jose.SignJWT({ iss: clientId, sub: clientId })
    .setProtectedHeader({ alg: 'RS256' }).setIssuedAt().setExpirationTime('15m')
    .sign(privateKey);
}
function signRequest(method, path, body, timestamp) {
  const bodyHash = crypto.createHash('sha256').update(body).digest('base64');
  const stringToSign = `${method}:${path}:${bodyHash}:${timestamp}`;
  return crypto.sign('sha256', Buffer.from(stringToSign), privateKey).toString('base64');
}
PrivateKey privateKey = loadPrivateKeyFromPem("private_key.pem");

String getAccessToken(String clientId) {
    long now = Instant.now().getEpochSecond();
    return Jwts.builder().setIssuer(clientId).setSubject(clientId)
        .setIssuedAt(new Date(now*1000)).setExpiration(new Date((now+900)*1000))
        .signWith(privateKey, SignatureAlgorithm.RS256).compact();
}
String signRequest(String method, String path, String body, String timestamp) {
    String bodyHash = Base64.getEncoder().encodeToString(
        MessageDigest.getInstance("SHA-256").digest(body.getBytes()));
    String toSign = method + ":" + path + ":" + bodyHash + ":" + timestamp;
    Signature sig = Signature.getInstance("SHA256withRSA");
    sig.initSign(privateKey); sig.update(toSign.getBytes());
    return Base64.getEncoder().encodeToString(sig.sign());
}

Spesifikasi teknis

AlgoritmaRS256
Key size2048-bit min
Access token expiry900 detik (15 min)
RSA key pairTidak kedaluwarsa
StandarSNAP BI v2.0
Max key aktif2 (untuk rotasi)

Error signing yang umum

Response CodeHTTPPenyebabSolusi
4012900401Access token kedaluwarsaGenerate token baru secara otomatis dan ulangi request
4012901401Signature tidak validPeriksa format string_to_sign dan private key yang digunakan
4012902401RSA public key belum terdaftarDaftarkan public key di Credentials > Signing Key
4002900400Header X-TIMESTAMP tidak sesuai formatGunakan ISO 8601: 2026-05-23T09:00:00+07:00
Referensi

Glosarium SNAP BI

Terminologi standar yang digunakan di seluruh dokumentasi API Bank ABC, mengacu pada regulasi SNAP BI dari Bank Indonesia.

IstilahPenjelasan
SNAP BIStandar Nasional Open API Perbankan dari Bank Indonesia. Mendefinisikan format request, header wajib, dan struktur response untuk semua transaksi antar bank dan mitra.
H2HHost-to-Host. Koneksi langsung server-to-server tanpa browser atau manusia. Mitra mengintegrasikan backend mereka langsung ke server Bank ABC.
Signing KeyRSA key pair untuk menandatangani setiap request API. Private key disimpan di sisi mitra, public key didaftarkan ke Bank ABC melalui Credentials.
VA (Virtual Account)Nomor rekening virtual untuk tracking dan routing pembayaran. Bisa berupa VA unik per transaksi atau VA statis permanen per merchant.
partnerReferenceNoID unik yang dibuat oleh sistem mitra untuk setiap transaksi. Digunakan untuk idempotency: request dengan ID sama tidak diproses dua kali.
T+0 SettlementDana diselesaikan pada hari yang sama. Berlaku untuk transaksi yang masuk sebelum pukul 15.00 WIB di hari kerja.
CBSCore Banking System. Sistem inti Bank ABC yang memproses semua transaksi keuangan dan ledger rekening.
X-SIGNATUREHTTP header berisi tanda tangan RSA per-request. Dibuat dari hash method + path + body + timestamp, ditandatangani dengan RSA private key mitra.
Access TokenJWT OAuth 2.0 untuk otentikasi sesi. Berlaku 15 menit, dibuat otomatis oleh kode Anda dari client_id dan client_secret.
Callback URLEndpoint HTTPS milik mitra yang menerima notifikasi asinkron dari Bank ABC setelah transaksi diproses.
IdempotencyProperti yang memastikan request dengan partnerReferenceNo yang sama tidak diproses lebih dari sekali meskipun dikirim ulang.
Troubleshooting

Panduan Troubleshooting

Isu paling umum yang ditemui selama integrasi dan setelah live. Setiap item mencakup penyebab akar dan langkah konkret untuk mengatasinya.

Referensi

Changelog

Riwayat perubahan API

Riwayat perubahan signifikan pada API Bank ABC. Breaking changes ditandai secara eksplisit dan mencakup panduan migrasi.

v1.4 12 Apr 2026
Breaking Response code 4001 dan 4002 dipisah. Sebelumnya semua validasi request menggunakan 4001. Mulai v1.4: 4001 = parameter tidak valid, 4002 = rekening tujuan tidak ditemukan. Update error handler untuk menangani keduanya secara terpisah.
Baru Header X-Expires-In ditambahkan pada response auth token. Berisi durasi validitas token dalam detik. Gunakan ini untuk proactive refresh daripada hardcode durasi.
Fix Callback retry logic diperbaiki. Sebelumnya retry ke-3 kadang dikirim dua kali dalam kondisi high-load. Sudah diperbaiki di sisi Bank ABC, tidak ada perubahan di sisi mitra.
v1.2 15 Jan 2026
Breaking Durasi access token dipersingkat dari 60 menit menjadi 15 menit sesuai standar keamanan SNAP BI terbaru. Implementasikan proactive refresh atau gunakan header X-Expires-In (tersedia di v1.4).
Baru Endpoint GET /va/status ditambahkan untuk cek status transaksi VA secara polling. Digunakan untuk menangani kasus timeout tanpa mengirim ulang transaksi yang mungkin sudah diproses.
Baru Field callbackUrl di request body memungkinkan override URL callback per-transaksi. Berguna untuk skenario multi-tenant dimana setiap merchant memiliki callback endpoint berbeda.
v1.0 01 Okt 2025
Rilis Rilis pertama API Bank ABC. Mencakup: Virtual Account (VA) Disbursement, QRIS Acquiring, Bulk Transfer, Transfer Dana, dan Notifikasi & Callback. Autentikasi via SNAP BI dengan RSA signing.