Developer

Dokumentasi API

Integrasikan pembayaran QRIS dan DANA ke website atau aplikasi Anda. Saat ini tersedia Mode Kasir (redirect ke halaman bayar).

Daftar & dapatkan API Key Masuk

QRIS & DANA
Callback otomatis
Cek status & saldo
Payout / transfer

Mode API sedang maintenance, jadi dokumentasinya disembunyikan sementara. Gunakan Mode Kasir.

Autentikasi

Contoh

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

Ini nilai contoh. Daftar untuk mendapat API Key dan Merchant UUID milik Anda. Bagian Uji Coba di paling bawah bisa dipakai dengan kredensial Anda sendiri.

Mode pembayaran

Mode Kasir (mode: "cashier")

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

1Terima Pembayaran

Mode Kasir

Customer diarahkan ke halaman bayar lewat checkout_url. method opsional.

POST/generateBuat Order — Mode Kasir

Request body

Body

{
  "username": "order-8841",
  "amount": 50000,
  "mode": "cashier",
  "method": "QRIS",
  "expire": 10,
  "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": 10,  "custom_ref": "INV-001"}'

2Cek Status

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"

Nilai status

pending menunggu pembayaran · success sudah dibayar · expired belum dibayar sampai 10 menit · cancelled dibatalkan.

3Callback

Callback / Webhook

Alur:

Buat endpoint di website toko Anda, mis. https://tokosaya.com/webhook/oktapayment
Salin URL itu, buka menu Integrasi API → isi kolom Callback / Webhook URL → Simpan
Saat customer berhasil bayar, server OKTA mengirim POST JSON ke URL tersebut
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';

4Saldo

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
}

5Payout / 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"}'

6Error

Checklist

• Header wajib: X-API-Key + X-Merchant-UUID (harus cocok)
• Amount harus integer (tanpa desimal), min Rp 10.000
• 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), maksimal 10 menit; transaksi yang belum dibayar otomatis menjadi expired
• Selama masih ada transaksi pending, pembuatan pembayaran, tarik dana, dan transfer dana baru ditolak (HTTP 409)
• API mode TopPay mungkin perlu whitelist merchant dari support TopPay

7Uji Coba

Isi Merchant UUID dan API Key Anda, lalu buka endpoint dan tekan Coba. Request dikirim dari browser Anda dan tidak disimpan.

Kredensial uji coba

Base URL

Merchant UUID

API Key

Siap mulai integrasi?

Daftar, lengkapi KYC, lalu ambil API Key dan Merchant UUID asli di dashboard. Di sana Anda juga bisa mencoba semua endpoint lewat menu Uji Coba API.

Daftar Masuk