API pembayaran kripto untuk developer

API Qvard sengaja dibuat kecil. Tiga rute mencakup seluruh siklus: membuat pembayaran, memeriksa bahwa metode pembayaran tersedia, dan mengirim payout. Referensi ini menjelaskan masing-masing seperti cara kerjanya hari ini, dengan error yang akan Anda temui, dan jujur tentang apa yang tidak dimiliki API, agar Anda tidak membangun di atas fitur yang tidak ada.

Apa yang dicakup API

API publik berada di https://api.qvard.com/api/v1 dan memiliki tiga rute:

POST /payment: membuat pembayaran dan mendapatkan alamat halaman pembayaran yang dihosting.
GET /method/:id/info: memeriksa apakah metode pembayaran dari proyek Anda siap menerima pembayaran.
POST /payout: mengirim payout ke alamat kripto.

Hasil tiba lewat webhook: Qvard memanggil URL yang Anda simpan di proyek saat pembayaran selesai. Tidak ada rute untuk membaca pembayaran berdasarkan id-nya, jadi webhook adalah cara Anda mengetahui hasilnya. Hal lain, seperti panel, saldo, dan pengaturan, dilakukan di antarmuka web.

Autentikasi

Setiap permintaan membawa kunci API proyek Anda di header x-api-key. Tidak ada token yang perlu diperbarui dan tidak ada OAuth. Kunci yang hilang atau tidak dikenal mengembalikan 401 dengan pesan error.wrong.api.key.

Perlakukan kunci seperti kata sandi: simpan di server, di variabel lingkungan atau pengelola rahasia, dan jangan pernah di kode front-end atau repositori publik. Kunci yang sama itulah yang dikirim Qvard kembali kepada Anda di header x-api-key webhook, jadi kebocoran memengaruhi kedua arah.

Membuat pembayaran

POST /api/v1/payment menerima isi JSON:

id (string, wajib): pengenal Anda sendiri untuk pesanan atau faktur. Ia kembali di webhook.
price (angka, wajib): jumlah dalam dolar AS. Pelanggan membayar setaranya dalam aset dan jaringan yang dipilih.
paymentSystemId (angka, opsional): metode pembayaran dari proyek Anda. Jika diberikan, halaman pembayaran terbuka dengan aset dan jaringan itu terpilih.

Responsnya 201 dengan dua field: id, pengenal pembayaran di sisi Qvard, dan redirectUrl, alamat halaman pembayaran yang dihosting, berbentuk https://my.qvard.com/pay/<id>. Arahkan pelanggan ke sana, atau taruh tautan di email.

Panggilan ini idempoten per id dan metode pembayaran: mengirim id yang sama lagi untuk metode yang sama mengembalikan pembayaran yang ada alih-alih membuat yang kedua, sehingga aman diulang setelah timeout. Perhatikan bahwa kode statusnya 201, bukan 200.

curlcreate-payment.sh

curl -X POST https://api.qvard.com/api/v1/payment \
  -H "x-api-key: $QVARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "order-1042", "price": 49.9 }'

# 201 Created
# { "id": "6f1c2d3e-...", "redirectUrl": "https://my.qvard.com/pay/6f1c2d3e-..." }

# 401 { "message": "error.wrong.api.key" }
# 400 { "message": "Error validation", "errors": { "price": "..." } }

Error

Error memiliki satu bentuk, isi JSON dengan message:

400: isi gagal validasi. Pesannya Error validation dan objek errors memetakan setiap field ke masalah pertamanya, misalnya id yang hilang atau price yang bukan angka. Jumlah di bawah minimum metode yang dipilih ditolak dengan cara yang sama.
401: header x-api-key hilang atau tidak dikenal (error.wrong.api.key).
404: pada rute informasi metode, id metode yang tidak ada (error.notfound).

Catat seluruh isi respons saat menerima 4xx; pesan menyebut field yang perlu diperbaiki. Jangan ulangi 400 atau 401 tanpa mengubah sesuatu, tetapi ulangi timeout atau 5xx, yang aman berkat idempotensi di atas.

Status pembayaran dan webhook

Pembayaran memiliki salah satu dari empat status: wait (dibuat, belum dibayar), partial (yang tiba kurang dari jumlah penuh), completed (jumlah penuh tiba), dan rejected.

