Geliştiriciler için kripto ödeme API'si

Qvard API'si bilerek küçüktür. Üç rota tüm döngüyü kapsar: ödeme oluşturmak, bir ödeme yönteminin kullanılabilir olduğunu kontrol etmek ve çıkış göndermek. Bu başvuru her birini bugün çalıştığı şekliyle, karşılaşacağınız hatalarla anlatır ve API'nin sahip olmadıklarında dürüsttür; böylece var olmayan bir özelliğin üzerine kurmazsınız.

API neleri kapsar

Genel API https://api.qvard.com/api/v1 altındadır ve üç rotası vardır:

POST /payment: bir ödeme oluşturur ve barındırılan ödeme sayfasının adresini verir.
GET /method/:id/info: projenizdeki bir ödeme yönteminin ödeme kabul etmeye hazır olup olmadığını kontrol eder.
POST /payout: bir kripto adresine çıkış gönderir.

Sonuçlar webhook ile gelir: bir ödeme tamamlandığında Qvard, projenizde kayıtlı bir URL'yi çağırır. Bir ödemeyi kimliğiyle geri okuyan bir rota yoktur; bu yüzden sonucu webhook'tan öğrenirsiniz. Panel, bakiyeler ve ayarlar gibi geri kalan her şey web arayüzünde yapılır.

Kimlik doğrulama

Her istek, projenizin API anahtarını x-api-key başlığında taşır. Yenilenecek token ve OAuth yoktur. Eksik veya bilinmeyen bir anahtar, error.wrong.api.key mesajıyla 401 döndürür.

Anahtarı bir parola gibi ele alın: sunucuda, bir ortam değişkeninde veya sır yöneticisinde tutun; asla ön yüz kodunda veya herkese açık bir depoda değil. Qvard'ın webhook'un x-api-key başlığında size geri gönderdiği anahtar da aynısıdır; bu yüzden bir sızıntı her iki yönü de etkiler.

Ödeme oluşturma

POST /api/v1/payment bir JSON gövdesi alır:

id (string, zorunlu): sipariş veya fatura için kendi tanımlayıcınız. Webhook'ta geri gelir.
price (sayı, zorunlu): ABD doları cinsinden tutar. Müşteri seçtiği varlık ve ağdaki karşılığını öder.
paymentSystemId (sayı, isteğe bağlı): projenizden bir ödeme yöntemi. Geçerseniz ödeme sayfası o varlık ve ağ seçili olarak açılır.

