API entegrasyonu

Merchant API üzerinden harici kripto cüzdanlardan kripto para ödemeleri kabul edin.

API entegrasyonunda uygulamanız kripto faturaları oluşturur, müşterilere ödeme talimatlarını gösterir ve ödeme durumunu API üzerinden izler.

API'yi iki şekilde kullanabilirsiniz:

• Yalnızca API — uygulamanız tüm ödeme deneyimini oluşturur ve müşteriye kripto adresini, tutarı, ağı ve son geçerlilik süresini gösterir.
• API + Hosted Checkout — arka ucunuz sipariş takibi ve mutabakat için API'yi kullanır, müşteriye yönelik ödeme sayfasını ise Hosted Checkout sağlar.

API entegrasyonu ne zaman kullanılır

Ödeme akışını kendi web sitenizde, uygulamanızda, botunuzda veya yapay zekâ ajanınızda kontrol etmek istediğinizde API entegrasyonunu kullanın.

API entegrasyonu şu durumlarda faydalıdır:

• Kendi ödeme arayüzünüzü oluşturmak istiyorsanız.
• Kripto faturalarını programatik olarak oluşturmanız gerekiyorsa.
• Ödeme talimatlarını kendi ürününüzde göstermek istiyorsanız.
• Ödeme durumunu arka ucunuzdan izlemeniz gerekiyorsa.
• Hosted Checkout'u arka uçtaki sipariş mutabakatıyla birleştirmek istiyorsanız.

Hazır bir ödeme sayfasıyla en hızlı entegrasyonu istiyorsanız bunun yerine Hosted Checkout entegrasyonunu kullanın.

Entegrasyon modelleri

Model	Müşteri deneyimi	Arka ucun sorumluluğu	Durumun işlenmesi
Yalnızca API	Uygulamanız oluşturur	Fatura oluşturma, ödeme bilgilerini gösterme, durumu izleme	Ödeme durumunu API üzerinden düzenli sorgulama
API + Hosted Checkout	Volet.com barındırır	Sipariş oluşturma veya izleme, ödeme durumunun mutabakatı	Hosted Checkout Status URL'sini ve API ile sipariş sorgulamayı kullanma

Başlamadan önce

API üzerinden kripto ödeme kabul etmek için şunlara ihtiyacınız vardır:

• Doğrulanmış bir Volet.com hesabı.
• Ödeme araçları bölümünde yapılandırılmış bir API.
• Kripto ödeme kabulü için API izinleri.
• API'yi Hosted Checkout ile birlikte kullanıyorsanız bir Hosted Checkout yapılandırması.

API'nizi oluşturmak ve yapılandırmak için Ödeme ağ geçidi oluşturma sayfasına bakın.

Kimlik doğrulama

Merchant API istekleri kimlik doğrulama başlıkları gerektirir.

Her API isteğine şu başlıkları ekleyin:

Başlık	Açıklama
Api-Name	Volet.com hesabınızda yapılandırılan API adı.
Account-Email	API'nin ait olduğu Volet.com hesabının e-posta adresi.
Authentication-Token	password:YYYYMMDD:HH (UTC) değerinden oluşturulan SHA-256 token'ı; buradaki parola, Volet.com hesabınızda Ödeme araçları bölümünde belirlenir. Örneğin, SHA256("MySecret123:20261026:14"). Yalnızca oluşturulan token gönderilir, parola asla gönderilmez.

API gizli anahtarınızı gizli tutun. API kimlik bilgilerini veya kimlik doğrulama token'larını ön uç kodunda, mobil uygulamalarda, botlarda veya istemci tarafı betiklerde asla açığa çıkarmayın.

Yalnızca API akışı

Tüm kripto ödeme deneyimini uygulamanız yönetiyorsa bu akışı kullanın.

Ödeme akışı:

