Membangun Integrasi Pembayaran
dengan RCB Pay API
RCB Pay API dirancang menggunakan arsitektur REST yang modern dan sangat mudah digunakan. Terima pembayaran QRIS dan Kripto (USDT) secara instan, otomatis, dan terintegrasi.
Introduction
Selamat datang di dokumentasi resmi PT. Raga Cipta Bersama Developers. API kami menggunakan struktur URL berbasis Resource, selalu menerima request dalam format JSON, dan mengembalikan response dalam format JSON standar.
Base URL (Production)
Authentication
Autentikasi ke RCB API dilakukan menggunakan metode API Keys. Anda harus
menyertakan API Key Anda pada setiap *request* melalui Header x-api-key.
Amankan API Key Anda!
API Key memberikan akses penuh untuk membuat transaksi atas nama akun Anda. Jangan pernah membagikan API Key Anda di forum publik, repositori GitHub (kecuali di dalam .env), atau aplikasi client-side (seperti React/Vue di sisi browser).
Sandbox Mode (Testing Environment)
Kami menyediakan **Sandbox Mode** agar Anda dapat menguji integrasi API QRIS dan USDT RCB Pay secara menyeluruh tanpa perlu melakukan transaksi dengan uang sungguhan.
API Keys Sandbox
Untuk masuk ke mode testing, gunakan API Key dengan awalan khusus yang dapat Anda salin dari Dashboard Developer Anda:
Simulator Pembayaran
Saat membuat invoice menggunakan API Key Sandbox, halaman pembayaran (payment_url) akan secara otomatis menampilkan tombol simulator pembayaran **"🧪 SIMULASI BAYAR"**.
Langkah Pengujian Sandbox
-
Buat Tagihan Sandbox: Panggil endpoint
/gateway/createdengan menyertakan headerx-api-key: rcb_sandbox_xxxxxx. -
Buka Payment URL: Ambil link
payment_urlyang dikembalikan oleh server, lalu buka di browser Anda. - Simulasi Sukses: Di halaman instruksi pembayaran, klik tombol berwarna hijau bertuliskan **"Simulasikan Pembayaran Sukses"**.
-
Terima Webhook Instant: Server RCB secara otomatis akan mengirimkan payload Webhook dengan status
"status": "PAID"ke URL Webhook Anda disertai signature yang valid untuk diverifikasi sistem Anda.
Catatan Keamanan Sandbox
Signature validasi webhook dihitung menggunakan rumus yang sama, namun menggunakan API Key Sandbox Anda sebagai *salt* hashing. Pastikan aplikasi Anda mendukung peralihan key ini saat beralih dari sandbox ke live production.
Pilihan Payment Method (Channels)
RCB Pay mendukung berbagai metode pembayaran populer. Anda dapat membatasi pilihan pembayaran yang tampil pada halaman checkout dengan menambahkan parameter query methods pada payment_url (contoh: payment_url + "&methods=qris" untuk membatasi hanya QRIS).
Kontrol Metode Pembayaran Dashboard
Metode pembayaran yang tampil pada halaman checkout juga dikontrol secara global melalui menu "Metode Pembayaran" pada Dashboard Developer Anda. Jika suatu metode dinonaktifkan di Dashboard, metode tersebut tidak akan ditampilkan kepada pelanggan Anda meskipun diizinkan via API/URL query.
| Kode Channel | Nama Metode | Kategori |
|---|---|---|
| qris | QRIS Dinamis (Mandiri, BCA, GoPay, OVO, Dana, ShopeePay) | E-Wallet & Scan Bank |
| usdt | Kripto USDT (TRC20, ERC20, BEP20, TON, SOL, NEAR) | Stablecoin / Crypto |
| va | Semua Virtual Account Bank Terintegrasi (Cooming soon / via Partner) | Transfer Bank |
| pulsa | Pulsa Seluler (Telkomsel, XL, Axis, Smartfren, Tri) | Transfer Pulsa |
| cimb_niaga_va | CIMB Niaga VA | Transfer Bank (VA) |
| bni_va | BNI VA | Transfer Bank (VA) |
| sampoerna_va | Sahabat Sampoerna VA | Transfer Bank (VA) |
| bnc_va | BNC Bank Neo Commerce VA | Transfer Bank (VA) |
| maybank_va | Maybank VA | Transfer Bank (VA) |
| permata_va | Permata Bank VA | Transfer Bank (VA) |
| atm_bersama_va | ATM Bersama VA | Transfer Bank (VA) |
| artha_graha_va | Artha Graha VA | Transfer Bank (VA) |
| bri_va | BRI VA | Transfer Bank (VA) |
Integrasi PHP (Source Code Lengkap)
Berikut adalah contoh source code lengkap untuk membuat tagihan dan menerima webhook sukses menggunakan PHP native.
1. Membuat Tagihan (Create Payment)
<?php // rcb-create-payment.php // 1. Konfigurasi Kunci $apiKey = "rcb_sandbox_test_55a12f990ac841bc82b5"; // Ganti dengan API Key Live di produksi $apiUrl = "https://api.ragaciptabersama.web.id/api/gateway/create"; // 2. Payload Data Transaksi $payload = [ "amount" => 50000, "item_name" => "Topup Diamond Free Fire", "customer_name" => "Rian Hidayat", "customer_email" => "rian@gmail.com", "external_id" => "ORDER-10029" // ID invoice dari database Anda ]; // 3. Kirim Request via cURL $ch = curl_init($apiUrl); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload)); curl_setopt($ch, CURLOPT_HTTPHEADER, [ "Content-Type: application/json", "x-api-key: " . $apiKey ]); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); // 4. Proses Hasil Response if ($httpCode === 200 || $httpCode === 201) { $result = json_decode($response, true); if ($result['success']) { $paymentUrl = $result['data']['payment_url']; $orderId = $result['data']['order_id']; // CONTOH MEMBATASI METODE PEMBAYARAN (QRIS ONLY atau USDT ONLY) // Cukup tambahkan parameter &methods=qris atau &methods=usdt pada URL pembayaran $qrisOnlyUrl = $paymentUrl . "&methods=qris"; $usdtOnlyUrl = $paymentUrl . "&methods=usdt"; echo "Sukses Membuat Invoice!
"; echo "Order ID RCB: " . $orderId . "
"; echo "Standard Link: <a href='$paymentUrl' target='_blank'>Bayar Sekarang</a>
"; echo "QRIS Only Link: <a href='$qrisOnlyUrl' target='_blank'>Bayar via QRIS Saja</a>
"; echo "USDT Only Link: <a href='$usdtOnlyUrl' target='_blank'>Bayar via USDT Saja</a>
"; } else { echo "Gagal: " . $result['message']; } } else { echo "Gagal HTTP Request dengan status code: " . $httpCode; echo " Response: " . $response; } ?>
2. Menerima Notifikasi Pembayaran (Webhook Callback)
Endpoint callback Anda harus memvalidasi data signature untuk memastikan keamanan data sebelum memperbarui status pesanan di database lokal.
<?php // rcb-callback-handler.php // Kunci API Key yang sama dengan saat pembuatan tagihan $apiKey = "rcb_sandbox_test_55a12f990ac841bc82b5"; // 1. Ambil payload JSON dari server RCB $rawPayload = file_get_contents('php://input'); $data = json_decode($rawPayload, true); if (!$data) { http_response_code(400); echo "Invalid JSON payload"; exit; } $orderId = $data['order_id']; $externalId = $data['external_id']; $status = $data['status']; $signatureReceived = $data['signature']; // 2. Hitung signature pembanding // Rumus: SHA256(order_id + status + api_key) $signatureLocal = hash('sha256', $orderId . $status . $apiKey); // 3. Cocokkan Signature if ($signatureReceived === $signatureLocal) { // Signature Valid! if ($status === 'PAID') { // Jalankan logika lunas di database Anda // Contoh: update_order_status_to_paid($externalId); // BERIKAN RESPONSE 200 OK UNTUK MENCEGAH RETRY WEBHOOK http_response_code(200); echo "OK"; } else { echo "Status pending atau gagal: " . $status; } } else { // Signature salah! Kemungkinan palsu / manipulasi data http_response_code(403); echo "Forbidden: Signature Mismatch"; }
WooCommerce Plugin
Bagi Anda yang menggunakan toko online berbasis WordPress dan WooCommerce, Anda tidak perlu melakukan integrasi API secara manual dari awal. Kami menyediakan Plugin resmi yang siap pakai.
Download RCB Gateway Plugin
Versi 1.0.0 • Mendukung WooCommerce v5.0+
Upload file ZIP ke menu Plugins > Add New di WordPress Anda.
Masukkan Merchant UID dan API Key rahasia Anda.
Setup URL Webhook dan pesanan WooCommerce Anda akan otomatis lunas saat dibayar.
Menerbitkan Tagihan (QRIS & USDT)
/gateway/create
Endpoint ini digunakan untuk membuat URL tagihan yang mendukung pembayaran QRIS dinamis dan transfer Kripto (USDT) secara instan. Sistem kami akan otomatis menyesuaikan nominal tagihan dengan kode unik dan mengelola konversi USDT agar transaksi bisa tervalidasi secara otomatis.
Pilihan Integrasi Pembayaran
Arahkan pelanggan langsung ke payment_url yang dikembalikan oleh API. Pelanggan akan diarahkan ke halaman checkout resmi RCB Pay yang lengkap dengan QRIS, instruksi transfer, dan countdown timer.
Tampilkan QR Code langsung di website Anda (seperti popup/modal custom) menggunakan data qris_string (raw data QRIS) atau qris_url (url gambar QR).
Body Parameters
| Parameter | Keterangan |
|---|---|
|
amount
Integer • Required
|
Nominal tagihan murni (tanpa kode unik). Minimal Rp 1.000. |
|
item_name
String • Optional
|
Nama barang atau jasa yang dibeli (Max 50 karakter). |
|
external_id
String • Optional
|
ID Referensi internal pesanan dari
database/sistem Anda (contoh: INV-992). Sangat disarankan
untuk mempermudah rekonsiliasi. |
|
customer_name
String • Optional
|
Nama pelanggan. |
|
customer_email
String • Optional
|
Email pelanggan (berguna untuk pengiriman bukti pembayaran otomatis kelak). |
|
allowed_methods
String • Optional
|
Daftar metode pembayaran yang diizinkan untuk transaksi ini, dipisahkan dengan koma (contoh: qris,usdt). Jika tidak diisi, semua metode pembayaran yang aktif di Dashboard Developer Anda akan tersedia. |
Alur Integrasi Custom UI (Opsi 2)
Jika Anda memilih untuk tidak meredireksi pelanggan ke halaman kami dan ingin menampilkan QR Code di website Anda sendiri secara modal/popup (seperti screenshot BoyzGames), ikuti alur berikut:
Gunakan parameter qris_url langsung sebagai atribut src pada tag <img> Anda, atau generate QR Code sendiri menggunakan library JavaScript (seperti qrcode.js) dari raw string qris_string.
Setelah modal QR Code terbuka, buat fungsi JavaScript untuk memanggil API status /api/payment-status/{order_id} secara berkala (setiap 3 - 5 detik).
// Contoh JavaScript Polling di sisi client const checkInterval = setInterval(async () => { try { const res = await fetch(`https://api.ragaciptabersama.web.id/api/payment-status/${orderId}`); const result = await res.json(); if (result.success && result.data.status === 'PAID') { clearInterval(checkInterval); alert('Pembayaran Berhasil!'); // Arahkan ke halaman sukses atau update UI modal window.location.reload(); } } catch (err) { console.error('Error checking status:', err); } }, 3000); // Cek setiap 3 detik
Meskipun pengecekan status di halaman client/browser sudah sukses, pastikan proses update saldo/produk digital di backend Anda tetap didasarkan pada callback Webhook yang aman menggunakan validasi signature SHA-256.
curl -X POST https://api.ragaciptabersama.web.id/api/gateway/create \ -H "Content-Type: application/json" \ -H "x-api-key: rcb_live_xxxxxxxxx" \ -d '{ "amount": 50000, "item_name": "Topup Diamond ML", "customer_name": "Budi Santoso", "customer_email": "budi@gmail.com", "external_id": "ORDER-992" }'
{
"success": true,
"message": "Payment gateway generated successfully",
"order_id": "API-XYZ123ABC",
"payment_url": "https://ragaciptabersama.web.id/bayar.html?id=API-XYZ123ABC",
"amount": 50000,
"total_amount": 50134,
"kode_unik": 134,
"qris_string": "00020101021226380010ID.CO.QQ...",
"qris_url": "https://quickchart.io/qr?text=0002010102...",
"data": {
"order_id": "API-XYZ123ABC",
"external_id": "ORDER-992",
"amount": 50000,
"total_amount": 50134,
"payment_url": "https://ragaciptabersama.web.id/bayar.html?id=API-XYZ123ABC",
"qris_string": "00020101021226380010ID.CO.QQ...",
"qris_url": "https://quickchart.io/qr?text=0002010102...",
"expired_at": "2026-05-06T15:30:00.000Z"
}
}
Check QRIS Status
Endpoint ini digunakan untuk melakukan pengecekan status transaksi secara manual apabila Webhook Anda gagal menerima notifikasi dari server kami. Anda hanya memerlukan order_id yang didapatkan saat Create QRIS.
Endpoint URL
https://api.ragaciptabersama.web.id/api/payment-status/{order_id}
Query Parameters
-
order_idRequired stringID Pesanan internal dari RCB yang diterima saat memanggil Create QRIS (dimulai dengan "API-").
curl -X GET \ 'https://api.ragaciptabersama.web.id/api/payment-status/API-XYZ123ABC' \ -H 'x-api-key: YOUR_SECRET_API_KEY'
{
"success": true,
"data": {
"order_id": "API-XYZ123ABC",
"external_id": "ORDER-992",
"status": "PAID",
"harga": 50000,
"total_amount": 50134,
"payment_type": "QRIS",
"paid_at": "2026-05-06 15:05:12",
"created_at": "2026-05-06 14:30:00"
}
}
Webhook Callback (Notifikasi)
Setelah pelanggan Anda melakukan pembayaran (baik QRIS maupun USDT) dan dana berhasil divalidasi, server RCB akan secara otomatis mengirimkan notifikasi (Callback) ke URL Webhook yang Anda atur di Dashboard Mitra.
Request ini akan dikirim menggunakan method POST dengan format application/json. Selain di body, signature juga dikirimkan melalui header X-RCB-Signature.
Payload JSON yang Dikirim Server RCB
{
"order_id": "API-XYZ123ABC",
"external_id": "ORDER-992",
"status": "PAID",
"amount": 50000,
"total_amount": 50134,
"payment_type": "USDT",
"paid_at": "2026-05-06T15:05:12.000Z",
"signature": "b6a4a9c8f1..."
}
Penting:
Server Anda wajib membalas notifikasi ini dengan HTTP Status 200 OK. Jika tidak membalas dengan 200, RCB akan menganggap Webhook gagal dan mungkin mengulang pengiriman (retry) beberapa kali.
Security (Signature Validation)
Untuk memastikan bahwa notifikasi Webhook yang diterima server Anda benar-benar berasal dari RCB Bisnis (bukan hacker), kami menyertakan parameter signature di dalam payload JSON Webhook dan header X-RCB-Signature.
Signature ini dibuat menggunakan algoritma hash SHA-256 yang menggabungkan order_id, status, dan Secret API Key Anda.
Rumus Validasi Signature
Contoh implementasi di PHP:
// Tangkap JSON Webhook = file_get_contents('php://input'); = json_decode(, true); = "YOUR_SECRET_API_KEY"; // Buat signature pembanding di sisi server Anda = hash('sha256', ['order_id'] . ['status'] . ); if ( === ['signature']) { // Signature Valid! Asli dari RCB. if (['status'] === 'PAID') { // Update status pesanan di database Anda menjadi LUNAS echo "OK"; } } else { // Signature Gagal! Tolak request. http_response_code(403); echo "Forbidden"; }
Error Handling
API kami menggunakan HTTP status code standar untuk mengindikasikan status sebuah request. Kode
2xx berarti sukses, kode 4xx berarti ada kesalahan pada data yang Anda
kirim, dan 5xx berarti ada gangguan pada server
kami.
| Code | Keterangan |
|---|---|
| 200 | OK. Request berhasil diproses. |
| 400 | Bad Request. Parameter yang dikirim tidak sesuai (misal: nominal kosong atau di bawah minimum). |
| 401 | Unauthorized. API Key tidak ditemukan atau salah. |
| 405 | Method Not Allowed. Anda menggunakan metode HTTP yang salah (harus POST). |
| 500 | Server Error. Terdapat kendala di sistem utama RCB. Tim engineer kami akan segera mengatasinya. |