Brick API Documentation
Brick

Konfigurasi dan Implementasi

Ikhtisar

Halaman Checkout adalah pengalaman pembayaran Brick yang dihosting yang menggabungkan:

  • konfigurasi yang dikelola dasbor untuk pengaturan branding dan penyematan
  • Pembuatan sesi berbasis API untuk setiap transaksi

Pengaturan ini memungkinkan pedagang untuk mempertahankan gaya halaman dan pengaturan operasional di Dasbor Brick, sementara backend mereka membuat sesi checkout khusus transaksi melalui API.

Tempat Mengonfigurasi Halaman Checkout

Buka Dasbor Brick dan navigasikan ke Settings > Checkout

Halaman ini berisi konfigurasi tingkat pedagang untuk pengalaman checkout yang dihosting.

Brick Checkout Page configuration dashboard


Konfigurasi Halaman Checkout

Pengaturan berikut dikelola di Dashboard UI.

BidangDeskripsiCatatan Implementasi
TitleJudul pedagang atau produk ditampilkan pada halaman yang dihostingGunakan label yang menghadap pelanggan
Primary ColorWarna aksen merek utamaDiterapkan pada elemen UI utama
Font ColorWarna teks utamaPastikan kontras yang cukup
Logo URLLogo ditampilkan di halaman checkoutHarus dapat diakses publik
Favicon URLIkon tab perambanHarus dapat diakses publik
Font FamilyPengaturan tipografi untuk halaman yang dihostingGunakan font yang didukung
Button RadiusJari-jari sudut tombolMengontrol gaya visual
Success URLRedirect URL setelah berhasil diselesaikanJangan gunakan sebagai satu-satunya sumber konfirmasi pembayaran
Failed URLRedirect URL setelah kegagalan atau pembatalanGunakan hanya untuk UX
Client Receipt EmailEmail penerima tanda terimaDikelola di dasbor
Client Receipt WhatsAppNomor penerima resi WhatsAppDikelola di dasbor
Published KeyKunci publik untuk inisialisasi frontend Halaman CheckoutAman untuk penggunaan frontend
Allowed DomainsDaftar domain yang diizinkan untuk eksekusi penyematan HTMLDiperlukan untuk alur penyematan


Tanggung Jawab Konfigurasi

Tanggung Jawab Dasbor

Kontrol dasbor:

  • pencitraan merek halaman yang dihosting
  • mengarahkan perilaku
  • pembuatan kunci yang diterbitkan
  • domain yang diizinkan untuk penggunaan yang disematkan
  • konfigurasi kontak tanda terima

Tanggung Jawab Backend

Kontrol backend Anda:

  • menghasilkan token akses publik
  • membuat sesi checkout
  • menyimpan referensi transaksi
  • menerima panggilan balik
  • memeriksa status transaksi bila diperlukan

Model Kredensial

Halaman Checkout menggunakan kredensial berbeda untuk lapisan berbeda.

KredensialDigunakan OlehTujuan
Published KeyBagian depanMemuat konfigurasi checkout pedagang
Client IDBagian belakangDigunakan untuk menghasilkan token akses publik
Client SecretBagian belakangDigunakan untuk menghasilkan token akses publik
publicAccessTokenPanggilan API bagian belakangMengotorisasi titik akhir Halaman Checkout yang dilindungi

Aturan penting:

  • jangan pernah mengekspos Client Secret dalam kode frontend
  • jangan gunakan Published Key sebagai kredensial API
  • menghasilkan publicAccessToken baru mendekati waktu penggunaan

Titik Masuk Frontend

Halaman Checkout dapat diinisialisasi dengan dua cara.

Titik MasukTujuan
https://checkout.onebrick.io/?pubkey=<Published Key>Memuat frontend checkout yang dihosting bermerek
checkoutUrl dikembalikan oleh POST /v1/payments/checkoutMembuka sesi pembayaran khusus transaksi

Gunakan Published Key saat Anda memerlukan frontend yang dihosting atau alur penyematan yang dikonfigurasi.

Gunakan checkoutUrl yang dihasilkan API ketika pelanggan harus menyelesaikan transaksi tertentu.


Alur Implementasi yang Direkomendasikan

Langkah 1. Konfigurasikan Halaman Checkout di Dasbor

Sebelum mengirimkan lalu lintas langsung:

  1. Atur judul halaman, warna, logo, dan favicon.
  2. Konfigurasikan Success URL dan Failed URL.
  3. Tinjau bidang tujuan tanda terima jika digunakan.
  4. Salin Published Key.
  5. Tambahkan domain yang diizinkan jika Anda berencana menyematkan halaman.

Langkah 2. Hasilkan Token Akses Publik

Panggilan API Halaman Checkout Terlindung memerlukan token akses publik.

Endpoint

Code
GET /v2/payments/auth/token

Example

TerminalCode
curl -u "<CLIENT_ID>:<CLIENT_SECRET>" \ "https://sandbox.onebrick.io/v2/payments/auth/token"

Example Response