1. Sisteminizde bir sipariş oluşturun.
2. İsteğe bağlı olarak faturayı oluşturmadan önce fatura bilgilerini kontrol edin.
3. API üzerinden bir kripto faturası oluşturun.
4. Müşteriye ödeme adresini, tutarı, para birimini, ağı ve son geçerlilik süresini gösterin.
5. Müşteri ödemeyi bir kripto cüzdandan gönderir.
6. Arka ucunuz ödeme durumunu API üzerinden kontrol eder.
7. Ödeme tamamlandığında sisteminizdeki sipariş durumunu güncelleyin.

Adım 1: Fatura bilgilerini kontrol edin

Fatura oluşturmadan önce hesaplanan fatura değerlerini kontrol edebilirsiniz.

Bu adımla asıl faturayı oluşturmadan önce gönderen tutarını, alıcı tutarını, döviz dönüştürmeyi ve son geçerlilik süresini önizleyebilirsiniz.

Uç nokta:

POST /api/invoice/crypto-invoice/check

Örnek istek:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com"
}

Örnek yanıt:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com",
  "senderAmount": 100,
  "receiverAmount": 100,
  "expirationDate": "2026-01-15T10:30:00",
  "expirationDateMillis": 1768473000000
}

Bu adım ödeme adresi oluşturmaz ve ödemeyi başlatmaz.

Adım 2: Kripto faturası oluşturun

Müşteri ödemeye hazır olduğunda bir kripto faturası oluşturun.

Uç nokta:

POST /api/invoice/crypto-invoice/deposit

Örnek istek:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com"
}

Yanıt, uygulamanızın müşteriye göstermesi gereken ödeme bilgilerini döndürür.

Örnek yanıt:

{
  "receiverCurrency": "USD",
  "senderCurrency": "USDT_TRC20",
  "amount": 100,
  "transferAction": "GET",
  "note": "Order #1001",
  "sciName": "Store",
  "orderId": "ORDER-1001",
  "subMerchantURL": "https://merchant.example.com",
  "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "addressOldFormat": null,
  "destinationTag": null,
  "senderAmount": 100,
  "receiverAmount": 100,
  "expirationDate": "2026-01-15T10:30:00",
  "expirationDateMillis": 1768473000000
}

Fatura isteği alanları

Alan	Zorunlu	Açıklama
receiverCurrency	Evet	Ödeme tamamlandıktan sonra Volet.com hesabınıza yatırılan para birimi.
senderCurrency	Evet	Müşterinin ödeme için kullanması gereken para birimi ve ağ.
amount	Evet	Ödeme tutarı. Nasıl yorumlanacağı transferAction değerine bağlıdır.
transferAction	Evet	Tutarın gönderilecek tutar mı yoksa alınacak tutar mı olduğunu belirler. Olası değerler: GIVE, GET.
note	Hayır	Ödeme notu veya sipariş açıklaması.
sciName	Hayır	Ödeme akışıyla ilişkili Hosted Checkout veya mağaza adı.
orderId	Hayır	Dahili sipariş kimliğiniz. Her ödeme için benzersiz bir değer kullanın.
subMerchantURL	Hayır	Ödeme başka bir üye işyeri adına işleniyorsa alt üye işyerinin web sitesi URL'si.

Fatura yanıtı alanları

Alan	Açıklama
address	Müşterinin ödemeyi göndermesi gereken kripto adresi.
addressOldFormat	Seçilen ağda varsa alternatif adres biçimi.
destinationTag	Bazı ağların gerektirdiği hedef etiketi, memo veya ek tanımlayıcı.
senderAmount	Müşterinin göndermesi gereken tutar.
senderCurrency	Müşterinin kullanması gereken para birimi ve ağ.
receiverAmount	Hesabınıza yatırılması beklenen tutar.
receiverCurrency	Hesabınıza yatırılan para birimi.
expirationDate	Faturanın son geçerlilik tarihi ve saati.
expirationDateMillis	Faturanın milisaniye cinsinden son geçerlilik zaman damgası.

