Dokumentasi › API V1

Buat Pembayaran

Membuat tagihan baru dan mendapat instruksi bayar untuk pembeli.

POST/v1/payments/create
Berlaku diSandbox (zp_test_)Live (zp_live_)

Membuat tagihan baru. Status awal selalu pending. Tampilkan instruksi bayar dari blok payment kepada pembeli, lalu tunggu webhook atau cek status.

Yang perlu dikirim

Body JSON.

ParameterTipeWajibKeterangan
amountintegerYaNominal dibayar pembeli dalam rupiah (bilangan bulat). Harus di antara min_amount dan max_amount channel. Teks seperti "150000" ditolak.
channelstringYaKode channel dari Daftar Channel, mis. qris atau va_bca.
customer.namestringYaNama pembeli, maksimal 100 karakter.
customer.emailstringYaEmail pembeli yang valid, maksimal 150 karakter.
customer.phonestringYaNomor telepon pembeli. Selain angka dan tanda + dibuang. Maksimal 20 karakter.
merchant_refstringTidakNomor order dari sistem Anda. Huruf, angka, . / - _, maksimal 64 karakter. Unik per merchant. Kosong = dibuat otomatis.
descriptionstringTidakKeterangan tagihan, maksimal 255 karakter.
redirect_urlstringTidakAlamat situs Anda tempat pembeli dikembalikan dari halaman bayar (checkout_url). Harus https, maksimal 500 karakter. Kami menambahkan ?reference=TRX…. Bukan bukti pembayaran: pembeli bisa membukanya tanpa membayar, jadi periksa status lewat webhook atau POST /v1/payments/status.
expiry_minutesintegerTidakMasa berlaku dalam menit, minimal 5. Hanya boleh lebih pendek dari bawaan channel, tidak bisa lebih panjang. Kosong = bawaan channel.
Mencegah tagihan gandaSelalu kirim merchant_ref milik Anda sendiri. Bila permintaan terputus dan Anda mengulang dengan nomor yang sama, server menjawab 409 conflict tanpa membuat tagihan kedua. Cek hasilnya lewat POST /v1/payments/status dengan {"merchant_ref": "INV-1001"}.

Contoh kode

Contoh memakai alamat sandbox. Untuk live, ganti host ke api.zevalpay.com dan kunci ke zp_live_….

cURL
curl -X POST https://api-sandbox.zevalpay.com/v1/payments/create \
  -H "Authorization: Bearer zp_test_KUNCI_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "channel": "va_bca",
    "merchant_ref": "INV-1001",
    "description": "Pesanan #1001",
    "expiry_minutes": 60,
    "customer": {
      "name": "Budi",
      "email": "[email protected]",
      "phone": "081234567890"
    }
  }'
PHP
<?php
function zevalpay(string $method, string $path, ?array $body = null): array
{
    $ch = curl_init('https://api-sandbox.zevalpay.com' . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_POSTFIELDS     => $body === null ? null : json_encode($body),
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('ZEVALPAY_KEY'), 'Content-Type: application/json'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
    ]);

    return json_decode((string) curl_exec($ch), true) ?? ['error' => ['code' => 'no_response']];
}

$result = zevalpay('POST', '/v1/payments/create', [
    'amount'         => 150000,
    'channel'        => 'va_bca',
    'merchant_ref'   => 'INV-1001',
    'description'    => 'Pesanan #1001',
    'expiry_minutes' => 60,
    'customer'       => ['name' => 'Budi', 'email' => '[email protected]', 'phone' => '081234567890'],
]);

