WF
VOLT HAVALE IFRAME API
Merchant Integration Documentation
Payments API Header Signature Callbacks

IFRAME Ödeme API
Deposit, Withdraw & Callback

Merchant sisteminizden yatırım ve çekim talebi oluşturun; işlem sonuçlarını callback adresiniz üzerinden güvenli hash imzası ile alın.

API Endpointleri Callback Yapısı
POST

Deposit

Yatırım talebi.

POST

Withdraw

Çekim talebi.

OUTBOUND

Callback

Sonuç bildirimi.

SHA-256

Signature

İmza doğrulama.

Authentication & İstek İmzası

Deposit ve withdraw isteklerinde aşağıdaki üç header zorunludur. X-Timestamp Unix timestamp olmalı ve sunucu saatinden en fazla 300 saniye sapmalıdır.

HeaderGerekliAçıklama
X-Api-KeyEvetMerchant API anahtarı.
X-HashEvetHeader signature değeri.
X-TimestampEvetUnix saniye, en fazla ±300 saniye.

Request Header Hash Formula

SHA256(API_KEY + MERCHANT_SECRET + TIMESTAMP)
POST

Deposit Oluşturma

https://apiservices.walletgate.services/api/v1/deposit

Request Body

useridstring/intZorunluKullanıcı kimliği.
usernamestringZorunluKullanıcı adı.
namesurnamestringZorunluAd soyad.
methodstringZorunluDeğer: bank
amountnumberZorunluYatırım tutarı.
ext_idstringZorunluMerchant işlem ID.
callback_urlurlZorunluSonuç bildirimi adresi.
Deposit Request
{
  "userid": "10244",
  "username": "demo_user",
  "namesurname": "Mehmet Yılmaz",
  "method": "bank",
  "amount": 2500,
  "ext_id": "DEP-000001",
  "callback_url": "https://merchant.example.com/payment/callback"
}
201 Created
{
  "status": true,
  "code": 201,
  "message": "Para Yatırma Talebi Başarıyla Oluşturuldu.",
  "detail": {
    "deposit_id": 8451,
    "uuid": "transaction-uuid",
    "userid": "10244",
    "method": "bank",
    "amount": 2500,
    "url": "https://payment.example.com/payment/bankdeposit/TOKEN"
  }
}
POST

Withdraw Oluşturma

https://apiservices.walletgate.services/api/v1/withdraw

Ek Request Alanı

accountnumberstringZorunluPara gönderilecek IBAN.

Diğer zorunlu alanlar: userid, username, namesurname, method, amount, ext_id, callback_url.

Withdraw Request
{
  "userid": "10244",
  "username": "demo_user",
  "namesurname": "Mehmet Yılmaz",
  "method": "bank",
  "amount": 1000,
  "ext_id": "WDR-000001",
  "accountnumber": "TR000000000000000000000000",
  "callback_url": "https://merchant.example.com/payment/callback"
}
201 Created
{
  "status": true,
  "message": "Para Çekme Talebiniz Başarıyla Oluşturuldu.",
  "detail": {
    "withdraw_id": 9201,
    "ext_id": "WDR-000001",
    "uuid": "transaction-uuid",
    "userid": "10244",
    "amount": 1000
  }
}

Callback Doğrulama

İşlem sonuçlandığında VOLT HAVALE, işlem oluştururken gönderdiğiniz callback_url adresine JSON POST isteği yapar. Merchant tarafı gelen callback içindeki hash değerini doğrulamalıdır.

DEPOSIT CALLBACK HASH
SHA256("deposit" + API_KEY + MERCHANT_SECRET + UUID + EXT_ID + STATUS)
WITHDRAW CALLBACK HASH
SHA256("withdraw" + API_KEY + MERCHANT_SECRET + UUID + EXT_ID + STATUS)
CALLBACK

Deposit Callback Body

Yatırım talebi onaylandığında veya reddedildiğinde merchant callback URL’inize gönderilir.

POST callback_url · application/json
{
  "type": "deposit",
  "message": "Yatırım Talebi Sonuçlandı",
  "id": 8451,
  "ext_id": "DEP-000001",
  "currency": "TRY",
  "uuid": "transaction-uuid",
  "userid": "10244",
  "amount": 2500,
  "status": 1,
  "method": "bank",
  "hash": "GENERATED_CALLBACK_SHA256"
}
CALLBACK

Withdraw Callback Body

Çekim talebi onaylandığında veya reddedildiğinde merchant callback URL’inize gönderilir.

POST callback_url · application/json
{
  "type": "withdraw",
  "message": "Çekim Talebi Sonuçlandı",
  "id": 9201,
  "ext_id": "WDR-000001",
  "currency": "TRY",
  "uuid": "transaction-uuid",
  "userid": "10244",
  "amount": 1000,
  "status": 1,
  "method": "bank",
  "hash": "GENERATED_CALLBACK_SHA256"
}

Callback Status Değerleri

Kodunuzdaki $status_id değerine göre callback standardı aşağıdaki gibi yayınlanmalıdır.

DeğerDurumAçıklama
0Pendingİşlem sonuç bekliyor.
1Approvedİşlem başarıyla onaylandı.
2Rejectedİşlem reddedildi.

Standart HTTP Response Kodları

API yanıtlarını aşağıdaki standarda çekmeniz, merchant tarafında hata yönetimini net ve otomasyona uygun hâle getirir.

201Yeni talep oluşturulduDeposit veya withdraw başarıyla kaydedildi.
200Mevcut işlem döndürüldüIdempotent tekrar isteğinde bekleyen işlem detayı.
401Authentication başarısızEksik header, invalid API key, invalid hash, expired timestamp.
403Yetki yokMerchant’in bu aksiyonu kullanma izni yoksa.
409ConflictAynı ext_id zaten kayıtlı veya reddedilecek aktif talep çakışması.
422Validation hatasıEksik/geçersiz body alanı, yanlış URL veya yanlış method.
503Geçici servis uygun değilUygun hesap yok veya provider geçici olarak işlem kabul etmiyor.
500Beklenmeyen sunucu hatası

PHP Doğrulama Örnekleri

Request Header Signature
<?php
$timestamp = time();
$hash = hash(
  'sha256',
  $apiKey . $merchantSecret . $timestamp
);

$headers = [
  'X-Api-Key' => $apiKey,
  'X-Hash' => $hash,
  'X-Timestamp' => $timestamp,
];
Callback Hash Validation
<?php
$expectedHash = hash(
  'sha256',
  $body['type'] .
  $apiKey .
  $merchantSecret .
  $body['uuid'] .
  $body['ext_id'] .
  $body['status']
);

if (!hash_equals($expectedHash, $body['hash'])) {
  return response()->json([
    'status' => false,
    'message' => 'Invalid callback hash'
  ], 401);
}

return ["status" => true];
Kod kopyalandı