senderAmount, senderCurrency, address ve döndürülmüşse destinationTag değerlerini her zaman aynen gösterin.

Adım 3: Ödeme talimatlarını gösterin

Yalnızca API modunda ödeme talimatlarını müşteriye göstermekten uygulamanız sorumludur.

En azından şunları gösterin:

• Gönderilecek tutar.
• Para birimi ve blokzincir ağı.
• Kripto adresi.
• Gerekiyorsa hedef etiketi veya memo.
• Son geçerlilik süresi.
• Fonların yalnızca seçilen ağ üzerinden gönderilmesi gerektiğine dair uyarı.

Örnek talimat:

Send exactly 100 USDT on Tron (TRC-20) to:

TXXXXXXXXXXXXXXXXXXXXXXXXXXXX

This invoice expires at 2026-01-15 10:30 UTC.
Do not send funds on another network.

Hedef etiketi veya memo gerektiren ağlarda bunu adresin yanında açıkça gösterin.

Adım 4: Ödeme durumunu kontrol edin

Fatura oluşturulduktan sonra arka ucunuz ödeme durumunu kontrol etmelidir.

Uç nokta:

GET /api/orders

Zorunlu sorgu parametresi:

Parametre	Açıklama
orderId	Üye işyerinin sipariş tanımlayıcısı.

İsteğe bağlı sorgu parametresi:

Parametre	Açıklama
sciName	Siparişle ilişkili Hosted Checkout veya mağaza adı.

Örnek istek:

GET /api/orders?orderId=ORDER-1001&sciName=Store

Örnek yanıt:

{
  "orderId": "ORDER-1001",
  "sciName": "Store",
  "paymentStatus": "PROCESSING",
  "paymentMethod": "CRYPTO_INVOICE",
  "paymentCreated": "2026-01-15T10:30:00",
  "transaction": {
    "status": "PROCESSING"
  },
  "invoice": {
    "invoiceStatus": "PROCESSING",
    "cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "initialSenderAmount": 100,
    "actualReceivedAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
  }
}

Ödeme durumları

Siparişi sisteminizde nasıl güncelleyeceğinize karar vermek için paymentStatus değerini kullanın.

Durum	Anlamı	Önerilen işlem
CREATED	Fatura oluşturuldu ve ödeme bekleniyor.	Siparişi beklemede tutun.
PROCESSING	Ödeme tespit edildi veya işleniyor.	Siparişi beklemede tutun ve kontrol etmeye devam edin.
COMPLETED	Ödeme başarıyla tamamlandı.	Siparişi ödendi olarak işaretleyin ve ürünü veya hizmeti teslim edin.
FAILED	Ödeme başarısız oldu, süresi doldu veya tamamlanamadı.	Siparişi teslim etmeyin. Müşteriden yeni bir ödeme başlatmasını isteyin.

Siparişi yalnızca durum COMPLETED olduktan sonra ödenmiş sayın.

API + Hosted Checkout akışı

Müşteriye yönelik ödeme sayfasını Hosted Checkout'un yönetmesini, sipariş takibi ve mutabakat kontrolünün ise API ile arka ucunuzda kalmasını istiyorsanız bu modeli kullanın.

Ödeme akışı:

1. Sisteminizde bir sipariş oluşturun.
2. Hosted Checkout entegrasyonunuzla müşteriyi Hosted Checkout'a yönlendirin.
3. orderId değerinizi Hosted Checkout ödeme talebinde iletin.
4. Müşteri ödemeyi Hosted Checkout sayfasında tamamlar.
5. Volet.com, Status URL'nize ödeme durumu bildirimi gönderir.
6. Arka ucunuz bildirimin imzasını doğrular.
7. Arka ucunuz sipariş durumunu günceller.
8. İsteğe bağlı olarak arka ucunuz mutabakat için siparişi API üzerinden de kontrol eder.

Bu modelde ödeme sayfasını, ödeme yöntemi seçimini, ödeme talimatlarını ve müşteri yönlendirmelerini Hosted Checkout yönetir.

