Link pembayaran: panduan

Apa itu link

Link pembayaran adalah pembungkus untuk pembayaran. Setiap pelanggan yang membayar lewat link mendapat pembayaran sendiri, di halaman pembayaran hosted yang sama dengan pembayaran Qvard lainnya.

Satu pembayaran adalah invoice dengan kurs tetap. Link adalah titik masuk yang bisa dipakai berulang untuk membuat pembayaran tersebut. Satu link bisa membuat banyak pembayaran, tetapi tidak menggantikan pembayaran itu sendiri.

Link memiliki mata uangnya sendiri: yang dilihat dan dibayar pelanggan. Setiap pembayaran mengunci kursnya saat dibuat. Kurs terkini ada di halaman «Kurs mata uang».

Membuat link di dashboard

Di dashboard, buka bagian «Link pembayaran» dan atur linknya. Pilihannya adalah:

• Nominal: tetap, atau diisi pelanggan dengan minimum dan maksimum.
• Batas pembayaran: tanpa batas, satu pembayaran, atau N pembayaran.
• Masa berlaku: 1, 7, atau 30 hari, atau tanpa batas waktu.
• Email pembeli: jangan tanya, opsional, atau wajib.

Setiap link punya alamat sendiri: https://qvard.com/l/<slug>. Pelanggan membukanya, memilih token dan jaringan, lalu melihat halaman pembayaran biasa.

Link bisa diunduh sebagai kode QR dalam format PNG, untuk invoice cetak, struk, dan poster. Tombol «Bagikan» memberi link yang bisa dikirim lewat saluran apa pun.

Satu link per pelanggan lewat API

Untuk tahu pasti siapa yang membayar, buat pembayaran untuk setiap pelanggan lewat API dari server Anda, lalu kirim redirectUrl dari respons ke pelanggan. Kunci rahasia (qvard_sk_…) hanya boleh ada di server Anda.

Contoh permintaan

# Create a payment for one customer
curl -X POST https://api.qvard.com/api/v1/payment \
  -H 'x-api-key: qvard_sk_YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"price":12499.00,"currency":"INR","id":"order-123"}'

# The response contains "data": { "redirectUrl": "https://my.qvard.com/pay/..." }
# Send that redirectUrl to the customer.

// Run on your server only: the secret key must not reach the browser
async function createPaymentLink(orderId, amount) {
  const res = await fetch('https://api.qvard.com/api/v1/payment', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.QVARD_SECRET_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ price: amount, currency: 'INR', id: orderId })
  });
  if (!res.ok) throw new Error('Qvard API error: ' + res.status);
  const payment = await res.json();
  return payment.data.redirectUrl; // send this link to the customer
}

// Usage inside an async handler: const link = await createPaymentLink('order-123', 10);

Respons berisi id pembayaran dan redirectUrl, misalnya https://my.qvard.com/pay/<uuid>. Kirim redirectUrl ke pelanggan. Nilai id di permintaan adalah nomor pesanan Anda.

Jangan pernah memasukkan kunci rahasia (qvard_sk_…) ke kode yang berjalan di browser atau ke repositori publik. Buat pembayaran hanya dari server.

Penjualan terbatas dan link sekali pakai

Link sekali pakai menerima satu pembayaran, cocok untuk invoice. Link dengan batas N pembayaran menerima N pembayaran lalu berhenti, cocok untuk penawaran terbatas, misalnya 100 kursi.

Status link

• Aktif: link menerima pembayaran.
• Nonaktif: Anda mematikan link di dashboard. Link tidak menerima pembayaran sampai Anda menyalakannya lagi.
• Kedaluwarsa: masa berlaku (1, 7, atau 30 hari) sudah lewat.
• Habis: batas pembayaran sudah tercapai.

Webhook untuk pembayaran dari link

Pembayaran yang dibuat dari link memakai webhook yang sama dan header X-Qvard-Signature yang sama. Body-nya memiliki dua field tambahan yang opsional: paymentLink, yaitu slug link, dan customerEmail, yaitu email yang diisi pelanggan jika link memintanya. Pembayaran lain tidak memiliki field ini.

Cara memverifikasi tanda tangan webhook

Yang tidak diberitahu link

Link yang bisa dipakai berulang tidak menunjukkan siapa yang membayar. Webhook memberi tahu tentang pembayaran, bukan pembeli.

Field customerEmail bersifat opsional dan tidak diverifikasi: pelanggan mengetiknya sendiri dan tidak ada yang memeriksanya. Jika perlu tahu pembelinya, buat pembayaran lewat API untuk setiap pembeli.

Referensi API