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)

https:// api.ragaciptabersama.web.id/api

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:

rcb_sandbox_test_55a12f990ac841bc82b5

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

  1. Buat Tagihan Sandbox: Panggil endpoint /gateway/create dengan menyertakan header x-api-key: rcb_sandbox_xxxxxx.
  2. Buka Payment URL: Ambil link payment_url yang dikembalikan oleh server, lalu buka di browser Anda.
  3. Simulasi Sukses: Di halaman instruksi pembayaran, klik tombol berwarna hijau bertuliskan **"Simulasikan Pembayaran Sukses"**.
  4. 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+

Download .ZIP
1. Install

Upload file ZIP ke menu Plugins > Add New di WordPress Anda.

2. Konfigurasi

Masukkan Merchant UID dan API Key rahasia Anda.

3. Siap Terima Bayaran

Setup URL Webhook dan pesanan WooCommerce Anda akan otomatis lunas saat dibayar.

Menerbitkan Tagihan (QRIS & USDT)

POST /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

Opsi 1: Redireksi (Halaman RCB)

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.

Sangat Mudah & Praktis
Opsi 2: Custom Tampilan (Modal/UI)

Tampilkan QR Code langsung di website Anda (seperti popup/modal custom) menggunakan data qris_string (raw data QRIS) atau qris_url (url gambar QR).

Sesuai Brand/UI Sendiri

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:

1 Render QR Code secara Dinamis

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.

2 Jalankan Polling Status (JavaScript Client)

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
3 Validasi Akhir via Webhook

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.

Example Request (cURL)
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"
}'
201 Created Response
{
  "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"
  }
}
GET

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

GET https://api.ragaciptabersama.web.id/api/payment-status/{order_id}

Query Parameters

  • order_id Required string

    ID Pesanan internal dari RCB yang diterima saat memanggil Create QRIS (dimulai dengan "API-").

cURL Request
curl -X GET \
  'https://api.ragaciptabersama.web.id/api/payment-status/API-XYZ123ABC' \
  -H 'x-api-key: YOUR_SECRET_API_KEY'
200 OK Response
{
  "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"
  }
}
POST

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

signature = SHA256(order_id + status + api_key)

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.