API, ödeme emrini orderId ile almak ve nihai durumu sisteminizde mutabakata bağlamak için yine kullanılabilir.

Hosted Checkout ile durumun işlenmesi

Hosted Checkout kullanırken yalnızca Success URL veya Failed URL yönlendirmelerine güvenmeyin.

Müşteri yönlendirmeleri tarayıcı akışının parçasıdır ve sunucunuza her zaman ulaşmayabilir. Sipariş durumunu güvenilir şekilde güncellemek için Status URL bildirimini ve API ile sipariş sorgulamayı kullanın.

Önerilen yaklaşım:

1. Hosted Checkout Status URL bildirimini alın.
2. Bildirimin imzasını doğrulayın.
3. Bildirim geçerliyse sipariş durumunu güncelleyin.
4. API ile sipariş sorgulamayı yedek veya mutabakat kontrolü olarak kullanın.

Hata işleme

Merchant API hataları yapılandırılmış bir hata yanıtı döndürür.

Yaygın hata durumları:

HTTP durumu	Anlamı
400	İstek hatalı biçimlendirilmiş veya geçersiz parametreler içeriyor.
401	Kimlik doğrulama başlıkları eksik veya geçersiz.
403	API'nin istenen işlemi kullanma izni yok.
404	İstenen kaynak bulunamadı.
500	Beklenmedik sunucu hatası.

Hata oluştuğunda:

• Destek ve teşhis için errorId değerini kaydedin.
• Hatayla ilgili istek alanını belirlemek için errorField değerini kontrol edin.
• Otomatik olarak yinelenen sipariş oluşturmayın.
• Yalnızca güvenli olduğunda yeniden deneyin.

Test kontrol listesi

Gerçek kripto ödemeleri kabul etmeden önce tüm akışı test edin.

Yalnızca API entegrasyonlarında şunları doğrulayın:

• Fatura kontrolü.
• Fatura oluşturma.
• Ödeme adresinin gösterilmesi.
• Gerektiğinde hedef etiketinin veya memonun gösterilmesi.
• Fatura süresinin dolmasının işlenmesi.
• Sipariş durumunun düzenli sorgulanması.
• Tamamlanan ödemelerin işlenmesi.
• Başarısız veya süresi dolmuş ödemelerin işlenmesi.
• Yinelenen orderId değerlerinin işlenmesi.

API + Hosted Checkout entegrasyonlarında ayrıca şunları doğrulayın:

• Müşterinin Hosted Checkout'a yönlendirilmesi.
• Status URL bildirimlerinin iletilmesi.
• Bildirim imzasının doğrulanması.
• Success URL ve Failed URL yönlendirmeleri.
• Mutabakat için API ile sipariş sorgulama.

Önemli notlar

• Yalnızca API entegrasyonları Hosted Checkout callback'lerini kullanmaz.
• Arka ucunuz ödeme durumunu API üzerinden kontrol etmelidir.
• Her ödeme için her zaman benzersiz bir orderId kullanın.
• API'nin döndürdüğü adresi, tutarı, para birimini, ağı ve hedef etiketini her zaman aynen gösterin.
• Ödeme durumu COMPLETED olana kadar siparişi ödendi olarak işaretlemeyin.
• Kripto ödemeler blokzincir onaylarına ve ağ koşullarına bağlıdır.
• Fonları yanlış adrese veya ağa göndermek fonların kalıcı olarak kaybedilmesine yol açabilir.

İlgili sayfalar

• Ödeme ağ geçidi oluşturma — API'nizi oluşturun ve yapılandırın
• Emanetçi kripto ödemeleri kabul etme — emanetçi kripto ödemeler nasıl çalışır
• Hosted Checkout entegrasyonu — barındırılan ödeme sayfasını kullanın
• API referansı — yöntemler, parametreler ve yanıtlarla ilgili eksiksiz dokümantasyon