API entegrasyonu

Merchant API üzerinden Volet.com hesabınızdan Volet.com kullanıcılarına ve harici kripto cüzdanlara ödeme gönderin.

Mass Payout API, uygulamanızın ödeme işlemlerini programatik olarak oluşturmasını, doğrulamasını ve izlemesini sağlar.

API'yi üç ana ödeme senaryosu için kullanabilirsiniz:

• Volet.com kullanıcılarına ödemeler — Volet.com hesabınızdan başka bir Volet.com hesabına para gönderin.
• Dönüştürmesiz kripto ödemeler — aynı kripto bakiyesinden harici bir kripto cüzdana kripto para gönderin.
• Dönüştürmeli kripto ödemeler — USD, EUR, USDT veya başka bir kripto para gibi desteklenen başka bir bakiyeden harici bir kripto cüzdana kripto para gönderin.

Toplu ödemeler API üzerinden nasıl çalışır

Merchant API her istek için bir ödeme işlemi oluşturur.

Toplu ödeme gruplarında arka ucunuz bir alıcı listesi hazırlar ve gruptaki her kalem için ayrı bir ödeme işlemi oluşturur.

Tipik bir grup akışı:

1. Sisteminizde bir ödeme grubu hazırlayın.
2. Volet.com cüzdanlarınızdaki kullanılabilir bakiyeleri kontrol edin.
3. Gerektiğinde limitleri, tarifeleri ve döviz kurlarını kontrol edin.
4. Her ödemeyi oluşturmadan önce doğrulayın.
5. Ödeme işlemlerini API üzerinden oluşturun.
6. Döndürülen işlem kimliklerini sisteminizde saklayın.
7. Ödeme durumlarını API üzerinden izleyin.
8. Tamamlanan, başarısız, iptal edilen veya iade edilen ödemeleri mutabakata bağlayın.

Başlamadan önce

API üzerinden toplu ödeme göndermek 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.
• Volet.com hesabınızda yeterli bakiye.
• Her ödeme yöntemi için gereken alıcı bilgileri.

API'nizi oluşturmak ve yapılandırmak için Toplu ödemeleri etkinleştirme 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.

Önerilen ödeme akışı

Ödemeleri oluşturmadan önce arka ucunuz her kalemi doğrulayıp hazırlamalıdır.

Önerilen akış:

1. Cüzdan bakiyelerini alın.
2. Seçilen ödeme yöntemi ve para birimi için asgari limitleri kontrol edin.
3. Tarifeleri veya ücretleri kontrol edin.
4. Ödeme dönüştürme kullanıyorsa döviz kuru bilgisini kontrol edin.
5. Ödeme talebini doğrulayın.
6. Ödeme işlemini oluşturun.
7. Döndürülen transactionId değerini saklayın.
8. Ödeme nihai bir duruma ulaşana kadar işlem durumunu düzenli sorgulayın.

Adım 1: Cüzdan bakiyelerini alın

Ödemeleri oluşturmadan önce Volet.com cüzdanlarınızdaki kullanılabilir bakiyeleri kontrol etmek için bu yöntemi kullanın.

Uç nokta:

GET /api/account/balances

Örnek yanıt:

[
  {
    "walletId": "W000000000001",
    "amount": 1000.50,
    "currency": "USD"
  },
  {
    "walletId": "W000000000002",
    "amount": 2500,
    "currency": "USDT"
  }
]

Ödeme talepleri oluştururken kaynak cüzdan olarak walletId değerini kullanın.

Adım 2: Limitleri ve tarifeleri kontrol edin

Ödeme göndermeden önce seçilen ödeme yöntemi ve para birimi çifti için asgari limitleri ve tarifeleri kontrol edin.

Asgari limitler:

GET /api/account/limits/min

Tarifeler:

GET /api/account/tariffs

Desteklenmeyen tutarlar, para birimleri veya ödeme yöntemleri nedeniyle ödeme oluşturma hatalarını önlemek için bu yöntemleri kullanın.

