Dokumentasi › API V1

Webhook

Pemberitahuan otomatis ke server Anda saat status pembayaran berubah.

Berlaku diSandbox (zp_test_)Live (zp_live_)

Saat status pembayaran berubah, ZevalPay mengirim permintaan POST berisi JSON ke alamat yang Anda daftarkan. Ini cara termudah dan tercepat mengetahui pembayaran selesai, tanpa polling.

Mengatur webhook

  1. 1
    Buka menu WebhookDi dashboard, pilih mode (Sandbox atau Live) lalu buka menu Webhook. Setiap mode punya alamat dan secret sendiri.
  2. 2
    Isi alamat penerimaAlamat harus https, tanpa nama pengguna atau sandi di dalamnya, dan menuju server publik. Pengalihan (redirect) tidak diikuti.
  3. 3
    Simpan secretSalin secret dari halaman yang sama. Dipakai untuk memeriksa signature, jangan dibagikan.
  4. 4
    Kirim ujiTombol Kirim uji mengirim peristiwa webhook.test ke alamat tersimpan agar Anda bisa memastikan penerima dan signature sudah benar.

Peristiwa

PeristiwaKapan dikirim
payment.paidPembayaran berhasil dibayar.
payment.failedPembayaran gagal.
payment.expiredPembayaran melewati batas waktu.
payment.refundedTransaksi di-refund oleh ZevalPay (saldo Anda dipotong). Isi data sama, dengan refunded bernilai true.
webhook.testTombol Kirim uji ditekan. Isi data hanya message.

Di sandbox, peristiwa dikirim saat Anda memanggil Simulasi. Di live, saat provider pembayaran mengabarkan hasilnya ke ZevalPay.

Header

HeaderIsi
X-ZevalPay-SignatureSignature HMAC-SHA256 isi mentah, dalam heksadesimal. Lihat bagian verifikasi.
X-ZevalPay-EventNama peristiwa, mis. payment.paid.
X-ZevalPay-DeliveryID pengiriman. Berubah untuk tiap pengiriman, tetap sama pada percobaan ulang atas pengiriman yang sama.
X-ZevalPay-Modetest atau live.

Isi webhook

POST ke alamat Anda
{
  "event": "payment.paid",
  "livemode": true,
  "data": {
    "reference": "TRX261027A1B2C3",
    "merchant_ref": "INV-1001",
    "status": "paid",
    "channel": "va_bca",
    "amount": 150000,
    "fee": 1050,
    "net_amount": 148950,
    "customer": {
      "name": "Budi",
      "email": "[email protected]",
      "phone": "081234567890"
    },
    "description": "Pesanan #1001",
    "created_at": "2026-10-27T10:15:00+07:00",
    "expires_at": "2026-10-28T10:15:00+07:00",
    "paid_at": "2026-10-27T10:20:41+07:00",
    "available_at": "2026-10-28T15:00:00+07:00",
    "refunded": false,
    "refunded_at": null
  }
}

data berbentuk sama dengan objek pembayaran di Buat Pembayaran, tanpa blok payment. livemode = false untuk sandbox.

Verifikasi signature

Wajib. Tanpa ini siapa pun yang tahu alamat Anda bisa berpura-pura menjadi ZevalPay.

Signature = hex( HMAC-SHA256( isi_mentah, secret ) ). Hitung dari byte persis yang diterima, lalu bandingkan dengan header X-ZevalPay-Signature memakai perbandingan waktu-konstan.

PHP
<?php
$secret    = getenv('ZEVALPAY_WEBHOOK_SECRET');
$body      = file_get_contents('php://input');   // isi MENTAH, jangan di-decode lalu di-encode ulang
$signature = $_SERVER['HTTP_X_ZEVALPAY_SIGNATURE'] ?? '';

if (! hash_equals(hash_hmac('sha256', $body, $secret), $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
if ($event['event'] === 'payment.paid') {
    // Cari pesanan lewat $event['data']['merchant_ref'], tandai lunas bila belum.
}

http_response_code(200);
Node.js
const crypto = require('crypto');
const express = require('express');
const app = express();

// express.raw agar isi mentah tersedia untuk menghitung tanda tangan
app.post('/webhooks/zevalpay', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.ZEVALPAY_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
  const received = req.get('X-ZevalPay-Signature') || '';

  const ok = expected.length === received.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString('utf8'));
  if (event.event === 'payment.paid') {
    // Cari pesanan lewat event.data.merchant_ref, tandai lunas bila belum.
  }
  res.sendStatus(200);
});
Python
import hashlib, hmac, os, json
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/zevalpay")
def zevalpay_webhook():
    body = request.get_data()  # isi mentah
    expected = hmac.new(os.environ["ZEVALPAY_WEBHOOK_SECRET"].encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-ZevalPay-Signature", "")):
        abort(401)

    event = json.loads(body)
    if event["event"] == "payment.paid":
        pass  # cari pesanan lewat event["data"]["merchant_ref"], tandai lunas bila belum
    return "", 200
Kesalahan yang sering terjadi
  • Menghitung dari JSON yang sudah di-decode lalu di-encode ulang. Urutan kunci atau spasi berubah dan signature tidak cocok.
  • Memakai secret mode yang salah. Secret Sandbox dan Live berbeda.
  • Membandingkan dengan == biasa. Pakai fungsi perbandingan waktu-konstan.

IP server ZevalPay

Hanya bila server Anda memakai firewall yang membatasi IP masuk.

Webhook dikirim dari alamat berikut. Izinkan alamat ini menuju endpoint webhook Anda.

IP server ZevalPay
103.152.242.240
Daftar IP bisa berubahJangan menjadikan IP sebagai satu-satunya pengaman. Signature tetap wajib diperiksa.

Balasan dan percobaan ulang

  • Balas HTTP 2xx secepatnya (batas waktu 8 detik). Lakukan pekerjaan berat setelah membalas.
  • Selain 2xx, timeout, atau gagal tersambung dianggap gagal. ZevalPay mencoba lagi setelah 1 menit, 5 menit, 30 menit, 2 jam, dan 6 jam. Sesudah itu pengiriman ditandai gagal.
  • Pengiriman yang gagal bisa dikirim ulang manual lewat tombol Kirim ulang di dashboard.
  • Balas 2xx untuk semua peristiwa, termasuk payment.failed, payment.expired, dan payment.refunded yang tidak Anda proses. Balasan 4xx atau 5xx dianggap gagal walau Anda memang tidak memakai peristiwa itu. Abaikan saja isinya, lalu balas 200.

Membuat penerima yang andal

  • Idempoten. Webhook bisa tiba lebih dari sekali, atau tidak berurutan. Proses berdasarkan data.reference dan abaikan bila pesanan sudah berstatus akhir.
  • Jangan hanya percaya isi webhook untuk uang besar. Setelah signature valid, Anda boleh memastikan lagi dengan POST /v1/payments/status.
  • Jaga status dari sisi ZevalPay sebagai kebenaran. Bila ada selisih dengan data Anda, ikuti ZevalPay.
  • Simpan X-ZevalPay-Delivery di log Anda untuk memudahkan pelacakan bila perlu bertanya ke tim ZevalPay.