WistaPay Developer
Dokumentasi API
Integrasikan pembayaran QRIS ke aplikasi, website, atau backend Anda. Autentikasi dengan API Key, buat pembayaran, cek status, dan terima notifikasi otomatis.
Base URL
https://wistapay.shop/wistapay/api
Auth
Header X-API-Key
Format
JSON · UTF-8
1. Autentikasi
Setiap request ke API wajib menyertakan API Key di header. API Key dibuat otomatis saat registrasi dan dapat disalin di Dashboard.
X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxx
Jangan mengekspos API Key di frontend publik (browser). Panggil API dari server Anda.
2. Biaya transaksi
Fee hanya dikenakan saat pembayaran SUCCESS.
Pembebanan biaya (fee_bearer)
| Nilai | Client bayar | Merchant terima (net) |
|---|---|---|
| MERCHANT | amount |
amount − fee |
| CLIENT | amount + fee |
amount (penuh) |
Default fee_bearer diatur di
Pengaturan Fee.
Jika body request tidak mengirim fee_bearer, sistem memakai default akun.
3. Buat pembayaran
POST
https://wistapay.shop/wistapay/api/create-payment.php
Headers
Content-Type: application/json X-API-Key: sk_your_api_key
Body (JSON)
{
"amount": 10000,
"description": "Order #123",
"external_id": "INV-123",
"callback_url": "https://yourapp.com/payment/done",
"fee_bearer": "CLIENT"
}
Parameter
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
| amount | number | Ya | Nominal order. Min 1.000 · Max 9.998.000 |
| description | string | Tidak | Keterangan pembayaran |
| external_id | string | Tidak | ID dari sistem Anda (invoice, order id) |
| callback_url | string | Tidak | URL redirect setelah pembayaran |
| fee_bearer | string | Tidak | MERCHANT atau CLIENT. Default = pengaturan akun |
Response sukses HTTP 200
{
"success": true,
"data": {
"reference": "API20260817001ABCDEF",
"external_id": "INV-123",
"amount": 10000,
"charge_amount": 11070,
"fee": 1070,
"fee_fixed": 1000,
"fee_fixed_base": 100,
"units_thousand": 10,
"fee_percent": 0.7,
"fee_bearer": "CLIENT",
"net_amount": 10000,
"status": "PENDING",
"payment_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"qris_image": "https://...",
"payment_url": "https://...",
"expires_at": "2026-08-17T12:30:00+07:00"
}
}
amount— nominal order merchantcharge_amount— nominal yang harus dibayar di QRIS (sudah termasuk fee jika CLIENT)net_amount— yang akan masuk saldo merchant saat suksesqris_image/payment_url— tampilkan ke pembayarreference— simpan untuk cek status
4. Cek status pembayaran
GET
https://wistapay.shop/wistapay/api/check-status.php?reference=API...
Header: X-API-Key.
Jika status masih PENDING, sistem juga menyinkronkan ke gateway pembayaran.
Response
{
"success": true,
"data": {
"reference": "API20260817001ABCDEF",
"external_id": "INV-123",
"amount": 10000,
"fee": 1070,
"net_amount": 10000,
"status": "SUCCESS",
"source": "API",
"created_at": "2026-08-17 10:00:00",
"updated_at": "2026-08-17 10:05:12"
}
}
Nilai status
5. Webhook & saldo
Saat pembayaran berhasil, WistaPay menerima notifikasi dari gateway dan memperbarui transaksi
menjadi SUCCESS, lalu menambahkan net_amount ke saldo merchant.
- Endpoint webhook dikonfigurasi di server WistaPay (bukan di aplikasi merchant).
- Merchant cukup polling
check-status.phpatau menunggu user kembali viacallback_url. - Saldo masuk otomatis; tidak ada konfirmasi manual.
Disarankan: setelah user kembali ke aplikasi, panggil check-status sekali untuk memastikan status akhir.
6. Kode error
| HTTP | Arti | Penyebab umum |
|---|---|---|
| 400 | Bad request | amount < 1000, amount > maks, reference kosong |
| 401 | Unauthorized | API Key kosong / tidak valid |
| 403 | Forbidden | Akun diblokir |
| 404 | Not found | reference tidak ditemukan |
| 405 | Method not allowed | Bukan POST pada create-payment |
| 502 | Bad gateway | Gagal membuat QRIS di gateway |
7. Contoh integrasi
cURL — buat pembayaran
curl -X POST "https://wistapay.shop/wistapay/api/create-payment.php" \
-H "Content-Type: application/json" \
-H "X-API-Key: sk_your_api_key" \
-d '{
"amount": 10000,
"description": "Order #123",
"external_id": "INV-123",
"fee_bearer": "CLIENT"
}'
cURL — cek status
curl -X GET "https://wistapay.shop/wistapay/api/check-status.php?reference=API20260817001ABCDEF" \ -H "X-API-Key: sk_your_api_key"
PHP
$payload = json_encode([
'amount' => 10000,
'description' => 'Order #123',
'fee_bearer' => 'CLIENT',
]);
$ch = curl_init('https://wistapay.shop/wistapay/api/create-payment.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: sk_your_api_key',
],
]);
$res = json_decode(curl_exec($ch), true);
// $res['data']['qris_image'] → tampilkan QR
// $res['data']['reference'] → simpan untuk cek status
Node.js (fetch)
const res = await fetch('https://wistapay.shop/wistapay/api/create-payment.php', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'sk_your_api_key',
},
body: JSON.stringify({
amount: 10000,
description: 'Order #123',
fee_bearer: 'CLIENT',
}),
});
const json = await res.json();
// json.data.payment_url / json.data.qris_image
© 2026 WistaPay · Dokumentasi API produksi
Webhook Merchant
Atur URL di menu Setting. WistaPay mengirim POST JSON saat status berubah.
{
"event": "payment.success",
"status": "SUCCESS",
"reference": "API2026...",
"external_id": "order-123",
"amount": 10000,
"fee": 1070,
"net_amount": 8930,
"source": "API",
"merchant": "WistaPay",
"timestamp": "2026-10-01T15:00:00+07:00"
}
Event: payment.pending, payment.success, payment.expired, payment.failed. Header signature (jika secret diisi): X-WistaPay-Signature: sha256=...
Log pengiriman tersimpan di client webhook log documents (lihat di Setting / panel admin).
API · Virtual Account
Integrasi Virtual Account
Panduan khusus pembayaran Virtual Account melalui API Key WistaPay. Alur ini berbeda dari QRIS: customer mentransfer ke nomor VA, status diperbarui lewat webhook / check status, dan saldo merchant di-settle pada H+1 pukul 08:00 WIB (Sabtu–Minggu tidak di-settle).
Alur integrasi (ringkas)
- Merchant memanggil
POST /api/create-payment.phpdenganmethodbank VA (contohBNI_VA). - WistaPay membuat VA dan mengembalikan
va_number,invoice_url,reference, nominal tagihan. - Tampilkan
invoice_urlke customer (atau bangun UI sendiri memakaiva_number). - Customer transfer tepat sesuai nominal sebelum jatuh tempo.
- Status lunas diterima lewat webhook merchant, atau di-poll lewat check status / halaman invoice (tombol Check Status).
- Setelah lunas: status transaksi
SUCCESS. Saldo merchant masuk setelah settlement H+1 08:00 (hari kerja). - Tipe va yang dapat digunakan:[C] One Off
1. Buat pembayaran VA
Endpoint
POST https://wistapay.shop/wistapay/api/create-payment.php
Header wajib
X-API-Key: sk_your_api_key Content-Type: application/json
Body JSON
| Field | Wajib | Keterangan |
|---|---|---|
| amount | Ya | Nominal produk (integer, min 1000) |
| method | Ya | Kode metode VA, lihat daftar di bawah |
| description | Tidak | Nama produk / keterangan (tampil di invoice) |
| external_id | Tidak | ID pesanan di sistem Anda (nomor pesanan) |
| callback_url | Tidak | Override webhook per transaksi (opsional) |
| va_trx_type | Tidak | C One Off · O Open Recurring · R Close Recurring. Default: konfigurasi Setting merchant. BNI / Mandiri / Mandiri PC hanya C. |
| va_name | Tidak | Nama pada VA (5–24 karakter) |
| fee_bearer | — | Tidak berlaku untuk VA. Field ini diabaikan. Pembebanan biaya VA diatur internal sistem. |
Contoh request
{
"amount": 20000,
"method": "BNI_VA",
"description": "Order #INV-1001",
"external_id": "INV-1001",
"va_trx_type": "C"
}
Contoh response sukses
{
"success": true,
"message": "Payment created",
"data": {
"reference": "PAY20261105XXXXXXXX",
"external_id": "INV-1001",
"amount": 20000,
"charge_amount": 20000,
"fee": 5000,
"net_amount": 15000,
"status": "PENDING",
"method": "BNI_VA",
"gateway": "WistaPay",
"va_number": "88XXXXXXXXXXXX",
"va_channel": "BNI",
"va_trx_type": "C",
"invoice_url": "https://wistapay.shop/wistapay/api/va/{invoice_code}",
"invoice_code": "aB3x9kLm...",
"contract_id": "ci-xxxxx",
"payment_url": "https://wistapay.shop/wistapay/api/va/{invoice_code}",
"qris_image": null,
"expires_at": "2026-11-05T12:00:00+07:00",
"source": "API"
}
}
Gunakan invoice_url untuk mengarahkan customer ke halaman pembayaran WistaPay (countdown, salin VA, Check Status).
2. Kode metode Virtual Account
| method | Channel | Catatan tipe |
|---|---|---|
| PERMATA_VA | PERMATA | C / O / R* |
| BRI_VA | BRI | C / O / R* |
| MANDIRI_VA | MANDIRI | Hanya C (One Off) |
| MANDIRIPC_VA | MANDIRIPC | Hanya C (One Off) |
| CIMB_VA | CIMB | C / O / R* |
| BNI_VA | BNI | Hanya C (One Off) |
| SINARMAS_VA | SINARMAS | C / O / R* |
| MUAMALAT_VA | MUAMALAT | C / O / R* |
| NEOBANK_VA | BNC | C / O / R* |
* Tergantung metode diaktifkan di Setting merchant dan tidak sedang maintenance di panel admin.
3. Halaman invoice (domain WistaPay)
https://wistapay.shop/wistapay/api/va/{invoice_code}
- Menampilkan total, countdown jatuh tempo, nomor VA, tombol salin, metode bank, nomor pesanan, produk.
- Tombol Check Status + polling otomatis untuk memperbarui status real-time.
- Setelah lunas menampilkan konfirmasi pembayaran berhasil.
4. Cek status pembayaran
Gunakan endpoint status yang sama dengan QRIS, dengan reference dari create payment.
GET/POST https://wistapay.shop/wistapay/api/check-status.phpX-API-Key: sk_your_api_key
{ "reference": "PAY20261105XXXXXXXX" }
Status umum: PENDING · SUCCESS · EXPIRED. Untuk VA yang sudah lunas, saldo merchant dapat masih menunggu settlement (settlement_status: PENDING_SETTLEMENT hingga H+1 08:00 hari kerja).
5. Webhook merchant
Atur URL webhook di dashboard Setting. WistaPay mengirim notifikasi saat status berubah
(PENDING, SUCCESS, EXPIRED, dan SETTLED saat saldo VA di-settle).
Pastikan endpoint Anda menjawab HTTP 200 dan bersifat idempotent (boleh menerima event yang sama lebih dari sekali).
{
"event": "SUCCESS",
"reference": "PAY20261105XXXXXXXX",
"external_id": "INV-1001",
"amount": 20000,
"status": "SUCCESS",
"method": "BNI_VA",
"va_number": "88XXXXXXXXXXXX"
}
6. Settlement saldo VA
- Setelah customer bayar: transaksi
SUCCESS(lunas). - Saldo merchant dikreditkan pada H+1 pukul 08:00 WIB.
- Sabtu dan Minggu tidak di-settle — jadwal digeser ke Senin 08:00.
- QRIS tetap settle instan; aturan H+1 hanya untuk Virtual Account.
7. Biaya VA
- Biaya VA bersifat flat (diatur sistem; default Rp 5.000 per transaksi berhasil).
- Parameter
fee_bearertidak digunakan pada integrasi Virtual Account dan akan diabaikan jika dikirim. - Pembebanan biaya VA tidak dikonfigurasi lewat Setting merchant (berbeda dengan QRIS).
8. Kode error terkait VA
| code | Arti |
|---|---|
| METHOD_INVALID | Nilai method tidak dikenali |
| METHOD_DISABLED | Metode dimatikan di Setting merchant |
| VA_NOT_CONFIGURED | Gateway VA belum siap di server |
| VA_TYPE_BLOCKED | Tipe C/O/R tidak diizinkan (restriksi bank atau maintenance) |
| GATEWAY_ERROR | Gagal membuat VA di sisi gateway |
9. Contoh cURL
curl -X POST "https://wistapay.shop/wistapay/api/create-payment.php" \
-H "Content-Type: application/json" \
-H "X-API-Key: sk_your_api_key" \
-d '{
"amount": 20000,
"method": "BNI_VA",
"description": "Order #INV-1001",
"external_id": "INV-1001",
"va_trx_type": "C"
}'
10. Contoh PHP
$payload = [
'amount' => 20000,
'method' => 'BNI_VA',
'description' => 'Order #INV-1001',
'external_id' => 'INV-1001',
'va_trx_type' => 'C',
];
$ch = curl_init('https://wistapay.shop/wistapay/api/create-payment.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: sk_your_api_key',
],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);
// Arahkan customer ke: $res['data']['invoice_url']
// Tampilkan nomor VA: $res['data']['va_number']