JSONCode
{ "status": 200, "data": { "message": "Access token is valid for 5 minutes and can use one time only", "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "issuedAt": "2026-03-17T11:54:06.736541", "expiresAt": "2026-03-17T11:59:06.736541" } }

Langkah 3. Buat Sesi Checkout

Panggil Halaman Checkout untuk membuat titik akhir dari backend Anda.

Endpoint

Code
POST /v1/payments/checkout

Headers

Code
publicAccessToken: Bearer <accessToken> Content-Type: application/json

Example Request

JSONCode
{ "externalId": "CO-1773723246580", "currency": "IDR", "description": "Gaming Voucher Free Amount" }

Optional Fixed-Amount Example

JSONCode
{ "externalId": "CO-1773723246580", "currency": "IDR", "description": "Gaming Voucher", "amount": 12012, "type": "qris" }

Example cURL

TerminalCode
curl --request POST \ --url "https://sandbox.onebrick.io/v1/payments/checkout" \ --header "publicAccessToken: Bearer <accessToken>" \ --header "Content-Type: application/json" \ --data '{ "externalId": "CO-1773723246580", "currency": "IDR", "description": "Gaming Voucher Free Amount" }'

Example Response

JSONCode
{ "status": 200, "data": { "id": "QyECa1OpjWJcyfzXOLT6HKCxAVoDzUs3", "externalId": "CO-1773723246580", "status": "CREATED", "checkoutUrl": "https://sandbox-checkout.onebrick.io/aiU5tkLQZeZzXXdgwZUenOyGgTf41mKqyXv9XS96yB4QE9lze2wuMFhfPH4jMC2%2B", "currency": "IDR", "amount": null, "type": "", "createdAt": "2026-03-17T04:54:06Z", "description": "Gaming Voucher Free Amount" }, "errors": null, "hashcode": "38d4b6cc3dd7a6cbb400f08c3bed1228" }

Langkah 4. Tunjukkan Checkout kepada Pelanggan

Anda dapat menyajikan pembayaran dalam salah satu pola berikut:

  • mengarahkan pelanggan ke checkoutUrl
  • buka checkoutUrl dari tombol atau CTA
  • inisialisasi frontend Halaman Checkout bermerek menggunakan Published Key
  • sematkan halaman jika domain asal diizinkan

Langkah 5. Konfirmasikan Hasil Pembayaran

Jangan hanya mengandalkan URL pengalihan.

Gunakan:

  • Panggilan balik Brick sebagai sumber kebenaran
  • pemeriksaan status untuk verifikasi operasional bila diperlukan

Konfigurasi Penyematan HTML

Jika Anda berencana untuk menyematkan Halaman Checkout:

  1. Tambahkan semua asal yang diizinkan di bawah Allowed Domains.
  2. Simpan konfigurasi.
  3. Uji penyematan dari setiap domain yang disetujui.

Jika situs asal tidak diizinkan, halaman yang dihosting atau pemeriksaan status terkait mungkin gagal karena pembatasan asal.



Kendala Implementasi

Batasan Token

  • token akses publik berumur pendek
  • tanggapan token yang diuji menyatakan bahwa mereka valid selama 5 menit dan sekali pakai
  • menghasilkan token baru sebelum permintaan dilindungi

Kendala Lingkungan

Lingkungan HidupURL dasar
kotak pasirhttps://sandbox.onebrick.io
Produksihttps://api.onebrick.io

Gunakan https:// eksplisit di semua URL dasar.

Hindari:

Code
http://sandbox.onebrick.io

Pengalihan HTTP dapat menyebabkan beberapa klien mencoba lagi sebagai GET, yang dapat memicu 405 method_not_allowed.

Batasan Referensi

  • externalId harus unik per transaksi
  • simpan ID transaksi externalId dan Brick yang dikembalikan

Kendala Saluran

  • qris dan virtual_account didukung dalam koleksi yang diuji
  • Batas jumlah QR Code dan batas Akun Virtual mengikuti aturan produk Terima Uang yang dikonfigurasi oleh Brick


Pemecahan masalah

400 Permintaan Buruk

Penyebab umum:

  • bidang wajib yang hilang
  • JSON tidak valid
  • jenis bidang yang salah

Praktik terbaik:

  • kirim JSON yang valid saja
  • jangan letakkan komentar di dalam badan permintaan JSON

401 Tidak Sah

Penyebab umum:

  • token tidak valid
  • tanda yang hilang
  • token kedaluwarsa
  • kredensial lingkungan yang salah

Metode 405 Tidak Diizinkan

Penyebab umum:

  • menggunakan GET bukannya POST untuk /v1/payments/checkout
  • memposting ke URL http:// dan membiarkan klien mengikuti pengalihan

Data Backend yang Direkomendasikan untuk Disimpan

Untuk setiap sesi Halaman Checkout, simpan minimal:

  • externalId
  • ID transaksi Brick
  • checkoutUrl
  • status
  • currency
  • amount
  • description
  • stempel waktu pembuatan

Hal ini akan membantu rekonsiliasi, mendukung investigasi, dan pencocokan callback.

Daftar Periksa Tayang Langsung

  1. Konfirmasikan akses produksi diaktifkan.
  2. Konfigurasikan URL panggilan balik produksi.
  3. Tinjau semua bidang pencitraan merek di bawah Settings > Checkout.
  4. Validasi Success URL dan Failed URL.
  5. Salin dan verifikasi Published Key.
  6. Tambahkan semua domain yang disetujui ke Allowed Domains.
  7. Uji satu aliran jumlah terbuka dan satu aliran jumlah tetap di kotak pasir.
  8. Validasi callback sebelum beralih ke produksi.
Last modified on