if (isset($result['error'])) {
    echo $result['error']['message'];
} else {
    echo 'Bayar ke VA: ' . $result['data']['payment']['code'];
}
Node.js
async function zevalpay(method, path, body) {
  const res = await fetch('https://api-sandbox.zevalpay.com' + path, {
    method,
    headers: {
      Authorization: 'Bearer ' + process.env.ZEVALPAY_KEY,
      'Content-Type': 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  return res.json();
}

const result = await zevalpay('POST', '/v1/payments/create', {
  amount: 150000,
  channel: 'va_bca',
  merchant_ref: 'INV-1001',
  description: 'Pesanan #1001',
  expiry_minutes: 60,
  customer: { name: 'Budi', email: '[email protected]', phone: '081234567890' },
});

if (result.error) console.log(result.error.message);
else console.log('Bayar ke VA:', result.data.payment.code);
Python
import os, requests

def zevalpay(method, path, body=None):
    res = requests.request(
        method, "https://api-sandbox.zevalpay.com" + path, json=body, timeout=30,
        headers={"Authorization": "Bearer " + os.environ["ZEVALPAY_KEY"]},
    )
    return res.json()

result = zevalpay("POST", "/v1/payments/create", {
    "amount": 150000,
    "channel": "va_bca",
    "merchant_ref": "INV-1001",
    "description": "Pesanan #1001",
    "expiry_minutes": 60,
    "customer": {"name": "Budi", "email": "[email protected]", "phone": "081234567890"},
})

if "error" in result:
    print(result["error"]["message"])
else:
    print("Bayar ke VA:", result["data"]["payment"]["code"])

Contoh respons

Berhasil: Virtual Account
HTTP 201
{
  "data": {
    "reference": "TRX261027A1B2C3",
    "merchant_ref": "INV-1001",
    "status": "pending",
    "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": null,
    "available_at": null,
    "refunded": false,
    "refunded_at": null,
    "livemode": false,
    "payment": {
      "code": "8277012345678901",
      "qris_string": null,
      "url": null
    }
  }
}
Berhasil: QRIS
HTTP 201 (dipersingkat)
{
  "data": {
    "reference": "TRX261027D4E5F6",
    "status": "pending",
    "channel": "qris",
    "amount": 25000,
    "payment": {
      "code": null,
      "qris_string": "00020101021226...",
      "url": null
    }
  }
}
Gagal: nominal di luar batas
HTTP 422
{
  "error": {
    "code": "invalid_request",
    "message": "Nominal untuk channel ini harus antara Rp 10.000 dan Rp 10.000.000."
  }
}
Gagal: nomor order sudah dipakai
HTTP 409
{
  "error": {
    "code": "conflict",
    "message": "Nomor order \"INV-1001\" sudah dipakai transaksi lain."
  }
}

Isi data

ParameterTipeKeterangan
referencestringNomor referensi ZevalPay. Simpan, dipakai untuk cek status dan muncul di webhook.
merchant_refstringNomor order Anda.
statusstringpending, paid, failed, atau expired.
channelstringKode channel.
amountintegerNominal dibayar pembeli.
feeintegerBiaya yang dipotong dari Anda. Di sandbox selalu 0.
net_amountintegeramount dikurangi fee, yang masuk ke saldo Anda.
customerobjectData pembeli seperti yang dikirim.
descriptionstring|nullKeterangan tagihan.
created_atstringWaktu dibuat (ISO 8601).
expires_atstringBatas waktu bayar. Lewat dari ini status menjadi expired.
paid_atstring|nullWaktu dibayar. Kosong bila belum dibayar.
available_atstring|nullTanggal dana bisa ditarik. Realtime = sama dengan paid_at, H+N = perkiraan, belum dibayar = kosong.
refundedbooleantrue bila transaksi sudah di-refund oleh ZevalPay (saldo Anda dipotong sebesar net_amount). Status tetap paid, anggap transaksi ini batal.
refunded_atstring|nullWaktu refund, kosong bila belum di-refund.
livemodebooleantrue = live, false = sandbox.
payment.codestring|nullNomor Virtual Account atau kode bayar gerai.
payment.qris_stringstring|nullIsi QRIS. Ubah menjadi gambar QR di sisi Anda.
payment.urlstring|nullTautan bayar (untuk channel e-wallet).
payment.checkout_urlstringHalaman bayar siap pakai untuk pembeli. Arahkan pembeli ke sini bila Anda tidak ingin menampilkan instruksi sendiri.

Instruksi bayar menurut channel

KelompokYang ditampilkan ke pembeli
qrisRender payment.qris_string menjadi kode QR.
vaTampilkan bank dan nomor payment.code. Pembeli membayar lewat ATM atau mobile banking.
ewalletArahkan pembeli ke payment.url bila ada.
retailTampilkan payment.code untuk dibawa ke kasir.
SandboxIsi payment di sandbox adalah data contoh yang tidak bisa dibayar sungguhan. Gunakan Simulasi untuk menyelesaikan pembayaran.