Alur integrasi pembayaran
Gunakan API key hanya dari backend website Anda. Browser customer akan diarahkan ke payment_url yang dibuat oleh ALTPAY.
payment_url dari backend Anda.
Autentikasi API
Semua request ke /api/v1/* wajib menggunakan API key merchant pada header Authorization.
https://propayment.site
Gunakan URL ini, bukan URL lokal atau URL dashboard. Base URL otomatis mengikuti subfolder instalasi.
oto_pg_••••••••
Dashboard → API & Integrasi. Jangan bagikan key ini kepada customer.
Authorization: Bearer YOUR_API_KEY
Content-Type: application/jsonPastikan production memakai HTTPS. Endpoint API mengizinkan CORS, tetapi CORS bukan pengganti keamanan API key.
/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
{
"amount": 150000,
"description": "Premium Membership",
"external_id": "ORDER-20260615-001",
"customer_name": "Budi Santoso",
"customer_email": "budi@example.com"
}Response berhasil
{
"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"
}
}| Field | Tipe | Keterangan |
|---|---|---|
amount | integer | Wajib. Nominal dalam Rupiah tanpa desimal. Untuk QRIS, minimal Rp 10.000 dan maksimal Rp 10.000.000. |
description | string | Opsional. Deskripsi yang tampil di halaman pembayaran. |
external_id | string | Opsional. ID order di sistem Anda untuk rekonsiliasi dan webhook. |
customer_name | string | Opsional. Nama customer yang ditampilkan. |
customer_email | string | Opsional. Email customer untuk disimpan pada invoice. |
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.
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.
// 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);data.qris_image sebagai <img src="...">. Pastikan customer tetap diarahkan ke payment_url atau menggunakan alur status yang benar.
/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
{
"invoice_id": 42
}Pending
{
"success": true,
"data": {
"invoice_id": 42,
"external_id": "ORDER-20260615-001",
"status": "PENDING",
"amount": 150000
}
}Status sudah dibayar
{
"success": true,
"data": {
"invoice_id": 42,
"external_id": "ORDER-20260615-001",
"status": "PAID",
"amount": 150000,
"paid_at": "2026-06-15T10:05:30.000Z"
}
}// 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);
}status: "PAID" dari webhook atau check-status.
Webhook invoice paid
Aktifkan URL webhook di Dashboard → Settings. ALTPAY mengirim POST JSON ketika invoice berubah menjadi lunas.
{
"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
// 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';event, membatasi ukuran payload, dan memverifikasi invoice melalui check-status sebelum fulfill order. Lakukan proses secara idempotent berdasarkan invoice_id.
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
$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
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);invoice_id, dan handler webhook.
Error codes & troubleshooting
Response error selalu berbentuk { "success": false, "error": "..." }. Jangan hanya membaca HTTP status; selalu periksa success.
| HTTP | Penyebab | Cara menangani |
|---|---|---|
400 | Amount bukan integer positif. | Kirim integer Rupiah positif (tanpa desimal). |
401 | API key tidak ada/tidak valid. | Periksa header Bearer dan key di Dashboard. |
403 | API key salah, akun nonaktif, atau akun diblokir. | Cek kembali API key dan status akun di dashboard. |
404 | Invoice tidak ditemukan atau milik merchant lain. | Simpan invoice_id saat create invoice. |
409 | external_id sudah dipakai dengan nominal berbeda. | Pakai external_id baru, atau samakan amount dengan invoice sebelumnya. |
502/503 | Gateway 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. |
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.
| Status | Arti | Perubahan saldo |
|---|---|---|
PENDING | Pengajuan menunggu persetujuan. | Nominal ditahan — dipotong dari saldo tersedia saat diajukan. |
PROCESSING | Dana sedang dikirim ke rekening/e-wallet tujuan. | Tertahan. |
COMPLETED | Transfer berhasil diterima tujuan. | Tercatat pada saldo terkirim (total_settled). |
REJECTED | Transfer gagal atau ditolak sistem bank. | Dikembalikan 100% ke saldo tersedia — bisa diajukan ulang. |
POST /api/user/login. Token ini stateless (tanpa expiry), jadi cukup diambil sekali lalu simpan di backend / secret manager kamu.
Langkah 0 · Dapatkan token
{
"email": "merchant@kamu.com",
"password": "********"
}{
"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.
/api/user/withdraw
Saldo & riwayat penarikan
{
"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"
}
]
}
}/api/user/withdraw
Ajukan penarikan
{
"token": "TOKEN_DARI_POST /api/user/login",
"amount": 500000,
"method": "bank",
"bank_name": "BCA",
"account_number": "1234567890",
"account_name": "Budi Santoso"
}Response pengajuan
{
"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"
}
}| Field | Tipe | Keterangan |
|---|---|---|
amount | integer | Wajib. Nominal penarikan dalam Rupiah tanpa desimal. Minimal min_withdraw dan maksimal saldo tersedia. |
method | string | Opsional, default gopay. Pilihan: gopay (e-wallet), bank (transfer bank), qris. |
bank_name | string | Wajib bila method: "bank". Contoh BCA, Mandiri, BNI, BRI — atau kode bank 3 digit (014). |
account_number | string | Wajib. Nomor rekening atau nomor e-wallet tujuan. |
account_name | string | Wajib. Nama pemilik rekening — diverifikasi ke penyedia payout sebelum transfer dikirim. |
token | string | Wajib. 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. |
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.
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.
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.