Yanıt iki alanla 201 olur: Qvard tarafındaki ödeme tanımlayıcısı id ve barındırılan ödeme sayfasının adresi olan redirectUrl (https://my.qvard.com/pay/<id> biçiminde). Müşteriyi oraya yönlendirin veya bağlantıyı bir e-postaya koyun.

Çağrı id ve ödeme yöntemi başına idempotenttir: aynı yöntem için aynı id yeniden gönderildiğinde ikinci bir ödeme oluşturmak yerine mevcut ödeme döner; böylece zaman aşımından sonra yeniden denemek güvenlidir. Durum kodunun 200 değil 201 olduğuna dikkat edin.

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": "..." } }

Hatalar

Hataların tek bir biçimi vardır, message içeren bir JSON gövdesi:

400: gövde doğrulamadan geçemedi. Mesaj Error validation olur ve bir errors nesnesi her alanı ilk sorunuyla eşler; örneğin eksik bir id veya sayı olmayan bir price. Seçilen yöntemin asgari tutarının altındaki bir tutar da aynı şekilde reddedilir.
401: x-api-key başlığı eksik veya bilinmiyor (error.wrong.api.key).
404: yöntem bilgisi rotasında, var olmayan bir yöntem kimliği (error.notfound).

Bir 4xx aldığınızda yanıt gövdesinin tamamını günlüğe yazın; mesaj düzeltilecek alanı söyler. Bir 400 veya 401'i bir şey değiştirmeden yeniden denemeyin, ama zaman aşımını veya 5xx'i yeniden deneyin; yukarıdaki idempotentlik sayesinde bu güvenlidir.

Ödeme durumları ve webhook

Bir ödemenin dört durumundan biri vardır: wait (oluşturuldu, ödenmedi), partial (tam tutardan az geldi), completed (tam tutar geldi) ve rejected.

Webhook, ödeme tamamlandığında gönderilir: Qvard, projenizin callback URL'sine id ve status içeren küçük bir JSON ile POST yapar ve API anahtarınızı x-api-key başlığına koyar. Uç noktanız tam olarak HTTP 200 yanıtlamalıdır; başka herhangi bir durum, zaman aşımı veya yönlendirme başarısız teslimat sayılır ve yeniden denenir; yaklaşık altı dakikada toplam beş deneme. Başlık bir kimlik doğrulama başlığıdır, kriptografik imza değildir; bu yüzden anahtarınızla sabit zamanlı karşılaştırın. İşleyiciyi idempotent yapın, çünkü bir teslimat iki kez gelebilir.

Kodlu ayrıntılar kripto ödeme webhook'ları nasıl güvenli hale getirilir yazısında, tüm akış ise bir web sitesinde kripto ödemesi nasıl kabul edilir yazısında anlatılıyor.

Bir yöntemin hazır olduğunu kontrol etme

GET /api/v1/method/:id/info, projenizdeki bir ödeme yönteminin sayısal kimliğini alır ve üç alanla 200 yanıtlar:

server: yöntemin durumu hakkında ayrıntılar.
isReady: yöntem ödeme kabul etmeye hazır olduğunda true.
isActive: yöntem çevrimdışı olmadığında true, ağa yetişmeye devam etse bile.

Ödeme adımınızda belirli bir varlık ve ağ sunmadan önce kullanın; örneğin geçici olarak kullanılamayan bir yöntemi gizlemek için. Bilinmeyen bir kimlik 404 döndürür. İsteğe bağlıdır: müşterinin ödeme sayfasında seçmesine izin veriyorsanız ona ihtiyacınız yoktur.

Çıkışlar

POST /api/v1/payout, bakiyenizden bir kripto adresine fon gönderir. JSON gövdesi şunları içerir:

id (string, zorunlu): yeniden denemelerde kopyayı önlemek için kullanılan kendi çıkış tanımlayıcınız; yani aynı id'yi iki kez göndermek iki kez ödemez.
price (sayı, zorunlu): dolar değil, yöntemin kriptosu cinsinden tutar.
methodId (sayı, zorunlu): projenizdeki ödeme yöntemi.
address (string, zorunlu): hedef adres.
comment (string, isteğe bağlı).

Başarılı bir çağrı 201 döndürür. Çıkışlar gerçek para hareket ettirir; bu yüzden küçük bir tutarla test edin, adresi ve yöntemin ağını iki kez kontrol edin ve API üzerinden çıkışların projeniz için etkin olduğunu Qvard ile doğrulayın. Fiat banka hesabına çekim mevcut değildir; çıkış bir kripto adresine gider ve yalnızca ağ ücretine mal olur.

API'nin henüz sahip olmadıkları

Aramanızı önlemek için:

Bir ödemeyi kimliğiyle getiren uç nokta yok, bu yüzden webhook'a ve kendi kayıtlarınıza güvenin.
Webhook imzası yok; kimlik doğrulama x-api-key başlığıdır.
Sandbox yok: ayrı bir test ortamı yol haritasında, bu yüzden küçük gerçek tutarlar kullanın. Bir demo fatura ödeme yapmadan ödeme sayfasını gösterir.
Dönüş URL'leri yok: ödeme sonrası müşteri siteye kendi başına döner.
Mağaza platformları için hazır eklenti yok, ödeme bağlantıları da geliştirme aşamasında.

Biçimler ve örnekler için geliştirici belgelerine bakın. Ticari koşullar için fiyatlandırma sayfasına.

FAQ

Fiyatı hangi para biriminde belirlerim?

ABD doları cinsinden. Müşteri, ödeme sayfasında seçtiği varlık ve ağdaki karşılığını bir saat sabitlenen kurla öder. İstisna çıkıştır: tutarı yöntemin kriptosu cinsindendir.

Ödeme oluşturmayı yeniden denemek güvenli mi?

Evet. Aynı ödeme yöntemi için aynı id'yi göndermek mevcut ödemeyi döndürür; bu yüzden zaman aşımından sonra yeniden denemek kopya oluşturmaz.

Bir ödemenin sonucunu nasıl öğrenirim?

Ödeme tamamlandığında gönderilen webhook'tan. Bir ödemeyi kimliğiyle okuyan rota yoktur; bu yüzden gönderdiğiniz id'yi saklayın ve webhook geldiğinde eşleştirin.

Sandbox var mı?

Henüz yok. Ayrı bir test ortamı planlanıyor. Şimdilik küçük gerçek tutarlar kullanın ve ödeme sayfasını görmek için bir demo fatura açın.