API Documentation

Selamat Datang di OnoPay API

OnoPay API menyediakan akses kepada sistem pembayaran digital yang aman dan efisien. API kami dirancang untuk memungkinkan merchant dan pihak ketiga mengintegrasikan layanan pembayaran dengan mudah.

📝 Catatan: API OnoPay tidak memerlukan autentikasi khusus. Semua endpoint dapat diakses secara publik tanpa API key atau token.

Informasi Teknis

Base URL:

https://onopay.web.id/api/v1

Format Response: JSON

Request Method: POST (untuk semua endpoint)

Content-Type: application/json

Memulai

Persyaratan

Koneksi internet yang stabil
Tools untuk membuat HTTP request (curl, Postman, atau HTTP client library)
Pemahaman dasar tentang REST API

Contoh Request Dasar dengan cURL

curl -X POST "https://onopay.web.id/api/v1/merchant/check-user" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "08123456789"
  }'

Contoh Request dengan JavaScript/Fetch

fetch('https://onopay.web.id/api/v1/merchant/check-user', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '08123456789'
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Contoh Request dengan Python

import requests

url = 'https://onopay.web.id/api/v1/merchant/check-user'
payload = {
    'phone_number': '08123456789'
}

response = requests.post(url, json=payload)
print(response.json())

Merchant API

POST https://onopay.web.id/api/v1/merchant/check-user

Memeriksa keberadaan pengguna berdasarkan nomor telepon dan mengembalikan informasi dasar pengguna.

Parameter Request

Parameter	Tipe	Status	Deskripsi
`phone_number`	string	Required	Nomor telepon pengguna (contoh: 08123456789)

Contoh Request

curl -X POST "https://onopay.web.id/api/v1/merchant/check-user" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "08123456789"
  }'

Response Success (200)

{
  "success": true,
  "message": "User ditemukan",
  "data": {
    "id": 1,
    "phone_number": "08123456789",
    "name": "Budi Santoso",
    "email": "budi@example.com",
    "status": "active"
  }
}

Response Error (404)

{
  "success": false,
  "message": "User tidak ditemukan",
  "data": null
}

POST https://onopay.web.id/api/v1/merchant/check-balance

Memeriksa saldo pengguna berdasarkan nomor telepon.

Parameter Request

Parameter	Tipe	Status	Deskripsi
`phone_number`	string	Required	Nomor telepon pengguna (contoh: 08123456789)

Contoh Request

curl -X POST "https://onopay.web.id/api/v1/merchant/check-balance" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "08123456789"
  }'

Response Success (200)

{
  "success": true,
  "message": "Balance ditemukan",
  "data": {
    "phone_number": "08123456789",
    "name": "Budi Santoso",
    "balance": 5000000
  }
}

Payment API

POST https://onopay.web.id/api/v1/payment/topup

Melakukan top-up saldo untuk seorang pengguna.

Parameter Request

Parameter	Tipe	Status	Deskripsi
`phone_number`	string	Required	Nomor telepon pengguna
`amount`	numeric	Required	Jumlah top-up (minimum: 1000)

Contoh Request

curl -X POST "https://onopay.web.id/api/v1/payment/topup" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "08123456789",
    "amount": 100000
  }'

Response Success (200)

{
  "success": true,
  "message": "Topup berhasil",
  "data": {
    "transaction_id": "TXN-1780366262-gUyZvt",
    "amount": 100000,
    "new_balance": 5100000,
    "status": "success"
  }
}

POST https://onopay.web.id/api/v1/payment/qr/generate

Menghasilkan kode QR untuk pembayaran. QR code ini dapat digunakan oleh pengguna lain untuk melakukan pembayaran.

Parameter Request

Parameter	Tipe	Status	Deskripsi
`phone_number`	string	Required	Nomor telepon penerima pembayaran
`amount`	numeric	Required	Jumlah pembayaran (minimum: 100)
`merchant_code`	string	Optional	Kode merchant pembayaran
`description`	string	Optional	Deskripsi pembayaran
`qr_mode`	string	Optional	Tipe QR: `single_use` (default) atau `reusable`

Catatan integrasi: OnoPay hanya mengembalikan qr_image berupa URL gambar QR. URL ini disimpan pada database qr_codes.qr_image, bukan mengirim file image mentah di response generate.

Contoh Request

curl -X POST "https://onopay.web.id/api/v1/payment/qr/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "08123456789",
    "amount": 50000,
    "merchant_code": "MERCHANT001",
        "description": "Pembayaran makanan",
        "qr_mode": "single_use"
  }'

Response Success (200)

