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:

BASE_URL/pay/{slug}/{amount}?order_id={order_id}
  • 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:

BASE_URL/pay/yopedia/22000?order_id=240910HDE7C9

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.

BASE_URL/pay/yopedia/22000?order_id=240910HDE7C9&redirect=https://app.yopedia.com/invoices

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.

BASE_URL/pay/yopedia/22000?order_id=240910HDE7C9&qris_only=1

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

qris
bca_va
mandiri_va
bni_va
bri_va
permata_va
cimb_niaga_va
sampoerna_va
bnc_va
maybank_va
atm_bersama_va
artha_graha_va

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:

curl -L 'BASE_URL/api/paymentsimulation' \ -H 'Content-Type: application/json' \ -d '{ "project": "yopedia", "order_id": "INV123123", "api_key": "YOUR_API_KEY" }'

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:

curl -L 'BASE_URL/api/transactioncancel' \ -H 'Content-Type: application/json' \ -d '{ "project": "yopedia", "order_id": "INV123123", "api_key": "YOUR_API_KEY" }'

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"
  }
}