Adım 3: Döviz kuru bilgisini kontrol edin

Ödeme dönüştürme gerektirdiğinde döviz kuru bilgisini kullanın.

Uç nokta:

POST /api/exchange-rate/information

Kaynak para birimi ile ödeme para biriminin farklı olduğu ödemeleri oluşturmadan önce bunu kullanın.

Örnek kullanım senaryoları:

• USD bakiyesinden harici bir kripto cüzdana USDT gönderme.
• EUR bakiyesinden harici bir kripto cüzdana BTC gönderme.
• Desteklenen bir kripto bakiyesini başka bir ödeme para birimine dönüştürme.

Ödeme yöntemi 1: Volet.com kullanıcılarına ödeme gönderme

Alıcının Volet.com hesabı varsa bu yöntemi kullanın.

Fonlar Volet.com hesabınızdan alıcının Volet.com hesabına dahili olarak aktarılır.

Bu yöntem blokzincir onayı gerektirmez ve harici kripto cüzdan adresleri kullanmaz.

Volet.com kullanıcısına ödemeyi doğrulayın

İşlemi oluşturmadan önce ödemeyi doğrulayın.

Uç nokta:

POST /api/withdrawal/validation/internal-other

Örnek istek:

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

Doğrulama, işlem oluşturmadan ödeme bilgilerini kontrol eder.

Volet.com kullanıcısına ödeme oluşturun

Doğrulama başarılı olduktan sonra ödeme işlemini oluşturun.

Uç nokta:

POST /api/withdrawal/internal-other

Örnek istek:

{
  "srcWalletId": "W000000000001",
  "amount": 25,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 001",
  "srcCurrency": "USD",
  "destCurrency": "USD",
  "destEmail": "[email protected]"
}

Örnek yanıt:

{
  "transactionId": "11111111-1111-4111-8111-111111111111",
  "paymentMethodType": "INTERNAL_OTHER",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 25,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.13,
  "comment": "Payout batch 2026-06-26 / recipient 001"
}

Döndürülen transactionId değerini sisteminizde saklayın ve ödeme durumunu izlemek için kullanın.

İsteğe bağlı: Alıcıların Volet.com hesaplarını doğrulayın

Ödeme akışınız ödemeler oluşturulmadan önce alıcıların e-posta adreslerini topluyorsa ödeme talepleri oluşturmadan önce Volet.com hesaplarının var olup olmadığını kontrol edebilirsiniz.

Uç nokta:

GET /api/account/exists

Akışınız ek alıcı kontrolleri gerektiriyorsa hesap sahibi bilgilerini de eşleştirebilirsiniz.

Uç nokta:

GET /api/account/matching

Yanlış alıcı bilgilerinden kaynaklanan başarısız ödemeleri azaltmak için bu yöntemleri kullanın.

Ödeme yöntemi 2: Dönüştürmesiz kripto ödemeler gönderme

Aynı kripto bakiyesinden harici bir kripto cüzdana kripto para göndermek istediğinizde bu yöntemi kullanın.

Örneğin:

• USDT bakiyenizden harici bir USDT TRC-20 adresine USDT gönderme.
• BTC bakiyenizden harici bir BTC adresine BTC gönderme.
• ETH bakiyenizden harici bir ETH adresine ETH gönderme.

Alıcının Volet.com hesabına ihtiyacı yoktur.

Dönüştürmesiz kripto ödemeyi doğrulayın

İşlemi oluşturmadan önce kripto ödemeyi doğrulayın.

Uç nokta:

POST /api/withdrawal/validation/cryptowallet

Örnek istek:

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Ödeme token'ı ve blokzincir ağı için doğru destCurrency değerini kullanın.

Memo, hedef etiketi veya benzer bir tanımlayıcı gerektiren ağlarda bunu address.memo alanına ekleyin.

Örnek:

{
  "address": {
    "address": "rXXXXXXXXXXXXXXXXXXXXXXXX",
    "memo": "123456"
  }
}