{
  "success": true,
  "message": "QR code berhasil dibuat",
  "data": {
    "qr_code": "QR-ABCDEF123456",
    "amount": 50000,
    "merchant_code": "MERCHANT001",
        "qr_mode": "single_use",
    "expires_at": "2026-06-02T02:46:07+00:00",
        "description": "Pembayaran makanan",
        "qr_image": "https://domain-aktif/api/v1/payment/qr/image/QR-ABCDEF123456"
  }
}

POST https://onopay.web.id/api/v1/payment/qr/pay

Melakukan pembayaran menggunakan kode QR yang telah dihasilkan.

Parameter Request

Parameter	Tipe	Status	Deskripsi
`qr_code`	string	Required	Kode QR yang telah dihasilkan
`payer_phone`	string	Required	Nomor telepon pengguna yang melakukan pembayaran

Contoh Request

curl -X POST "http://127.0.0.1:8001/api/v1/payment/qr/pay" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_code": "QR-ABCDEF123456",
    "payer_phone": "08777888999"
  }'

Response Success (200)

{
  "success": true,
  "message": "Pembayaran berhasil",
  "data": {
    "transaction_id": "TXN-1780366262-qTOCzT",
    "payer_phone": "08777888999",
    "receiver_phone": "08123456789",
    "amount": 50000,
    "payer_new_balance": 4950000,
    "receiver_new_balance": 5050000,
    "status": "success"
  }
}

Complete Payment Flow (Alur Pembayaran Lengkap)

⭐ Alur Pembayaran Peer-to-Peer dengan QR Code

Berikut adalah alur lengkap transaksi pembayaran menggunakan OnoPay API:

Langkah 1: Penerima uang (Seller/Merchant) membuat permintaan pembayaran

POST /payment/qr/generate

Input: phone_number, amount, description, qr_mode (single_use/reusable)

↓ Sistem menghasilkan unique QR code ↓

Langkah 2: QR code dikomunikasikan ke pembayar

Via: WhatsApp, Email, SMS, atau media komunikasi lainnya

Integrasi pihak ketiga menggunakan URL qr_image dari response

QR code berlaku selama 30 menit

↓ Pembayar menerima dan menginput QR code ↓

Langkah 3: Pembayar memproses pembayaran

POST /payment/qr/pay

Input: qr_code, payer_phone

↓ Sistem validasi ↓

Validasi yang dilakukan sistem:

QR code ada di database
QR code status = "active" (belum digunakan)
QR code belum expired
Payer (pembayar) active status
Payer memiliki saldo >= jumlah pembayaran

Langkah 4: Transaksi Berhasil (✓) ⭐

✓ Kurangi saldo payer
✓ Tambah saldo receiver
✓ Buat transaction record dengan status "success"
✓ Tandai QR code sebagai "used"

💡 Keunggulan API OnoPay:

Tidak memerlukan autentikasi API Key - akses terbuka untuk semua pihak
Atomicity terjamin - jika salah satu step gagal, seluruh transaksi dibatalkan
Real-time processing - uang langsung transfer antar akun
Keamanan tingkat enterprise - semua data terenkripsi dan tervalidasi
Error handling lengkap - setiap kemungkinan error sudah ditangani

Skenario Error & Penanganan

Error 1: QR code tidak ditemukan (404)

{
  "success": false,
  "message": "QR code tidak ditemukan"
}

Error 2: Saldo tidak cukup (402)

{
  "success": false,
  "message": "Saldo tidak cukup"
}

Kategori status: 402 Payment Required sesuai standar HTTP

Error 3: QR code sudah digunakan/expired (403)

{
  "success": false,
  "message": "QR code tidak aktif atau sudah digunakan"
}

Error 4: User tidak aktif (403)

{
  "success": false,
  "message": "User tidak aktif"
}

Kode Response HTTP

Kode	Status	Deskripsi
200	OK	Request berhasil diproses
400	Bad Request	Parameter yang dikirim tidak valid atau kurang
402	Payment Required	Saldo pengguna tidak cukup untuk melakukan transaksi
403	Forbidden	User tidak aktif, QR code sudah expired, atau akses ditolak
404	Not Found	User atau QR code tidak ditemukan
500	Server Error	Terjadi kesalahan di sisi server

Struktur Response Error

Semua response error mengikuti format yang konsisten:

{
  "success": false,
  "message": "Deskripsi error",
  "data": null
}

OnoPay API Documentation

Versi 1.0 • Terakhir diperbarui: 03/08/2026 13:24

API ini tersedia untuk integrasi pihak ketiga. Support: contact@onopay.com