OTOPAY
Developer documentation

Integrasi Pembayaran ALTPAY

Panduan lengkap untuk menerima pembayaran QRIS di website Anda dan mencairkan dana lewat REST API.

BASE URL https://propayment.site
REST APIJSONBearer Auth
Mulai dalam 5 menit

Alur integrasi pembayaran

Gunakan API key hanya dari backend website Anda. Browser customer akan diarahkan ke payment_url yang dibuat oleh ALTPAY.

01Siapkan akunDaftar akun merchant, API key langsung aktif.
02Simpan API keyAmbil dari Dashboard → API.
03Buat invoicePOST dari server Anda.
04Terima pembayaranRedirect atau cek status.
Jangan pernah menaruh API key di JavaScript browser. API key adalah password merchant. Simpan di environment variable server, secret manager, atau database backend Anda. Endpoint pada halaman customer cukup menerima payment_url dari backend Anda.
1. Authentication

Autentikasi API

Semua request ke /api/v1/* wajib menggunakan API key merchant pada header Authorization.

BASE URL https://propayment.site

Gunakan URL ini, bukan URL lokal atau URL dashboard. Base URL otomatis mengikuti subfolder instalasi.

API KEY oto_pg_••••••••

Dashboard → API & Integrasi. Jangan bagikan key ini kepada customer.

HTTP headers
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Pastikan production memakai HTTPS. Endpoint API mengizinkan CORS, tetapi CORS bukan pengganti keamanan API key.

POST /api/v1/create-invoice

Membuat invoice QRIS

Endpoint ini membuat satu invoice, menghasilkan QRIS dinamis, dan mengembalikan halaman pembayaran yang siap dibuka customer.

Request body

JSON
{
  "amount": 150000,
  "description": "Premium Membership",
  "external_id": "ORDER-20260615-001",
  "customer_name": "Budi Santoso",
  "customer_email": "budi@example.com"
}

Response berhasil

JSON · 200
{
  "success": true,
  "data": {
    "invoice_id": 42,
    "external_id": "ORDER-20260615-001",
    "amount": 150000,
    "status": "PENDING",
    "payment_url": "https://domain-anda.com/pay/42",
    "qris_image": "data:image/png;base64,...",
    "expires_at": "2026-06-16T10:00:00.000Z",
    "created_at": "2026-06-15T10:00:00.000Z"
  }
}
FieldTipeKeterangan
amountintegerWajib. Nominal dalam Rupiah tanpa desimal. Untuk QRIS, minimal Rp 10.000 dan maksimal Rp 10.000.000.
descriptionstringOpsional. Deskripsi yang tampil di halaman pembayaran.
external_idstringOpsional. ID order di sistem Anda untuk rekonsiliasi dan webhook.
customer_namestringOpsional. Nama customer yang ditampilkan.
customer_emailstringOpsional. Email customer untuk disimpan pada invoice.
Setelah invoice dibuat: simpan invoice_id, external_id, dan payment_url di database Anda. Gunakan external_id yang unik dan stabil untuk retry. Jangan membuat invoice baru setiap kali customer me-refresh halaman.

Jika external_id yang sama dikirim ulang dengan nominal yang sama, ALTPAY mengembalikan invoice yang sama dengan tambahan field "duplicate": true (bukan invoice baru). Bila external_id sama tetapi amount berbeda, request ditolak dengan 409.
2. Customer flow

Redirect customer ke halaman pembayaran

Cara paling aman dan kompatibel lintas perangkat adalah mengarahkan customer ke payment_url. Halaman ALTPAY menangani QRIS dinamis dan polling status otomatis — customer cukup memindai QR dengan aplikasi bank atau e-wallet apa pun yang mendukung QRIS.

Browser → backend Anda
// Endpoint di bawah adalah endpoint backend website Anda,
// bukan endpoint ALTPAY. Backend sudah menyimpan invoice_id.

const response = await fetch('/api/orders/ORDER-20260615-001/payment-url', {
  credentials: 'same-origin'
});
const data = await response.json();

if (!response.ok || !data.payment_url) {
  throw new Error(data.error || 'Payment URL tidak tersedia');
}

window.location.assign(data.payment_url);
Alternatif: jika ingin menampilkan QRIS sendiri, gunakan nilai data.qris_image sebagai <img src="...">. Pastikan customer tetap diarahkan ke payment_url atau menggunakan alur status yang benar.
POST /api/v1/check-status

Cek status pembayaran

Gunakan endpoint ini dari backend atau worker. Panggil secara berkala hanya jika webhook belum tersedia. ALTPAY akan mengecek status ke gateway dan menandai invoice sebagai PAID ketika berhasil. Invoice PENDING yang melewati expires_at otomatis berubah menjadi BATAL dan tidak dapat dibayar lagi.

Request

JSON
{
  "invoice_id": 42
}

Pending

JSON · 200
{
  "success": true,
  "data": {
    "invoice_id": 42,
    "external_id": "ORDER-20260615-001",
    "status": "PENDING",
    "amount": 150000
  }
}

Status sudah dibayar

JSON · 200
{
  "success": true,
  "data": {
    "invoice_id": 42,
    "external_id": "ORDER-20260615-001",
    "status": "PAID",
    "amount": 150000,
    "paid_at": "2026-06-15T10:05:30.000Z"
  }
}
Node.js backend worker
// Jalankan dari backend/worker, jangan menaruh API key di browser.
const API_BASE = process.env.ALTPAY_BASE_URL;
const API_KEY = process.env.ALTPAY_API_KEY;

const response = await fetch(API_BASE + '/api/v1/check-status', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ invoice_id: 42 })
});

const result = await response.json();
if (result.success && result.data.status === 'PAID') {
  // baru fulfils order di sistem Anda
  await markOrderAsPaid(result.data.invoice_id, result.data.paid_at);
}
Jangan menganggap redirect customer sebagai bukti pembayaran. Finalisasi order hanya setelah menerima status: "PAID" dari webhook atau check-status.
3. Realtime callback

Webhook invoice paid

Aktifkan URL webhook di Dashboard → Settings. ALTPAY mengirim POST JSON ketika invoice berubah menjadi lunas.

Webhook payload
{
  "event": "invoice.paid",
  "data": {
    "invoice_id": 42,
    "external_id": "ORDER-20260615-001",
    "amount": 150000,
    "paid_at": "2026-06-15T10:05:30.000Z"
  }
}

URL webhook diatur di Dashboard → Pengaturan. Callback hanya dikirim saat invoice berpindah PENDING → PAID, dengan hingga 3 percobaan (backoff bertahap) selama endpoint Anda tidak membalas 2xx. Balas 200 secepat mungkin, lalu proses payload di latar belakang.

Contoh receiver PHP

PHP webhook receiver
<?php
// Endpoint ini harus ada di backend Anda.
// Contoh: https://website-anda.com/webhooks/ALTPAY

$payload = json_decode(file_get_contents('php://input'), true);

if (($payload['event'] ?? '') !== 'invoice.paid') {
    http_response_code(200);
    exit;
}

$invoiceId = (int) ($payload['data']['invoice_id'] ?? 0);
$externalId = (string) ($payload['data']['external_id'] ?? '');

if ($invoiceId < 1 || $externalId === '') {
    http_response_code(400);
    exit;
}

// Verifikasi kembali ke ALTPAY sebelum akhirnya fulfill order.
// Ganti helper ini dengan request POST /api/v1/check-status di backend Anda.
// Pastikan proses ini idempotent berdasarkan invoice_id / external_id.
verifyInvoiceWithALTPAY($invoiceId);

// Balas 2xx segera agar webhook tidak dianggap gagal.
http_response_code(200);
echo 'OK';
Catatan keamanan: payload webhook saat ini tidak membawa signature HMAC terpisah. Endpoint receiver wajib memakai HTTPS, memvalidasi event, membatasi ukuran payload, dan memverifikasi invoice melalui check-status sebelum fulfill order. Lakukan proses secara idempotent berdasarkan invoice_id.
4. Copy & paste

Contoh integrasi siap pakai

Gunakan contoh di bawah sebagai titik awal. Ganti `YOUR_API_KEY`, dan simpan key melalui environment variable pada production.

PHP cURL — create invoice dari server

PHP
<?php
$apiBase = 'https://propayment.site';
$apiKey  = getenv('ALTPAY_API_KEY') ?: 'YOUR_API_KEY';

$ch = curl_init($apiBase . '/api/v1/create-invoice');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 150000,
        'description' => 'Premium Membership',
        'external_id' => 'ORDER-' . time(),
        'customer_name' => 'Budi Santoso',
    ]),
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (empty($result['success'])) {
    http_response_code(502);
    exit(json_encode(['error' => $result['error'] ?? 'Gagal membuat invoice']));
}

// Simpan invoice_id di database Anda, lalu kirim payment_url ke browser.
echo json_encode([
    'invoice_id' => $result['data']['invoice_id'],
    'payment_url' => $result['data']['payment_url'],
]);

Node.js / Express — create invoice dari server

JavaScript server
const API_BASE = process.env.ALTPAY_BASE_URL || 'https://propayment.site';
const API_KEY = process.env.ALTPAY_API_KEY;

const response = await fetch(API_BASE + '/api/v1/create-invoice', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 150000,
    description: 'Premium Membership',
    external_id: 'ORDER-' + Date.now(),
    customer_name: 'Budi Santoso'
  })
});

const result = await response.json();
if (!response.ok || !result.success) {
  throw new Error(result.error || 'Gagal membuat invoice');
}

// Kirim payment_url ini ke frontend Anda.
console.log(result.data.invoice_id, result.data.payment_url);
Minimum production setup: PHP 8+ dengan cURL atau Node.js 18+, API key di secret/environment variable, HTTPS, database untuk menyimpan invoice_id, dan handler webhook.
5. Reference

Error codes & troubleshooting

Response error selalu berbentuk { "success": false, "error": "..." }. Jangan hanya membaca HTTP status; selalu periksa success.

HTTPPenyebabCara menangani
400Amount bukan integer positif.Kirim integer Rupiah positif (tanpa desimal).
401API key tidak ada/tidak valid.Periksa header Bearer dan key di Dashboard.
403API key salah, akun nonaktif, atau akun diblokir.Cek kembali API key dan status akun di dashboard.
404Invoice tidak ditemukan atau milik merchant lain.Simpan invoice_id saat create invoice.
409external_id sudah dipakai dengan nominal berbeda.Pakai external_id baru, atau samakan amount dengan invoice sebelumnya.
502/503Gateway QRIS belum dikonfigurasi, sedang bermasalah, atau amount di luar batas (Rp 10.000–Rp 10.000.000).Pastikan nominal dalam batas dan operator gateway sudah mengisi kredensial QRIS. Coba lagi dengan backoff.
6. Payout

Pencairan dana (payout)

Setiap pembayaran yang lunas masuk ke antrean settlement H+1 (setelah biaya transaksi): dana otomatis menjadi saldo tersedia merchant (balance_available) besok pukul 00.00, tanpa proses manual. Sisa dana yang belum jatuh tempo terlihat sebagai balance_pending pada response GET. Setelah jatuh tempo, pencairan berjalan otomatis: setelah pengajuan disetujui, dana dikirim ke rekening atau e-wallet tujuan lewat kanal payout terintegrasi (inquiry → transfer) — tanpa proses transfer manual.

StatusArtiPerubahan saldo
PENDINGPengajuan menunggu persetujuan.Nominal ditahan — dipotong dari saldo tersedia saat diajukan.
PROCESSINGDana sedang dikirim ke rekening/e-wallet tujuan.Tertahan.
COMPLETEDTransfer berhasil diterima tujuan.Tercatat pada saldo terkirim (total_settled).
REJECTEDTransfer gagal atau ditolak sistem bank.Dikembalikan 100% ke saldo tersedia — bisa diajukan ulang.
Pencairan otomatis & anti nyangkut: hasil setiap transfer dikonfirmasi lewat callback sistem. Bila callback telat atau tidak pernah sampai, ALTPAY otomatis mengecek ulang status transfer ke penyedia payout dan menyelesaikan sendiri statusnya (lunas, atau gagal + saldo kembali ke Anda). Callback ganda tidak pernah menggandakan saldo.
Token dari mana? Endpoint pencairan memakai token sesi login — yaitu email & password akun Dashboard ALTPAY kamu sendiri yang ditukar lewat POST /api/user/login. Token ini stateless (tanpa expiry), jadi cukup diambil sekali lalu simpan di backend / secret manager kamu.

Langkah 0 · Dapatkan token

JSON · request
{
  "email": "merchant@kamu.com",
  "password": "********"
}
JSON · 200
{
  "success": true,
  "data": {
    "token": "eyJ1c2VySWQiOjcsImVtYWlsIjoibWVyY2hhbnRAa2FtdS5jb20iLCJ0cyI6MTc2MTA1MDAwMDAwMH0",
    "user": {
      "id": 7,
      "email": "merchant@kamu.com",
      "storeName": "Toko Baru",
      "apiKey": "oto_pg_••••"
    }
  }
}

Nilai data.token itulah yang dikirim di setiap request pencairan (field "token" di body JSON, atau query ?token=). Bila akun mengaktifkan 2FA, tambahkan "code": "123456" sekali saat login. Contoh tanpa memanggil API: dari browser yang sedang masuk Dashboard, token tersimpan di localStorage dengan kunci pg_token (DevTools → Application → Local Storage); atau cukup pakai menu Dashboard → Penarikan tanpa perlu token sama sekali.

GET /api/user/withdraw

Saldo & riwayat penarikan

JSON · 200
{
  "success": true,
  "data": {
    "balance_available": 1250000,
    "balance_pending": 450000,
    "total_revenue": 14056200,
    "total_settled": 10000000,
    "min_withdraw": 50000,
    "withdraw_fee_percent": 2,
    "txn_fee_percent": 10,
    "withdrawals": [
      {
        "id": 18,
        "amount": 500000,
        "fee": 10000,
        "net_amount": 490000,
        "method": "bank",
        "bank_name": "BCA",
        "account_number": "1234567890",
        "account_name": "Budi Santoso",
        "status": "COMPLETED",
        "admin_note": null,
        "requested_at": "2026-10-18T09:12:00.000Z",
        "processed_at": "2026-10-18T09:13:20.000Z"
      }
    ]
  }
}
POST /api/user/withdraw

Ajukan penarikan

JSON · request
{
  "token": "TOKEN_DARI_POST /api/user/login",
  "amount": 500000,
  "method": "bank",
  "bank_name": "BCA",
  "account_number": "1234567890",
  "account_name": "Budi Santoso"
}

Response pengajuan

JSON · 200
{
  "success": true,
  "message": "Pengajuan penarikan Rp 490.000 berhasil dikirim! Menunggu transfer dari admin.",
  "data": {
    "id": 18,
    "amount": 500000,
    "fee": 10000,
    "net_amount": 490000,
    "status": "PENDING"
  }
}
FieldTipeKeterangan
amountintegerWajib. Nominal penarikan dalam Rupiah tanpa desimal. Minimal min_withdraw dan maksimal saldo tersedia.
methodstringOpsional, default gopay. Pilihan: gopay (e-wallet), bank (transfer bank), qris.
bank_namestringWajib bila method: "bank". Contoh BCA, Mandiri, BNI, BRI — atau kode bank 3 digit (014).
account_numberstringWajib. Nomor rekening atau nomor e-wallet tujuan.
account_namestringWajib. Nama pemilik rekening — diverifikasi ke penyedia payout sebelum transfer dikirim.
tokenstringWajib. Token sesi dari POST /api/user/login → data.token, dikirim di body JSON atau query ?token=. Contoh lengkap ada di Langkah 0 · Dapatkan token di atas.
Biaya & minimum: biaya transaksi (txn_fee_percent) sudah dipotong saat pembayaran masuk ke saldo. Saat menarik dana, biaya penarikan (withdraw_fee_percent) dihitung dari nominal: net_amount = amount − fee. Minimum penarikan dan persentase biaya yang berlaku dikembalikan oleh GET /api/user/withdraw — baca dari sana, jangan di-hardcode.
Beda autentikasi: endpoint pencairan memakai token sesi login (POST /api/user/login), bukan API key — jangan pakai oto_pg_•••• di sini. Untuk kebutuhan harian, cara paling aman adalah lewat Dashboard → Penarikan; gunakan API ini hanya bila sistem Anda perlu memantau saldo atau mengajukan penarikan secara terprogram.
Go live checklist

Checklist sebelum rilis

✓

Akun aktif dan API key valid.

✓

API key hanya berada di backend/secret manager.

✓

Setiap order punya external_id yang unik.

✓

Customer diarahkan ke payment_url yang dikembalikan API.

✓

Webhook handler melakukan verifikasi dan idempotency.

✓

Order baru di-fulfill setelah status PAID.

✓

Pencairan dana: tujuan rekening/e-wallet valid & biaya penarikan dipahami.