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.

Konfigurasi Halaman Checkout

Pengaturan berikut dikelola di Dashboard UI.

Bidang	Deskripsi	Catatan Implementasi
`Title`	Judul pedagang atau produk ditampilkan pada halaman yang dihosting	Gunakan label yang menghadap pelanggan
`Primary Color`	Warna aksen merek utama	Diterapkan pada elemen UI utama
`Font Color`	Warna teks utama	Pastikan kontras yang cukup
`Logo URL`	Logo ditampilkan di halaman checkout	Harus dapat diakses publik
`Favicon URL`	Ikon tab peramban	Harus dapat diakses publik
`Font Family`	Pengaturan tipografi untuk halaman yang dihosting	Gunakan font yang didukung
`Button Radius`	Jari-jari sudut tombol	Mengontrol gaya visual
`Success URL`	Redirect URL setelah berhasil diselesaikan	Jangan gunakan sebagai satu-satunya sumber konfirmasi pembayaran
`Failed URL`	Redirect URL setelah kegagalan atau pembatalan	Gunakan hanya untuk UX
`Client Receipt Email`	Email penerima tanda terima	Dikelola di dasbor
`Client Receipt WhatsApp`	Nomor WhatsApp penerima resi	Dikelola di dasbor
`Published Key`	Kunci publik untuk inisialisasi frontend Halaman Checkout	Aman untuk penggunaan frontend
`Allowed Domains`	Daftar domain yang diizinkan untuk eksekusi penyematan HTML	Diperlukan 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.

Kredensial	Digunakan Oleh	Tujuan
`Published Key`	Bagian depan	Memuat konfigurasi checkout pedagang
`Client ID`	Bagian belakang	Digunakan untuk menghasilkan token akses publik
`Client Secret`	Bagian belakang	Digunakan untuk menghasilkan token akses publik
`publicAccessToken`	Panggilan API bagian belakang	Mengotorisasi 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 Masuk	Tujuan
`https://checkout.onebrick.io/?pubkey=<Published Key>`	Memuat frontend checkout yang dihosting bermerek
`checkoutUrl` dikembalikan oleh `POST /v1/payments/checkout`	Membuka 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:

Atur judul halaman, warna, logo, dan favicon.
Konfigurasikan Success URL dan Failed URL.
Tinjau bidang tujuan tanda terima jika digunakan.
Salin Published Key.
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

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

Example Response


Code
{
  "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


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

Optional Fixed-Amount Example


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

Example cURL

Code
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


Code
{
  "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:

Tambahkan semua asal yang diizinkan di bawah Allowed Domains.
Simpan konfigurasi.
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 Hidup	URL dasar
kotak pasir	`https://sandbox.onebrick.io`
Produksi	`https://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 QRIS 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

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

Last modified on June 7, 2026

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.

Konfigurasi Halaman Checkout

Pengaturan berikut dikelola di Dashboard UI.

Bidang	Deskripsi	Catatan Implementasi
`Title`	Judul pedagang atau produk ditampilkan pada halaman yang dihosting	Gunakan label yang menghadap pelanggan
`Primary Color`	Warna aksen merek utama	Diterapkan pada elemen UI utama
`Font Color`	Warna teks utama	Pastikan kontras yang cukup
`Logo URL`	Logo ditampilkan di halaman checkout	Harus dapat diakses publik
`Favicon URL`	Ikon tab peramban	Harus dapat diakses publik
`Font Family`	Pengaturan tipografi untuk halaman yang dihosting	Gunakan font yang didukung
`Button Radius`	Jari-jari sudut tombol	Mengontrol gaya visual
`Success URL`	Redirect URL setelah berhasil diselesaikan	Jangan gunakan sebagai satu-satunya sumber konfirmasi pembayaran
`Failed URL`	Redirect URL setelah kegagalan atau pembatalan	Gunakan hanya untuk UX
`Client Receipt Email`	Email penerima tanda terima	Dikelola di dasbor
`Client Receipt WhatsApp`	Nomor WhatsApp penerima resi	Dikelola di dasbor
`Published Key`	Kunci publik untuk inisialisasi frontend Halaman Checkout	Aman untuk penggunaan frontend
`Allowed Domains`	Daftar domain yang diizinkan untuk eksekusi penyematan HTML	Diperlukan 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.

Kredensial	Digunakan Oleh	Tujuan
`Published Key`	Bagian depan	Memuat konfigurasi checkout pedagang
`Client ID`	Bagian belakang	Digunakan untuk menghasilkan token akses publik
`Client Secret`	Bagian belakang	Digunakan untuk menghasilkan token akses publik
`publicAccessToken`	Panggilan API bagian belakang	Mengotorisasi 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 Masuk	Tujuan
`https://checkout.onebrick.io/?pubkey=<Published Key>`	Memuat frontend checkout yang dihosting bermerek
`checkoutUrl` dikembalikan oleh `POST /v1/payments/checkout`	Membuka 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:

Atur judul halaman, warna, logo, dan favicon.
Konfigurasikan Success URL dan Failed URL.
Tinjau bidang tujuan tanda terima jika digunakan.
Salin Published Key.
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

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

Example Response


Code
{
  "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


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

Optional Fixed-Amount Example


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

Example cURL

Code
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


Code
{
  "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:

Tambahkan semua asal yang diizinkan di bawah Allowed Domains.
Simpan konfigurasi.
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 Hidup	URL dasar
kotak pasir	`https://sandbox.onebrick.io`
Produksi	`https://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 QRIS 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

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

Last modified on June 7, 2026