OKTA payment
Dokumentasi Masuk Daftar
Developer

Dokumentasi API

Integrasikan pembayaran QRIS dan DANA ke website / aplikasi Anda. Tersedia dua mode: Kasir (redirect) dan API (data langsung).

Nilai API Key dan Merchant UUID di bawah hanyalah contoh. Masuk atau daftar untuk melihat kredensial asli akun Anda. Masuk Daftar
Autentikasi

Setiap request ke endpoint /v1/* wajib menyertakan dua header: X-API-Key dan X-Merchant-UUID. Keduanya harus milik merchant yang sama. Ambil kredensial di menu Integrasi API. Jangan pernah expose API Key di frontend (browser) — panggil API dari server Anda.

Merchant UUID (contoh)
OK00000
API Key (contoh)
ok_live_xxxxxxxxxxxxxxxx
Header wajib
X-API-Key: ok_live_xxxxxxxxxxxxxxxx
X-Merchant-UUID: OK00000
Content-Type: application/json

Base URL: https://rest.oktapay.asia/api/v1
Dua mode pembayaran

1. Mode Kasir (mode: "cashier")

  1. Server Anda memanggil POST /v1/generate dengan mode: "cashier"
  2. API mengembalikan checkout_url
  3. Redirect customer ke checkout_url (halaman bayar TopPay)
  4. Customer bayar → status dikirim ke Callback URL Anda

2. Mode API (mode: "api")

  1. Server Anda memanggil POST /v1/generate dengan mode: "api" + method
  2. API mengembalikan data bayar langsung:
    • QRIS: pay_data_type: "QR_CODE", data = string QR
    • DANA: pay_data_type: "CASHIER_URL", data = link redirect ke app/web DANA
  3. Tampilkan QR / redirect customer sesuai method
  4. Setelah bayar, status dikirim ke Callback URL + bisa di-poll via /v1/checkstatus

1. Terima Pembayaran

POST /generate Buat Order — Mode Kasir
Request body
Body
{
  "username": "order-8841",
  "amount": 50000,
  "mode": "cashier",
  "method": "QRIS",
  "expire": 60,
  "custom_ref": "INV-001"
}
Response
JSON
{
  "status": true,
  "trx_id": "PRE20...",
  "type": "cashier",
  "mode": "cashier",
  "method": "QRIS",
  "amount": 50000,
  "fee": 1000,
  "checkout_url": "https://...cashier...",
  "expired_at": "2026-09-29T12:00:00+07:00"
}
Contoh cURL
curl -X POST https://rest.oktapay.asia/api/v1/generate \
  -H "X-API-Key: ok_live_xxxxxxxxxxxxxxxx" \
  -H "X-Merchant-UUID: OK00000" \
  -H "Content-Type: application/json" \
  -d '{  "username": "order-8841",  "amount": 50000,  "mode": "cashier",  "method": "QRIS",  "expire": 60,  "custom_ref": "INV-001"}'
POST /generate Buat Order — Mode API (QRIS)
Request body
Body
{
  "username": "order-8841",
  "amount": 50000,
  "mode": "api",
  "method": "QRIS",
  "expire": 60,
  "custom_ref": "INV-001"
}
Response
JSON
{
  "status": true,
  "trx_id": "PRE20...",
  "type": "qris",
  "mode": "api",
  "method": "QRIS",
  "pay_data_type": "QR_CODE",
  "data": "00020101021226...",
  "amount": 50000,
  "fee": 1000,
  "checkout_url": "https://yoursite/api/checkout/...",
  "expired_at": "2026-09-29T12:00:00+07:00"
}
Contoh cURL
curl -X POST https://rest.oktapay.asia/api/v1/generate \
  -H "X-API-Key: ok_live_xxxxxxxxxxxxxxxx" \
  -H "X-Merchant-UUID: OK00000" \
  -H "Content-Type: application/json" \
  -d '{  "username": "order-8841",  "amount": 50000,  "mode": "api",  "method": "QRIS",  "expire": 60,  "custom_ref": "INV-001"}'
POST /generate Buat Order — Mode API (DANA)
Request body
Body
{
  "username": "order-8842",
  "amount": 75000,
  "mode": "api",
  "method": "DANA",
  "expire": 30,
  "custom_ref": "INV-002"
}
Response
JSON
{
  "status": true,
  "trx_id": "PRE20...",
  "type": "cashier",
  "mode": "api",
  "method": "DANA",
  "pay_data_type": "CASHIER_URL",
  "data": "https://...dana...",
  "amount": 75000,
  "fee": 1500,
  "checkout_url": "https://...dana...",
  "expired_at": "2026-09-29T11:30:00+07:00"
}
Contoh cURL
curl -X POST https://rest.oktapay.asia/api/v1/generate \
  -H "X-API-Key: ok_live_xxxxxxxxxxxxxxxx" \
  -H "X-Merchant-UUID: OK00000" \
  -H "Content-Type: application/json" \
  -d '{  "username": "order-8842",  "amount": 75000,  "mode": "api",  "method": "DANA",  "expire": 30,  "custom_ref": "INV-002"}'
POST /checkstatus/{trx_id} Cek Status Pembayaran
Request body
Body
(body kosong / opsional)
Response
JSON
{
  "status": "success",
  "amount": 50000,
  "merchant_id": "OK00000",
  "trx_id": "PRE20...",
  "rrn": "123456",
  "created_at": "...",
  "finish_at": "..."
}
Contoh cURL
curl -X POST https://rest.oktapay.asia/api/v1/checkstatus/{trx_id} \
  -H "X-API-Key: ok_live_xxxxxxxxxxxxxxxx" \
  -H "X-Merchant-UUID: OK00000" \
  -H "Content-Type: application/json"
Callback / Webhook

Alur:

  1. Buat endpoint di website toko Anda, mis. https://tokosaya.com/webhook/oktapayment
  2. Salin URL itu, buka menu Integrasi API → isi kolom Callback / Webhook URL → Simpan
  3. Saat customer berhasil bayar, server OKTA mengirim POST JSON ke URL tersebut
  4. Website Anda verifikasi signature, update status order, lalu balas HTTP 200

Bukan sebaliknya: jangan isi URL callback OKTA ke website toko. Yang di-paste ke panel OKTA adalah URL endpoint milik toko Anda.

Signature: header X-Signature: sha256=... = HMAC_SHA256(webhook_secret, raw_body) (rahasia ada di menu Integrasi → Webhook Secret).

Request yang diterima website merchant
POST https://tokosaya.com/webhook/oktapayment
Content-Type: application/json
X-Signature: sha256=<HMAC_SHA256 webhook_secret atas raw body>
X-Timestamp: 2026-09-29T12:05:00.000000+00:00

{
  "amount": 50000,
  "terminal_id": "order-8841",
  "trx_id": "PRE20...",
  "rrn": "123456",
  "custom_ref": "INV-001",
  "vendor": "NOBU",
  "status": "success",
  "created_at": "2026-09-29T12:00:00.000000+00:00",
  "finish_at": "2026-09-29T12:05:00.000000+00:00"
}
Contoh handler PHP di website merchant
// Contoh verifikasi (PHP)
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$secret = 'WEBHOOK_SECRET_DARI_MENU_INTEGRASI'; // atau dari config
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('invalid signature');
}
$data = json_decode($raw, true);
// $data['status'] === 'success' → update order $data['custom_ref'] / $data['trx_id']
http_response_code(200);
echo 'OK';

2. Saldo

POST /balance Cek saldo merchant
cURL
curl -X POST https://rest.oktapay.asia/api/v1/balance \
  -H "X-API-Key: ok_live_xxxxxxxxxxxxxxxx" \
  -H "X-Merchant-UUID: OK00000" \
  -H "Content-Type: application/json"
Response
{
  "status": "success",
  "pending_balance": 0,
  "settle_balance": 1250000
}

3. Payout / Transfer

POST /inquiry Inquiry rekening
Request body
{
  "amount": 100000,
  "bank_code": "014",
  "account_number": "1234567890",
  "type": 1
}
Response
{
  "status": true,
  "inquiry_id": "TPINQ...",
  "account_name": "BUDI SANTOSO",
  "bank_code": "014",
  "account_number": "1234567890"
}
Contoh cURL
curl -X POST https://rest.oktapay.asia/api/v1/inquiry \
  -H "X-API-Key: ok_live_xxxxxxxxxxxxxxxx" \
  -H "X-Merchant-UUID: OK00000" \
  -H "Content-Type: application/json" \
  -d '{  "amount": 100000,  "bank_code": "014",  "account_number": "1234567890",  "type": 1}'
POST /transfer Transfer / Payout
Request body
{
  "amount": 100000,
  "bank_code": "014",
  "account_number": "1234567890",
  "account_name": "BUDI SANTOSO",
  "type": 1,
  "inquiry_id": "TPINQ...",
  "client_ref_id": "PAYOUT-001"
}
Response
{
  "status": true,
  "partner_ref_no": "TPREF...",
  "message": "Transfer submitted"
}
Contoh cURL
curl -X POST https://rest.oktapay.asia/api/v1/transfer \
  -H "X-API-Key: ok_live_xxxxxxxxxxxxxxxx" \
  -H "X-Merchant-UUID: OK00000" \
  -H "Content-Type: application/json" \
  -d '{  "amount": 100000,  "bank_code": "014",  "account_number": "1234567890",  "account_name": "BUDI SANTOSO",  "type": 1,  "inquiry_id": "TPINQ...",  "client_ref_id": "PAYOUT-001"}'
Contoh cURL lengkap — Payout
Payout flow
# 1. Inquiry
curl -X POST https://rest.oktapay.asia/api/v1/inquiry \
  -H "X-API-Key: ok_live_xxxxxxxxxxxxxxxx" \
  -H "X-Merchant-UUID: OK00000" \
  -H "Content-Type: application/json" \
  -d '{"amount":100000,"bank_code":"014","account_number":"1234567890","type":1}'

# 2. Transfer (pakai inquiry_id + account_name)
curl -X POST https://rest.oktapay.asia/api/v1/transfer \
  -H "X-API-Key: ok_live_xxxxxxxxxxxxxxxx" \
  -H "X-Merchant-UUID: OK00000" \
  -H "Content-Type: application/json" \
  -d '{"amount":100000,"bank_code":"014","account_number":"1234567890","account_name":"BUDI SANTOSO","type":1,"inquiry_id":"TPINQ...","client_ref_id":"PAYOUT-001"}'

4. Error & Tips

Checklist
• Header wajib: X-API-Key + X-Merchant-UUID (harus cocok)
• Amount harus integer (tanpa desimal), min Rp 10.000
• Mode API wajib kirim method: "QRIS" atau "DANA"
• Mode Kasir: method opsional, tapi disarankan diisi
• Selalu simpan trx_id & custom_ref di database Anda
• Jangan andalkan redirect saja — utamakan Callback + poll status
• Verifikasi X-Signature di webhook dengan webhook_secret
• expire dalam menit (bukan detik)
• API mode TopPay mungkin perlu whitelist merchant dari support TopPay