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 merchant
  • charge_amount — nominal yang harus dibayar di QRIS (sudah termasuk fee jika CLIENT)
  • net_amount — yang akan masuk saldo merchant saat sukses
  • qris_image / payment_url — tampilkan ke pembayar
  • reference — 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

PENDING SUCCESS EXPIRED FAILED

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.php atau menunggu user kembali via callback_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
400Bad requestamount < 1000, amount > maks, reference kosong
401UnauthorizedAPI Key kosong / tidak valid
403ForbiddenAkun diblokir
404Not foundreference tidak ditemukan
405Method not allowedBukan POST pada create-payment
502Bad gatewayGagal 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)

  1. Merchant memanggil POST /api/create-payment.php dengan method bank VA (contoh BNI_VA).
  2. WistaPay membuat VA dan mengembalikan va_number, invoice_url, reference, nominal tagihan.
  3. Tampilkan invoice_url ke customer (atau bangun UI sendiri memakai va_number).
  4. Customer transfer tepat sesuai nominal sebelum jatuh tempo.
  5. Status lunas diterima lewat webhook merchant, atau di-poll lewat check status / halaman invoice (tombol Check Status).
  6. Setelah lunas: status transaksi SUCCESS. Saldo merchant masuk setelah settlement H+1 08:00 (hari kerja).
  7. 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
amountYaNominal produk (integer, min 1000)
methodYaKode metode VA, lihat daftar di bawah
descriptionTidakNama produk / keterangan (tampil di invoice)
external_idTidakID pesanan di sistem Anda (nomor pesanan)
callback_urlTidakOverride webhook per transaksi (opsional)
va_trx_typeTidakC One Off · O Open Recurring · R Close Recurring. Default: konfigurasi Setting merchant. BNI / Mandiri / Mandiri PC hanya C.
va_nameTidakNama 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_VAPERMATAC / O / R*
BRI_VABRIC / O / R*
MANDIRI_VAMANDIRIHanya C (One Off)
MANDIRIPC_VAMANDIRIPCHanya C (One Off)
CIMB_VACIMBC / O / R*
BNI_VABNIHanya C (One Off)
SINARMAS_VASINARMASC / O / R*
MUAMALAT_VAMUAMALATC / O / R*
NEOBANK_VABNCC / 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_bearer tidak 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_INVALIDNilai method tidak dikenali
METHOD_DISABLEDMetode dimatikan di Setting merchant
VA_NOT_CONFIGUREDGateway VA belum siap di server
VA_TYPE_BLOCKEDTipe C/O/R tidak diizinkan (restriksi bank atau maintenance)
GATEWAY_ERRORGagal 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']
© 2026 WistaPay · HAK CIPTA DILINDUNGI