Dönüştürmesiz kripto ödeme oluşturun

Doğrulama başarılı olduktan sonra ödeme işlemini oluşturun.

Uç nokta:

POST /api/withdrawal/cryptowallet

Örnek istek:

{
  "srcWalletId": "W000000000002",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 002",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "email": "[email protected]"
  }
}

Örnek yanıt:

{
  "transactionId": "22222222-2222-4222-8222-222222222222",
  "paymentMethodType": "CRYPTO_WALLET",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USDT",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000002",
  "fullCommission": 0.25,
  "comment": "Payout batch 2026-06-26 / recipient 002"
}

Ödeme yöntemi 3: Dönüştürmeli kripto ödemeler gönderme

Kaynak bakiye ile ödeme para birimi farklı olduğunda bu yöntemi kullanın.

Örneğin:

• USD bakiyesinden harici bir cüzdana USDT gönderme.
• EUR bakiyesinden harici bir cüzdana BTC gönderme.
• Desteklenen başka bir bakiyeden desteklenen bir ağ üzerinden USDC gönderme.

Alıcı kripto parayı harici bir kripto cüzdana alır. Dönüştürme ödeme akışı sırasında yapılır.

Dönüştürmeli kripto ödemeyi doğrulayın

İşlemi oluşturmadan önce ödemeyi doğrulayın.

Uç nokta:

POST /api/withdrawal/validation/crypto-external

Örnek istek:

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Kaynak bakiyenin para birimini tanımlamak için srcCurrency, alıcıya gönderilen kripto parayı ve ağı tanımlamak için destCurrency kullanın.

Dönüştürmeli kripto ödeme oluşturun

Doğrulama başarılı olduktan sonra ödeme işlemini oluşturun.

Uç nokta:

POST /api/withdrawal/crypto-external

Örnek istek:

{
  "srcWalletId": "W000000000001",
  "amount": 100,
  "action": "GIVE",
  "note": "Payout batch 2026-06-26 / recipient 003",
  "srcCurrency": "USD",
  "destCurrency": "USDT_TRC20",
  "address": {
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  },
  "receiverInfo": {
    "firstName": "Alex",
    "lastName": "Example",
    "email": "[email protected]"
  }
}

Örnek yanıt:

{
  "transactionId": "33333333-3333-4333-8333-333333333333",
  "paymentMethodType": "CRYPTO_EXTERNAL",
  "transactionType": "WITHDRAWAL",
  "status": "CREATED",
  "direction": "WITHDRAWAL",
  "currency": "USD",
  "amount": 100,
  "createdAt": "2026-01-15T10:30:00",
  "walletSrcId": "W000000000001",
  "fullCommission": 0.50,
  "comment": "Payout batch 2026-06-26 / recipient 003"
}

İstek alanları

Yaygın ödeme talebi alanları:

Alan	Zorunlu	Kullanıldığı yer	Açıklama
srcWalletId	Hayır	Tüm ödeme yöntemleri	Volet.com hesabınızdaki kaynak cüzdan kimliği.
amount	Evet	Tüm ödeme yöntemleri	Ödeme tutarı. Nasıl yorumlanacağı action değerine bağlıdır.
action	Evet	Tüm ödeme yöntemleri	Tutar modu. Olası değerler: GIVE, GET.
note	Hayır	Tüm ödeme yöntemleri	Dahili not veya ödeme açıklaması.
srcCurrency	Hayır	Volet.com kullanıcılarına ödemeler, dönüştürmeli kripto ödemeler	Ödeme için kullanılan kaynak para birimi.
destCurrency	Evet	Tüm ödeme yöntemleri	Alıcıya yatırılan veya harici kripto cüzdana gönderilen para birimi.
destEmail	Hayır	Volet.com kullanıcılarına ödemeler	Alıcının Volet.com hesabının e-posta adresi.
destWalletId	Hayır	Volet.com kullanıcılarına ödemeler	Uygun olduğunda alıcının cüzdan kimliği.
address.address	Evet	Harici kripto ödemeler	Alıcının kripto cüzdan adresi.
address.memo	Hayır	Harici kripto ödemeler	Seçilen ağ gerektiriyorsa memo, hedef etiketi veya benzer tanımlayıcı.
receiverInfo	Hayır	Harici kripto ödemeler	Gerektiğinde ad, e-posta, doğum tarihi veya şirket adı gibi alıcı bilgileri.

