Buat Pembayaran
Membuat tagihan baru dan mendapat instruksi bayar untuk pembeli.
POST
/v1/payments/createBerlaku 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.
| Parameter | Tipe | Wajib | Keterangan |
|---|---|---|---|
amount | integer | Ya | Nominal dibayar pembeli dalam rupiah (bilangan bulat). Harus di antara min_amount dan max_amount channel. Teks seperti "150000" ditolak. |
channel | string | Ya | Kode channel dari Daftar Channel, mis. qris atau va_bca. |
customer.name | string | Ya | Nama pembeli, maksimal 100 karakter. |
customer.email | string | Ya | Email pembeli yang valid, maksimal 150 karakter. |
customer.phone | string | Ya | Nomor telepon pembeli. Selain angka dan tanda + dibuang. Maksimal 20 karakter. |
merchant_ref | string | Tidak | Nomor order dari sistem Anda. Huruf, angka, . / - _, maksimal 64 karakter. Unik per merchant. Kosong = dibuat otomatis. |
description | string | Tidak | Keterangan tagihan, maksimal 255 karakter. |
redirect_url | string | Tidak | Alamat 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_minutes | integer | Tidak | Masa 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
| Parameter | Tipe | Keterangan |
|---|---|---|
reference | string | Nomor referensi ZevalPay. Simpan, dipakai untuk cek status dan muncul di webhook. |
merchant_ref | string | Nomor order Anda. |
status | string | pending, paid, failed, atau expired. |
channel | string | Kode channel. |
amount | integer | Nominal dibayar pembeli. |
fee | integer | Biaya yang dipotong dari Anda. Di sandbox selalu 0. |
net_amount | integer | amount dikurangi fee, yang masuk ke saldo Anda. |
customer | object | Data pembeli seperti yang dikirim. |
description | string|null | Keterangan tagihan. |
created_at | string | Waktu dibuat (ISO 8601). |
expires_at | string | Batas waktu bayar. Lewat dari ini status menjadi expired. |
paid_at | string|null | Waktu dibayar. Kosong bila belum dibayar. |
available_at | string|null | Tanggal dana bisa ditarik. Realtime = sama dengan paid_at, H+N = perkiraan, belum dibayar = kosong. |
refunded | boolean | true bila transaksi sudah di-refund oleh ZevalPay (saldo Anda dipotong sebesar net_amount). Status tetap paid, anggap transaksi ini batal. |
refunded_at | string|null | Waktu refund, kosong bila belum di-refund. |
livemode | boolean | true = live, false = sandbox. |
payment.code | string|null | Nomor Virtual Account atau kode bayar gerai. |
payment.qris_string | string|null | Isi QRIS. Ubah menjadi gambar QR di sisi Anda. |
payment.url | string|null | Tautan bayar (untuk channel e-wallet). |
payment.checkout_url | string | Halaman bayar siap pakai untuk pembeli. Arahkan pembeli ke sini bila Anda tidak ingin menampilkan instruksi sendiri. |
Instruksi bayar menurut channel
| Kelompok | Yang ditampilkan ke pembeli |
|---|---|
qris | Render payment.qris_string menjadi kode QR. |
va | Tampilkan bank dan nomor payment.code. Pembeli membayar lewat ATM atau mobile banking. |
ewallet | Arahkan pembeli ke payment.url bila ada. |
retail | Tampilkan payment.code untuk dibawa ke kasir. |
SandboxIsi
payment di sandbox adalah data contoh yang tidak bisa dibayar sungguhan. Gunakan Simulasi untuk menyelesaikan pembayaran.