Pertanyaan Umum
Gunakan FAQ ini sebagai daftar periksa praktis saat merencanakan, membuat, menguji, atau memecahkan masalah integrasi Brick. Untuk bidang permintaan dan respons khusus produk, selalu konfirmasikan detail terbaru di halaman referensi API yang relevan.
Memulai
Apa yang harus saya baca terlebih dahulu sebelum berintegrasi dengan Brick?
Mulailah dengan alur bisnis yang ingin Anda dukung, lalu petakan ke produk Brick yang relevan:
| Tujuan | Mulai di sini |
|---|---|
| Memahami produk dan kemampuan Brick | What is Brick? |
| Siapkan akses dasbor dan pengaturan akun | Brick Dashboard Overview |
| Siapkan kredensial API dan URL dasar | Prepare Yourself to Use API |
| Memahami otentikasi dan lingkungan | Authentication and Environment |
| Tinjau ekspektasi keamanan | Security at Brick |
Sebelum menulis kode produksi, konfirmasikan produk mana yang Anda integrasikan: pencairan, akun virtual, QRIS, dompet elektronik, halaman checkout, validasi rekening bank, atau wawasan keuangan.
Apa yang harus diselesaikan sebelum akses produksi?
Akses produksi memerlukan akun terverifikasi, kredensial produksi, dan kesiapan operasional.
Minimal lengkap:
- Verifikasi KYB.
- Penyiapan akun dasbor.
- Penyediaan kunci dan rahasia API untuk lingkungan yang benar.
- Konfigurasi URL panggilan balik.
- Pengujian internal di Sandbox.
- Pemeriksaan kesiapan produksi untuk percobaan ulang, penanganan status, pencatatan, dan rekonsiliasi.
Referensi:
Bisakah saya menggunakan produksi APIs sebelum KYB disetujui?
Tidak. Akses produksi diaktifkan hanya setelah persetujuan KYB dan penyediaan kredensial produksi. Anda dapat terus membuat dan menguji dengan kredensial Sandbox saat KYB sedang diproses.
Apa perbedaan antara Sandbox dan Produksi?
Sandbox ditujukan untuk pengujian pengembangan dan integrasi. Ini menggunakan kredensial Sandbox, URL dasar Sandbox, dan perilaku transaksi yang disimulasikan atau diuji.
Produksi memproses transaksi nyata dan menggunakan kredensial produksi, URL basis produksi, dan penyelesaian nyata atau perilaku jaringan bank.
Jangan mencampur kredensial di seluruh lingkungan. Penyebab umum kegagalan autentikasi adalah penggunaan kredensial produksi terhadap URL Sandbox, atau kredensial Sandbox terhadap URL produksi.
Otentikasi Dan Token
Token mana yang harus saya gunakan?
Brick memiliki lebih dari satu alur autentikasi. Gunakan token yang cocok dengan keluarga API yang Anda panggil.
| keluarga API | Aliran token atau kredensial | Catatan |
|---|---|---|
| Umum Brick APIs | Token Akses Publik dari Generate Public Access Token | Token berumur pendek yang digunakan untuk permintaan API umum. |
| QRIS SNAP APIs | Token akses B2B SNAP dari Get Access Token (SNAP) | Alur autentikasi khusus QRIS SNAP. |
| Tindakan dasbor | Akses pengguna dasbor | Dikelola dari dasbor Brick, bukan aliran token API. |
Jika Anda mengintegrasikan QRIS SNAP, jangan perlakukan token akses publik umum sebagai token SNAP. Mulailah dengan aliran token QRIS SNAP.
Mengapa saya mendapatkan 401 Unauthorized?
Penyebab umum meliputi:
- Kredensial ditujukan untuk lingkungan yang salah.
- Kunci API, rahasia, kunci klien, atau tanda tangan salah.
- Token akses publik telah kedaluwarsa atau sudah digunakan.
- Permintaan tersebut tidak memiliki header otorisasi yang diperlukan.
- Permintaan QRIS SNAP menggunakan stempel waktu atau format tanda tangan yang salah.
Pemeriksaan yang disarankan:
- Konfirmasikan URL dasar.
- Konfirmasikan pasangan kredensial milik lingkungan tersebut.
- Hasilkan token baru.
- Bangun kembali header permintaan.
- Bandingkan permintaan dengan referensi API yang relevan.
Referensi:
Mengapa token saya terus gagal setelah dicoba lagi?
Beberapa token berumur pendek dan dimaksudkan untuk penggunaan terbatas. Hasilkan token baru sebelum mencoba kembali permintaan API, terutama jika permintaan sebelumnya gagal setelah penundaan atau dicoba ulang oleh klien Anda.
Untuk sistem produksi, jadikan pembuatan token sebagai bagian dari aliran permintaan yang terkontrol daripada menyimpan token dalam cache secara terlalu agresif.
Bagaimana cara mengamankan kredensial API?
Gunakan penyimpanan sisi server saja. Jangan mengekspos kredensial Brick di aplikasi seluler, kode frontend, repositori publik, log, tangkapan layar dukungan, atau peristiwa analitik.
Praktik yang disarankan:
- Simpan rahasia di manajer rahasia atau konfigurasi lingkungan terenkripsi.
- Putar kredensial saat akses berubah.
- Batasi siapa yang dapat melihat kredensial produksi.
- Menyembunyikan rahasia dalam log aplikasi.
- Pisahkan kredensial Sandbox dan Produksi dengan jelas.
Referensi:
Perilaku API
Apakah respon API berhasil berarti transaksi selesai?
Tidak selalu. Untuk aliran pembayaran dan pencairan yang tidak sinkron, respons API sering kali berarti Brick menerima permintaan pemrosesan. Status akhir mungkin muncul kemudian melalui panggilan balik atau mungkin perlu dikonfirmasi melalui titik akhir status.
Bangun sistem Anda berdasarkan status transaksi akhir, bukan hanya respons API pertama.
Haruskah saya mengandalkan panggilan balik atau status APIs?
Gunakan keduanya, dengan tanggung jawab yang jelas:
| Mekanisme | Paling baik digunakan untuk |
|---|---|
| Panggilan balik | Pemberitahuan acara utama ketika status berubah. |
| Statusnya API | Pemeriksaan manual, rekonsiliasi, fallback ketika panggilan balik tertunda, atau mendukung penyelidikan. |
Sistem Anda harus idempoten. Jika status yang sama diterima lebih dari satu kali, status tersebut tidak boleh menggandakan kredit, mendebit ganda, atau menduplikasi notifikasi pengguna.
Referensi:
Bisakah saya menggunakan kembali ID referensi yang sama?
Tidak. Gunakan ID referensi unik untuk setiap transaksi. Penggunaan kembali ID referensi dapat menyebabkan deteksi duplikat, kebingungan rekonsiliasi, atau permintaan ditolak.
Format yang disarankan:
- Stabil dan unik dari sistem Anda.
- Mudah untuk mencari di log.
- Tidak hanya berdasarkan stempel waktu.
- Disimpan bersama dengan pengidentifikasi transaksi Brick.
Bagaimana cara menangani batas waktu?
Jika klien Anda kehabisan waktu, jangan langsung menganggap transaksi gagal. Permintaannya mungkin masih mencapai Brick dan mungkin masih diproses.
Aliran yang disarankan:
- Catat ID referensi permintaan.
- Kueri titik akhir status yang relevan.
- Tunggu callback jika status masih pending.
- Coba lagi hanya ketika integrasi Anda dapat melakukannya dengan aman dengan perlindungan idempotensi.
Referensi:
Panggilan balik
Mengapa saya tidak menerima panggilan balik?
Periksa hal berikut:
- URL panggilan balik dapat dijangkau secara publik dari internet.
- URL menggunakan HTTPS dengan sertifikat yang valid.
- Firewall atau WAF Anda tidak memblokir permintaan Brick.
- Titik akhir menerima metode HTTP dan format muatan yang diharapkan.
- Aplikasi Anda mengembalikan respons HTTP yang berhasil dengan cepat.
- Konfigurasi panggilan balik diatur untuk lingkungan yang benar.
Jika Anda baru saja mengubah URL panggilan balik, uji lagi di Sandbox sebelum mengandalkannya di Produksi.
Apa yang harus dilakukan oleh pengendali panggilan balik saya?
Jaga agar pemrosesan panggilan balik tetap andal dan singkat:
- Verifikasi sumber panggilan balik dan tanda tangan bila diperlukan.
- Validasi muatannya.
- Simpan peristiwa mentah atau catatan peristiwa yang dapat diaudit.
- Perbarui status transaksi secara idempoten.
- Kembalikan respons HTTP yang berhasil dengan cepat.
- Jalankan tindakan hilir yang lebih berat secara asinkron.
Hindari logika bisnis yang berjalan lama secara langsung di dalam jalur respons panggilan balik.
Bagaimana jika panggilan balik tiba sebelum frontend saya diperbarui?
Itu normal. Perlakukan panggilan balik sebagai peristiwa sistem backend. Frontend Anda harus membaca status transaksi terbaru dari backend Anda alih-alih berasumsi bahwa sesi browser memiliki status akhir.
Kirim Uang: Pencairan
Metode pencairan mana yang harus saya gunakan?
Pilih berdasarkan kebutuhan operasional Anda:
| Metode | Kesesuaian yang khas |
|---|---|
| BIFAST | Aliran transfer lebih cepat dengan cakupan dan batasan bank yang sesuai dengan kasus penggunaan Anda. |
| Pencairan rutin | Fallback atau aliran operasional yang lebih luas ketika BIFAST tidak tersedia. |
Selalu konfirmasikan cakupan, batasan, dan perilaku saat ini di halaman API sebelum rilis.
Referensi:
Apakah saya harus memvalidasi rekening bank sebelum pencairan?
Ya, terutama bila data akun dikumpulkan dari pengguna atau sistem eksternal. Validasi rekening membantu mengurangi kegagalan pencairan dana yang disebabkan oleh nomor rekening bank yang salah atau detail rekening yang tidak cocok.
Referensi:
Kenapa pencairannya stuck di PENDING?
Kemungkinan alasannya:
- Pemrosesan bank masih berlangsung.
- Jaringan mitra belum mengembalikan status akhir.
- Pengiriman panggilan balik tertunda.
- Sistem Anda belum memproses panggilan balik terbaru.
Pemeriksaan yang disarankan:
- Cari berdasarkan ID referensi Anda.
- Periksa status berdasarkan ID pencairan atau ID referensi.
- Tinjau log panggilan balik.
- Konfirmasikan apakah bank tujuan mengalami keterlambatan.
Referensi:
Mengapa saldo saya berbeda dengan buku besar atau riwayat transaksi?
Pandangan yang berbeda dapat menjawab pertanyaan yang berbeda:
| Lihat | Apa gunanya |
|---|---|
| Saldo tersedia | Jumlah yang saat ini tersedia untuk transaksi baru. |
| buku besar | Pergerakan transaksi dan jalur rekonsiliasi. |
| Riwayat transaksi | Tinjauan operasional, pemfilteran, ekspor, dan investigasi dukungan. |
Gunakan buku besar dan riwayat transaksi untuk rekonsiliasi, tidak hanya saldo dashboard.
Referensi:
Bagaimana cara memberikan bukti transfer?
Gunakan fitur bukti transfer ketika operasi Anda memerlukan bukti yang dapat diunduh untuk pencairan yang telah selesai.
Referensi:
Terima Uang
Apa perbedaan antara VA Terbuka dan VA Tertutup?
| tipe VA | Perilaku khas | Paling cocok |
|---|---|---|
| Buka VA | Akun virtual yang dapat digunakan kembali dengan jumlah pembayaran fleksibel. | Isi ulang dompet pelanggan atau pembayaran pelanggan berulang. |
| VA tertutup | Aliran pembayaran satu kali atau tetap dengan jumlah yang diharapkan. | Faktur, checkout, atau pembayaran khusus pesanan. |
Referensi:
Mengapa pembayaran VA belum tercermin?
Kemungkinan penyebabnya:
- Pemrosesan bank atau penundaan penyelesaian.
- Panggilan balik belum terkirim.
- Panggilan balik telah terkirim tetapi titik akhir Anda menolaknya.
- Sistem Anda belum merekonsiliasi status VA terbaru.
Pemeriksaan yang disarankan:
- Periksa log pengiriman panggilan balik.
- Status kueri VA.
- Konfirmasikan jumlah pembayaran dan pengenal VA.
- Rekonsiliasi dengan riwayat transaksi jika diperlukan.
Referensi:
Apa perbedaan antara QRIS Statis, QRIS Dinamis, dan QRIS SNAP?
| tipe QRIS | Penggunaan yang umum |
|---|---|
| QRIS Statis | Kode QR yang dapat digunakan kembali untuk penerimaan pembayaran pedagang. |
| QRIS Dinamis | Kode QR dihasilkan untuk transaksi atau jumlah tertentu. |
| QRIS SNAP | Integrasi QRIS berbasis SNAP menggunakan otentikasi dan standar permintaan SNAP. |
Jika Anda menggunakan QRIS SNAP, mulailah dengan aliran token SNAP sebelum membuat atau menanyakan transaksi QRIS.
Referensi:
Mengapa saya tidak dapat menghasilkan QRIS?
Penyebab umum meliputi:
- Merchant tidak terdaftar atau tidak aktif.
- Akses produk QRIS belum diaktifkan.
- Bidang permintaan yang wajib diisi tidak ada atau tidak valid.
- Permintaan QRIS SNAP menggunakan token, stempel waktu, atau tanda tangan yang tidak valid.
- Anda menelepon lingkungan yang salah.
Referensi:
Kapan saya harus menggunakan E-Wallet atau Halaman Checkout?
Gunakan e-wallet APIs ketika Anda ingin membuat dan mengontrol aliran pembayaran e-wallet langsung dari sistem Anda.
Gunakan Halaman Checkout bila Anda menginginkan halaman pembayaran yang dihosting dengan pengalaman pembayaran yang dikelola Brick, pengalihan, dan penanganan status checkout.
Referensi:
Mengapa pembayaran e-wallet atau checkout tetap belum dibayar?
Kemungkinan penyebabnya:
- Pelanggan tidak menyelesaikan pembayaran.
- Pelanggan menutup aplikasi atau browser selama pengalihan.
- Pembayaran telah habis masa berlakunya.
- Penyedia atau saluran pembayaran untuk sementara tidak tersedia.
- Sistem Anda belum menerima atau memproses panggilan balik.
Pemeriksaan yang disarankan:
- Status pembayaran permintaan.
- Periksa log panggilan balik.
- Konfirmasikan waktu kedaluwarsa pembayaran.
- Konfirmasikan perilaku pengalihan pelanggan.
Referensi:
Rekonsiliasi dan Operasi
Data apa yang harus saya simpan untuk rekonsiliasi?
Simpan data yang cukup untuk melacak setiap transaksi di sistem Anda, Brick, callback, dan alat dukungan pelanggan:
- ID referensi Anda.
- ID transaksi Brick atau ID pencairan saat dikembalikan.
- Jenis produk dan metode pembayaran.
- Jumlah dan mata uang.
- Status saat ini dan riwayat status.
- Payload panggilan balik mentah atau catatan peristiwa yang dapat diaudit.
- Minta stempel waktu dan stempel waktu status akhir.
- Lingkungan Hidup.
Hal ini membuat dukungan, rekonsiliasi keuangan, dan investigasi insiden menjadi lebih cepat.
Seberapa sering saya harus merekonsiliasi status transaksi?
Gunakan callback untuk pembaruan waktu nyata, lalu jalankan rekonsiliasi terjadwal demi keamanan. Interval pastinya bergantung pada volume dan kebutuhan operasional Anda, namun pendekatan yang umum adalah:
- Pemeriksaan jangka pendek untuk transaksi yang masih tertunda setelah waktu pemrosesan yang diharapkan.
- Rekonsiliasi harian untuk keuangan dan operasional.
- Pencarian status manual untuk kasus dukungan pelanggan.
Apa yang harus saya lakukan sebelum melakukan siaran langsung?
Gunakan tinjauan kesiapan produksi:
- Uji skenario yang berhasil, gagal, tertunda, dan kedaluwarsa.
- Validasi penanganan tanda tangan panggilan balik jika berlaku.
- Konfirmasikan pembaruan status idempoten.
- Konfirmasikan perilaku coba lagi dan penanganan batas waktu.
- Konfirmasikan pencatatan dan pemantauan.
- Konfirmasikan alur kerja rekonsiliasi.
- Konfirmasikan jalur eskalasi untuk masalah operasional.
Referensi:
Pemecahan Masalah Dan Dukungan
Informasi apa yang harus saya berikan saat melaporkan suatu masalah?
Termasuk:
- Lingkungan: Sandbox atau Produksi.
- Produk: pencairan, VA, QRIS, e-wallet, checkout, atau produk lainnya.
- Titik akhir dipanggil.
- ID referensi Anda.
- ID transaksi Brick, ID pencairan, atau ID pembayaran jika tersedia.
- Stempel waktu dengan zona waktu.
- Minta sampel muatan dengan rahasia yang dihapus.
- Isi respons dan kode status HTTP.
- Log muatan panggilan balik atau pengiriman panggilan balik jika relevan.
- Hasil yang diharapkan dan hasil yang sebenarnya.
Jangan pernah mengirim rahasia API, kunci pribadi, atau header otorisasi penuh dalam pesan dukungan.
Referensi:
Bagaimana BrickI atau Brick MCP membantu selama implementasi?
Gunakan Meet BrickI saat Anda memerlukan dukungan terpandu atau bantuan menemukan jalur dokumentasi yang tepat.
Gunakan Brick MCP ketika asisten pengkodean AI Anda memerlukan akses terstruktur ke dokumentasi Brick sambil membantu Anda menerapkan, men-debug, atau meninjau integrasi.
Untuk perubahan produksi, selalu validasi keluaran yang dihasilkan AI berdasarkan dokumen resmi, perilaku Sandbox, dan proses peninjauan teknik internal Anda.