GIVE ve GET

Ödeme tutarının nasıl yorumlanacağını tanımlamak için action kullanın.

İşlem	Anlamı
GIVE	Tutar, kaynak taraftan gönderilecek tutar olarak kabul edilir.
GET	Tutar, desteklendiğinde alıcının alması gereken tutar olarak kabul edilir.

Döviz dönüştürmeli ödemelerde ödemeyi oluşturmadan önce döviz kuru bilgisini kontrol edin. Böylece sisteminiz işlem oluşturulmadan önce beklenen kaynak ve hedef tutarlarını gösterebilir veya saklayabilir.

Ödeme durumunun izlenmesi

Bir ödeme oluşturduktan sonra döndürülen transactionId değerini saklayın.

En güncel ödeme durumunu almak için işlem sorgulamayı kullanın.

Uç nokta:

GET /api/transactions/{id}

İşlem geçmişinde de arama yapabilirsiniz.

Uç nokta:

GET /api/transactions

Kullanışlı filtreler:

Filtre	Açıklama
paymentDirections	DEPOSIT veya WITHDRAWAL ile filtreleme.
transactionStatus	İşlem durumuna göre filtreleme.
wallets	Cüzdan kimliklerine göre filtreleme.
startDate / endDate	Oluşturma tarihi aralığına göre filtreleme.
searchLabel	Uygun olduğunda metin etiketine göre arama.
offset / limit	Sonuçları sayfalama.
sortOrder	Sonuçları oluşturma tarihine göre sıralama.

İşlem durumları

Kendi sisteminizdeki ödeme durumunu güncellemek için işlem durumunu kullanın.

Durum	Anlamı	Önerilen işlem
CREATED	Ödeme işlemi oluşturuldu.	İşlemi saklayın ve izlemeye devam edin.
READY_TO_PROCESS	Ödeme işlenmeye hazır.	İzlemeye devam edin.
PENDING	Ödeme beklemede.	İzlemeye devam edin.
PROCESSING	Ödeme işleniyor.	İzlemeye devam edin.
EXCHANGING	Döviz dönüştürme sürüyor.	İzlemeye devam edin.
COMPLETED	Ödeme tamamlandı.	Ödemeyi sisteminizde tamamlandı olarak işaretleyin.
CANCELLING	İptal işlemi sürüyor.	Nihai durumu bekleyin.
CANCELED	Ödeme iptal edildi.	Ödemeyi iptal edildi olarak işaretleyin.
REFUNDING	İade sürüyor.	Nihai durumu bekleyin.
REFUNDED	Ödeme iade edildi.	Ödemeyi iade edildi olarak işaretleyin.

Ödemeyi yalnızca durum COMPLETED olduktan sonra tamamlanmış sayın.

Ödemeleri iptal etme

Bazı işlemler, iptale hâlâ izin verildiği sürece iptal edilebilir.

Uç nokta:

DELETE /api/transactions/{transactionId}

İptal imkânı ödeme yöntemine, işlem durumuna ve işleme aşamasına bağlıdır.

Blokzincir işlemi yayınlandıktan sonra kripto ödemelerin iptaline güvenmeyin. Ödemeyi oluşturmadan önce tüm alıcı adreslerini, para birimlerini, ağları ve tutarları doğrulayın.

Toplu işleme önerileri

Toplu ödemelerde grubun yaşam döngüsünü arka ucunuz yönetmelidir.

Önerilen yaklaşım:

