Docs (Panduan Integrasi)
Diperbarui 05 Agu 2026
A. Persiapan
Pertama Anda bisa lakukan dengan mendaftar/login. Setelah itu mulailah dengan membuat Proyek.
A.1. Proyek
Proyek adalah identitas dari aplikasi/website Anda. Jadi, dengan satu akun YoPedia, Anda dapat mengintegrasikan untuk banyak website/aplikasi. Yaitu dengan membuat proyek untuk masing-masing website/aplikasi.
Yang perlu dicatat disini adalah Slug dan Api Key dari proyek Anda. Kedua hal ini nantinya akan Anda butuhkan untuk melakukan integrasi.
A.2. Biaya Transaksi (Fee)
Setiap transaksi memiliki biaya layanan yang bervariasi tergantung metode pembayaran dan nominal transaksi. Biaya ini sudah otomatis dihitung oleh sistem.
📌 Yang Perlu Anda Ketahui:
| Field API | Penjelasan |
|---|---|
amount |
Nominal asli transaksi yang Anda kirimkan |
fee |
Total biaya layanan yang dikenakan untuk transaksi ini |
total / total_payment |
Jumlah yang harus dibayar customer (amount + fee) |
💡 Contoh:
Anda membuat invoice dengan amount: 100000 menggunakan metode qris. API akan mengembalikan:
{
"amount": 100000,
"fee": 1500,
"total_payment": 101500
}
Customer membayar Rp 101.500, dan saldo Anda akan bertambah Rp 100.000 (nominal asli).
Untuk mengetahui fee setiap metode pembayaran sebelum membuat transaksi, gunakan API Get Payment Methods (lihat bagian C.2.8).
B. Integrasi Via URL
Untuk mengarahkan pelanggan Anda ke halaman pembayaran, cukup gunakan URL berikut:
- slug diambil dari proyek yang Anda miliki
- amount merupakan nominal transaksi tanpa titik dan spasi. contoh: 100000 atau 25000
- order_id adalah ID dari transaksi atau invoice di sistem Anda. contoh: INV20240910-123456 atau 1298
Berikut adalah contoh penggunaan yang benar:
B.1. Opsi: Custom Redirect
Akan muncul tombol [Kembali ke Halaman Merchant] setelah user berhasil melakukan pembayaran. Dan defaultnya akan diarahkan ke halaman sebelumnya.
Untuk mengarahkan user ke halaman khusus, tambahkan redirect=https://websitekamu.com/tujuan pada URL.
B.2. Opsi: Hanya QRIS
Untuk mengaktifkan hanya QRIS, sehingga pengunjung langsung melihat QR code dan tidak bisa mengubah ke metode pembayaran lain.
Tambahkan qris_only=1 pada URL.
C. Integrasi Via API
Disini Anda membutuhkan API Key yang terdapat di halaman detail Proyek.
C.1. Penjelasan Alur Integrasi API
Integrasi via API YoPedia terbagi menjadi 2 pendekatan utama:
- Create Invoice (Tanpa Metode): API ini mengembalikan tautan pembayaran (
payment_link) menuju halaman pemilihan metode pembayaran hijau pada YoPedia. Pelanggan Anda dapat memilih sendiri cara membayarnya di sana. - Create Transaction V2 (Spesifik Metode): Anda menentukan sendiri metode pembayaran secara terprogram dari API (misal
qris,bni_va). Respons akan langsung mengembalikan nomor pembayaran/string QRIS (payment_number) serta link halaman detail rincian pembayaran YoPedia (payment_link) yang memuat instruksi pembayaran.
Catatan Penting: Untuk Virtual Account (VA), halaman detail YoPedia akan langsung menyajikan nomor VA dan panduan pembayarannya secara internal tanpa perlu pengalihan ke pihak ketiga. Khusus untuk pembayaran E-Wallet, respons API menyertakan payment_url untuk meluncurkan aplikasi pembayaran terkait (ShopeePay, OVO, LinkAja).
C.2. API: Transaction create
- Method: POST
- URL: BASE_URL/api/transactioncreate/{method}
Body (JSON):
{
"project": "yopedia",
"order_id": "INV123123",
"amount": 99000,
"expiry_period": 60,
"api_key": "YOUR_API_KEY"
}
* Parameter expiry_period (opsional): Menentukan waktu kadaluarsa invoice dalam menit (min: 5 menit, max: 1440 menit / 24 jam. Default: 60 menit).
Contoh Request Kode:
<?php
$ch = curl_init('BASE_URL/api/transactioncreate/qris');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'project' => 'yopedia',
'order_id' => 'INV123123',
'amount' => 99000,
'expiry_period' => 60,
'api_key' => 'YOUR_API_KEY'
])
]);
$res = curl_exec($ch);
curl_close($ch);
$data = json_decode($res, true);
print_r($data);
Contoh Response (QRIS):
{
"payment": {
"project": "yopedia",
"order_id": "INV123123",
"amount": 99000,
"fee": 1000,
"total_payment": 100000,
"payment_method": "qris",
"payment_number": "00020101021226610016ID.CO.SHOPEE.WWW01189360091800216005...",
"va_number": "",
"payment_url": "",
"qr_string": "00020101021226610016ID.CO.SHOPEE.WWW01189360091800216005...",
"qris_image": "BASE_URL/public/uploads/qris/INV123123.png",
"payment_link": "BASE_URL/payment/detail/INV123123",
"expired_at": "2026-09-19T01:18:49+07:00"
}
}
Contoh Response (Virtual Account - BNI / BRI / Mandiri):
{
"payment": {
"project": "yopedia",
"order_id": "INV123123",
"amount": 99000,
"fee": 4000,
"total_payment": 103000,
"payment_method": "bri_va",
"payment_number": "1308200985000957",
"va_number": "1308200985000957",
"payment_url": "",
"qr_string": "",
"qris_image": "",
"payment_link": "BASE_URL/payment/detail/INV123123",
"expired_at": "2026-09-19T01:18:49+07:00"
}
}
Contoh Response (E-Wallet - ShopeePay / OVO / LinkAja):
{
"payment": {
"project": "yopedia",
"order_id": "INV123123",
"amount": 99000,
"fee": 1500,
"total_payment": 100500,
"payment_method": "shopeepay",
"payment_number": "https://sandbox.yo.com/topup/topupdirectv2.aspx?ref=SA26R8QLD1DJOSWIR2A",
"va_number": "",
"payment_url": "https://sandbox.yo.com/topup/topupdirectv2.aspx?ref=SA26R8QLD1DJOSWIR2A",
"qr_string": "",
"qris_image": "",
"payment_link": "BASE_URL/payment/detail/INV123123",
"expired_at": "2026-09-19T01:18:49+07:00"
}
}
C.2.5. API: Create Transaction (Tanpa Metode Pembayaran)
Gunakan endpoint ini jika Anda ingin membuat invoice tanpa menentukan metode pembayaran di awal. Pelanggan nantinya akan memilih metode pembayarannya sendiri pada link pembayaran yang dihasilkan.
- Method: POST
- URL: BASE_URL/api/transactioncreate
Body (JSON):
{
"project": "yopedia",
"order_id": "INV123123",
"amount": 99000,
"api_key": "YOUR_API_KEY",
"redirect_url": "https://domain-anda.com/finish"
}
Contoh Response:
{
"invoice_id": "INV09dcb0c9b",
"amount": 99000,
"fee": 0,
"total": 99000,
"qris_image": "",
"payment_link": "BASE_URL/payment/INV09dcb0c9b",
"expired_at": "2026-09-19T01:18:49+07:00",
"order_id": "INV123123"
}
C.2.8. API: Dapatkan Metode Pembayaran & Biaya Admin (Fee)
Gunakan endpoint ini untuk mendapatkan daftar metode pembayaran yang aktif beserta biaya admin (fee) dinamis yang disesuaikan dengan nominal transaksi.
- Method: GET
- URL: BASE_URL/api/payment/methods?project={slug}&amount={amount}&api_key={api_key}
Contoh Response:
{
"success": true,
"project": "yopedia",
"amount": 50000,
"payment_methods": [
{
"code": "qris",
"name": "QRIS",
"fee": 1000,
"total_payment": 51000,
"min_amount": 1000
},
{
"code": "bni_va",
"name": "BNI Virtual Account",
"fee": 4000,
"total_payment": 54000,
"min_amount": 10000
}
]
}
C.3. Pilihan Payment Method
C.4. API: Payment simulation
Jika proyek Anda masih di mode Sandbox, Anda dapat lakukan simulasi pembayaran untuk mengetes webhook.
- Method: POST
- URL: BASE_URL/api/paymentsimulation
{
"project": "yopedia",
"order_id": "INV123123",
"api_key": "YOUR_API_KEY"
}
Contoh CURL:
C.5. API: Transaction Cancel
Anda dapat membatalkan transaksi jika memang dibutuhkan. Silakan gunakan API berikut untuk melakukannya:
- Method: POST
- URL: BASE_URL/api/transactioncancel
{
"project": "yopedia",
"order_id": "INV123123",
"api_key": "YOUR_API_KEY"
}
Contoh CURL:
D. Webhook
Ketika pelanggan berhasil melakukan pembayaran dan dana masuk ke sistem kami, maka kami akan memberitahukan sistem Anda melalui webhook.
Kami akan mengirimkan HTTP POST dengan struktur body sebagai berikut:
{
"amount": 22000,
"fee": 1500,
"total": 23500,
"order_id": "240910HDE7C9",
"project": "yopedia",
"status": "completed",
"payment_method": "qris",
"completed_at": "2024-09-10T08:07:02.819+07:00"
}
Penting: Saat menerima webhook pastikan signature `X-YoPedia-Signature`, amount, dan order_id sesuai dengan transaksi di sistem Anda.
Contoh Receiver Webhook (Server Anda):
<?php
$json = file_get_contents('php://input');
$data = json_decode($json, true);
$signature = $_SERVER['HTTP_X_YOPEDIA_SIGNATURE'] ?? '';
$apiKey = 'YOUR_PROJECT_API_KEY';
$calcSig = hash_hmac('sha256', $json, $apiKey);
if (hash_equals($calcSig, $signature)) {
if ($data['status'] === 'completed') {
// Pembayaran sukses! Update database merchant Anda
$orderId = $data['order_id'];
}
http_response_code(200);
echo json_encode(['status' => 'success']);
} else {
http_response_code(403);
echo json_encode(['error' => 'Invalid signature']);
}
E. Transaction Detail API
Untuk mengetahui status sebuah transaksi Anda bisa lakukan melalui API ini. Disini Anda membutuhkan API Key yang terdapat di halaman detail Proyek.
- Method: GET
- URL: BASE_URL/api/transactiondetail?project={slug}&amount={amount}&order_id={order_id}&api_key={api_key}
Contoh Request Kode (Cek Status):
<?php
$url = 'BASE_URL/api/transactiondetail?project=yopedia&amount=22000&order_id=240910HDE7C9&api_key=YOUR_API_KEY';
$response = file_get_contents($url);
$data = json_decode($response, true);
print_r($data);
Contoh Response:
{
"transaction": {
"amount": 22000,
"fee": 1500,
"total": 23500,
"order_id": "240910HDE7C9",
"project": "yopedia",
"status": "completed",
"payment_method": "qris",
"completed_at": "2024-09-10T08:07:02.819+07:00"
}
}