Webhook dikirim saat pembayaran selesai: Qvard melakukan POST ke callback URL proyek Anda dengan JSON kecil berisi id Anda dan status, serta menaruh kunci API Anda di header x-api-key. Endpoint Anda harus menjawab tepat HTTP 200; status lain, timeout, atau pengalihan dianggap pengiriman gagal dan diulang, lima percobaan dalam sekitar enam menit. Header ini adalah header autentikasi, bukan tanda tangan kriptografis, jadi bandingkan dengan kunci Anda dalam waktu konstan. Buat handler idempoten, karena pengiriman bisa tiba dua kali.

Detail beserta kode ada di cara mengamankan webhook pembayaran kripto, dan seluruh alurnya dibahas di cara menerima pembayaran kripto di situs web.

Memeriksa bahwa metode siap

GET /api/v1/method/:id/info menerima id numerik metode pembayaran dari proyek Anda dan menjawab 200 dengan tiga field:

server: detail tentang status metode.
isReady: true saat metode siap menerima pembayaran.
isActive: true saat metode tidak offline, meskipun masih menyusul jaringan.

Gunakan sebelum menawarkan aset dan jaringan tertentu di checkout Anda, misalnya untuk menyembunyikan metode yang sementara tidak tersedia. Id yang tidak dikenal mengembalikan 404. Ini opsional: jika Anda membiarkan pelanggan memilih di halaman pembayaran, Anda tidak membutuhkannya.

Payout

POST /api/v1/payout mengirim dana dari saldo Anda ke alamat kripto. Isi JSON-nya:

id (string, wajib): pengenal payout Anda sendiri, dipakai untuk mencegah duplikat saat diulang, jadi mengirim id yang sama dua kali tidak membayar dua kali.
price (angka, wajib): jumlah dalam kripto metode tersebut, bukan dolar.
methodId (angka, wajib): metode pembayaran dari proyek Anda.
address (string, wajib): alamat tujuan.
comment (string, opsional).

Panggilan yang berhasil mengembalikan 201. Payout memindahkan uang sungguhan, jadi uji dengan jumlah kecil, periksa ulang alamat dan jaringan metode, dan pastikan kepada Qvard bahwa payout lewat API diaktifkan untuk proyek Anda. Penarikan ke rekening bank dalam fiat tidak tersedia; payout menuju alamat kripto dan hanya dikenai biaya jaringan.

Apa yang belum ada di API

Agar Anda tidak mencari-cari:

Tidak ada endpoint untuk mengambil pembayaran berdasarkan id, jadi andalkan webhook dan catatan Anda sendiri.
Tidak ada tanda tangan webhook; autentikasinya adalah header x-api-key.
Tidak ada sandbox: lingkungan uji terpisah ada di roadmap, jadi gunakan jumlah kecil yang nyata. Faktur demo menampilkan halaman pembayaran tanpa membayar.
Tidak ada URL kembali setelah pembayaran: pelanggan kembali ke situs Anda sendiri.
Tidak ada plugin siap pakai untuk platform toko, dan tautan pembayaran masih dalam pengembangan.

Untuk format dan contoh, lihat dokumentasi pengembang. Untuk ketentuan komersial, halaman harga.

FAQ

Dalam mata uang apa saya menetapkan harga?

Dalam dolar AS. Pelanggan membayar setaranya dalam aset dan jaringan yang dipilih di halaman pembayaran, dengan kurs yang dikunci selama satu jam. Payout adalah pengecualian: jumlahnya dalam kripto metode tersebut.

Apakah aman mengulang pembuatan pembayaran?

Ya. Mengirim id yang sama untuk metode pembayaran yang sama mengembalikan pembayaran yang ada, jadi pengulangan setelah timeout tidak membuat duplikat.

Bagaimana saya tahu hasil pembayaran?

Dari webhook, yang dikirim saat pembayaran selesai. Tidak ada rute untuk membaca pembayaran berdasarkan id-nya, jadi simpan id yang Anda kirim dan cocokkan saat webhook tiba.

Apakah ada sandbox?

Belum. Lingkungan uji terpisah direncanakan. Untuk sekarang gunakan jumlah kecil yang nyata dan faktur demo untuk melihat halaman pembayaran.