1. Ödeme grubuna dahili bir kimlik atayın.
2. Her ödemeye dahili bir kalem kimliği atayın.
3. İşlemleri oluşturmadan önce her kalemi doğrulayın.
4. Yalnızca doğrulanan kalemler için işlem oluşturun.
5. Dahili kalem kimliğiniz ile döndürülen transactionId arasındaki eşleşmeyi saklayın.
6. Her işlemi ayrı ayrı izleyin.
7. Yalnızca başarısız veya oluşturulmamış kalemleri yeniden deneyin.
8. Grubu tamamlandı olarak işaretlemeden önce nihai durumları mutabakata bağlayın.

Yinelenen ödemeler göndermekten kaçının. Uygulamanız bir zaman aşımından sonra isteği yeniden deniyorsa önce o kalem için zaten bir işlem oluşturulup oluşturulmadığını kontrol edin.

Hata işleme

Merchant API hataları yapılandırılmış hata yanıtları 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.
• Hiçbir işlemin oluşturulmadığını doğrulamadan otomatik olarak yerine geçecek bir ödeme oluşturmayın.
• Yalnızca güvenli olduğunda yeniden deneyin.

Test kontrol listesi

Gerçek toplu ödemeler göndermeden önce tüm akışı test edin.

Volet.com kullanıcılarına ödemeler için:

• Alıcı hesabının doğrulanması.
• Ödemenin doğrulanması.
• Ödemenin oluşturulması.
• İşlem durumunun izlenmesi.
• Tamamlanan, iptal edilen ve başarısız senaryolar.

Dönüştürmesiz kripto ödemeler için:

• Doğru token ve ağ seçimi.
• Adres ve memonun işlenmesi.
• Ödemenin doğrulanması.
• Ödemenin oluşturulması.
• Blokzincir işleminin izlenmesi.
• Yanlış adres veya desteklenmeyen ağ durumlarının işlenmesi.

Dönüştürmeli kripto ödemeler için:

• Bakiye kontrolü.
• Döviz kuru kontrolü.
• Ödemenin doğrulanması.
• Ödemenin oluşturulması.
• EXCHANGING ve COMPLETED durumları.
• Kaynak ve hedef para birimleri arasında tutar mutabakatı.

Toplu işleme için:

• Grubun kısmen başarısız olduğu durumların işlenmesi.
• Yeniden deneme mantığı.
• Yinelenen ödemelerin önlenmesi.
• Gruplar ile işlemler arasındaki dahili eşleşme.
• Nihai mutabakat raporu.

Önemli notlar

• API her istek için bir ödeme işlemi oluşturur.
• Grupların düzenlenmesinden arka ucunuz sorumludur.
• İşlemleri oluşturmadan önce ödemeleri her zaman doğrulayın.
• Döndürülen transactionId değerlerini her zaman saklayın.
• Nihai durumu izlemek için işlem sorgulamayı veya işlem geçmişini kullanın.
• Durum COMPLETED olana kadar bir ödemeyi tamamlandı olarak işaretlemeyin.
• Kripto ödemelerde işlemi oluşturmadan önce alıcının adresini, token'ı, ağı ve memoyu her zaman doğrulayın.
• Kriptoyu yanlış adrese veya yanlış ağ üzerinden göndermek fonların kalıcı olarak kaybedilmesine yol açabilir.
• API kimlik bilgileri asla ön uç kodunda açığa çıkarılmamalıdır.

İlgili sayfalar

• Toplu ödemeleri etkinleştirme — ödeme göndermeden önce API'nizi kurun
• Volet.com kullanıcılarına ödeme gönderme — Volet.com hesaplarına dahili ödemeler gönderin
• Emanetçi kripto ödemeleri gönderme — Volet.com hesabınızdan harici cüzdanlara kripto gönderin
• Toplu ödemelere genel bakış — ödeme yöntemlerini ve modellerini karşılaştırın
• API referansı — yöntemler, parametreler ve yanıtlarla ilgili eksiksiz dokümantasyon