Payment API · v1.2

Payment API v1.2

Merchant entegrasyonu için Auth, Hash, BankList, CheckDeposit, DepositCreate, Withdraw ve Callback akışlarını tek sayfada açıklayan teknik dokümantasyon.

Technical integration guide covering Auth, Hash, BankList, CheckDeposit, DepositCreate, Withdraw and Callback flows in a single page.

Bearer JWT

Yetkilendirme

Authorization

MD5

Mevcut hash uyumluluğu

Current hash compatibility

Decimal Deposit

Küsürat kabul edilir

Decimals accepted

Integer Withdraw

Küsürat kabul edilmez

Decimals not accepted

Entegrasyon Özeti

Integration Overview

QUICK START

1 · AuthJWT token üret.Generate a JWT token.

2 · BankListAktif banka listesini al. Gerçek hash gerekmez.Get active banks. A real hash is not required.

3 · TransactionDeposit veya withdraw isteğini oluştur.Create a deposit or withdrawal request.

4 · CallbackSonucu callback ile al ve payload üzerinden hash doğrula.Receive the final result and verify the hash from callback payload fields.

Önemli: /api/merchant/checkdeposit bir işlem durum sorgulama endpointi değildir. Sadece kullanıcının işlemi başlatacağı URL'yi döndürür.

Important: /api/merchant/checkdeposit is not a transaction-status endpoint. It only returns the URL where the user starts the deposit flow.

Ortak Header'lar

Common Headers

Accept: application/json
Content-Type: application/json
Authorization: Bearer <JWT_TOKEN>

Auth çağrısında Authorization header kullanılmaz. Callback ise merchant sistemine gelen sunucudan sunucuya çağrıdır.

Authorization is not used on the Auth call. Callback is a server-to-server request received by the merchant system.

Yaygın Hata Kodları

Common Error Codes

400	Validation / hatalı parametreValidation / invalid parameter
401	Token / kimlik doğrulama problemiToken / authentication problem
403	Hash / yetki problemiHash / authorization problem
409	Duplicate transactionDuplicate transaction
503	Uygun hesap yok / servis meşgulNo eligible account / service unavailable

Auth — JWT Token Üretimi

Auth — Obtain JWT Token

POST /api/auth/token

partnerID ve partnerKey ile JWT token alınır. Sonraki yetkili çağrılarda Authorization: Bearer <token> kullanılır.

Send partnerID and partnerKey to obtain a JWT token. Use Authorization: Bearer <token> on subsequent authorized requests.

Not: Auth response içinde expires, expiresIn veya benzeri bir süre alanı dönmez.

Note: The Auth response does not include an expires, expiresIn, or equivalent expiry property.

Request Body

{
  "partnerID": "<SID>",
  "partnerKey": "<KEY>"
}

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Hash — İmza Üretimi ve Örnekler

Hash — Signature Generation & Examples

POST /api/hash/createhost

Mevcut entegrasyon, alanların belirlenmiş sırada birleştirilip UTF-8 üzerinden MD5 hex üretilmesi mantığını kullanır. Alan sırası ve büyük/küçük harf dönüşümleri değiştirilmemelidir.

The current integration builds a canonical string in a strict field order and calculates an MD5 hex digest over UTF-8. Do not change field order or defined casing/normalization rules.

BankList istisnası: BankList için gerçek hash üretmek zorunlu değildir. hash alanına boş string ("") veya rastgele bir string gönderilebilir.

BankList exception: BankList does not require a real hash. The hash field may be an empty string ("") or any random string.

Withdraw Hash Sırası

Withdraw Hash Order

#	Key	DeğerValue
1	Amount	Tam sayı tutar. Withdraw küsürat kabul etmez.Integer amount. Withdraw does not accept decimals.
2	CurrencyCode	TRY
3	AccountNumber	IBAN
4	Key	MerchantKey
5	PaymentName	service / havale
6	PaymentTransactionID	transactionId / trx
7	PlayerFullName	fullname
8	PlayerID	userId
9	Secret	password / shared secret

Örnek 1 — Withdraw

Example 1 — Withdraw

Amount = 1000
CurrencyCode = TRY
IBAN = TR210001200977700001010561
MerchantKey = DEMO_KEY
PaymentName = havale
TransactionId = WD-20260919-0001
MerchantFullname = John Doe
MerchantUserID = user001
Password = DEMO_SECRET

Canonical String:
Amount1000CurrencyCodeTRYAccountNumberTR210001200977700001010561KeyDEMO_KEYPaymentNamehavalePaymentTransactionIDWD-20260919-0001PlayerFullNameJohn DoePlayerIDuser001DEMO_SECRET

MD5:
00fab2b2f6d9611717bb25bda529543f

Örnek 2 — DepositCreate

Example 2 — DepositCreate

Deposit tarafında küsüratlı tutar kabul edilir. DepositCreate hash diziliminde AccountNumber anahtarı bulunur fakat değeri boş bırakılır.

Deposit accepts decimal amounts. In the DepositCreate canonical hash string, the AccountNumber key is present but its value is empty.

Amount = 1000.50
CurrencyCode = TRY
AccountNumber = ""
MerchantKey = DEMO_KEY
PaymentName = havale
TransactionId = DP-20260919-0001
MerchantFullname = John Doe
MerchantUserID = user001
Password = DEMO_SECRET

Canonical String:
Amount1000.50CurrencyCodeTRYAccountNumberKeyDEMO_KEYPaymentNamehavalePaymentTransactionIDDP-20260919-0001PlayerFullNameJohn DoePlayerIDuser001DEMO_SECRET

MD5:
4ce0ed3bfd7b5e3ed3b873adc90d956c

C# Örneği

C# Example

using System.Security.Cryptography;
using System.Text;

static string CreateMd5(string canonicalString)
{
    using var md5 = MD5.Create();
    var bytes = Encoding.UTF8.GetBytes(canonicalString);
    var hash = md5.ComputeHash(bytes);
    return Convert.ToHexString(hash).ToLowerInvariant();
}

BankList — Aktif Bankalar

BankList — Active Banks

POST /api/merchant/banklist

Aktif banka/hesap listesini döndürür. JWT gereklidir. Gerçek hash gerekli değildir.

Returns the active bank/account list. JWT is required. A real hash is not required.

Hash: "", "test" veya rastgele başka bir string gönderilebilir.

Hash: You may send "", "test", or any other random string.

min parametresi: Response içinde görülen min alanının entegrasyon tarafında işlevsel bir karşılığı yoktur; işlem kuralı olarak kullanılmamalıdır.

min parameter: The min value returned in the response has no functional integration meaning and should not be used as a transaction rule.

Request

{
  "sid": "2134",
  "hash": ""
}

200 OK

{
  "code": 200,
  "data": [
    { "id": "9", "name": "Bank-A", "min": 250 },
    { "id": "13", "name": "Bank-B", "min": 350 }
  ]
}

CheckDeposit — İşlem URL'si Oluşturma

CheckDeposit — Create Transaction URL

POST /api/merchant/checkdeposit

Davranış: Bu endpoint yalnızca kullanıcının para yatırma işlemini gerçekleştireceği URL'yi döndürür. Mevcut işlemin durumunu, sonucunu veya onayını kontrol etmek için kullanılmaz.

Behavior: This endpoint only returns the URL where the user performs the deposit transaction. It is not used to check an existing transaction's status, result, or approval.

Deposit tutarı küsüratlı olabilir; örneğin 50.25 geçerlidir.

Deposit amounts may contain decimals; for example 50.25 is valid.

Request

{
  "sid": 2002,
  "username": "testuser",
  "userId": "user001",
  "fullname": "John Doe",
  "amount": 50.25,
  "trx": "DP-20260919-0001",
  "currencyCode": "TRY",
  "return_url": "https://merchant.example.com/return",
  "service": "havale",
  "hash": "<MD5_HASH>"
}

200 OK

{
  "code": 200,
  "message": "Deposit start.",
  "data": null,
  "url": "https://pay.example.com/redirect/abc"
}

DepositCreate — H2H Deposit

POST /api/merchant/depositcreate

Redirect oluşturmadan deposit kaydını açar ve seçilen banka hesabını JSON olarak döndürür. Deposit tutarı küsüratlı olabilir.

Creates the deposit without a redirect and returns the selected bank account as JSON. Deposit amounts may contain decimals.

bankId: 0 otomatik seçim, >0 ise belirtilen bankaya yönlendirme mantığında kullanılır.

bankId: Use 0 for automatic selection, or >0 to target a specific bank.

Request

{
  "sid": 2002,
  "username": "testuser",
  "userID": "user001",
  "fullname": "John Doe",
  "amount": 20000.50,
  "trx": "656959310",
  "return_url": "Deposit",
  "currencyCode": "TRY",
  "service": "havale",
  "bankId": 0,
  "hash": "<MD5_HASH>"
}

200 OK

{
  "code": 200,
  "message": "OK",
  "data": {
    "ProcedID": 886439,
    "BankID": 19,
    "IBAN": "TR210001200977700001010561",
    "HesapSahibi": "JOHN DOE",
    "KasaId": 11,
    "BankName": "Bank-A",
    "limit": 10000,
    "maxlimit": 100000,
    "ParaBirimi": "TRY",
    "isFast": true
  }
}

Withdraw — Para Çekme Talebi

Withdraw — Payout Request

POST /api/merchant/withdraw

Tutar kuralı: Withdraw isteğinde küsürat kabul edilmez. 1000 geçerlidir; 1000.50 geçerli değildir.

Amount rule: Withdraw does not accept decimal amounts. 1000 is valid; 1000.50 is not.

IDNumber: Zorunlu değildir. Alan request'ten tamamen çıkarılabilir veya entegrasyon ihtiyacına göre herhangi bir string değer (ör. "test") gönderilebilir.

IDNumber: This field is optional. It may be omitted from the request entirely, or any string value (for example "test") may be sent when needed.

Request

{
  "bankId": "9",
  "iban": "TR210001200977700001010561",
  "idNumber": "test",
  "CurrencyCode": "TRY",
  "amount": 1000,
  "merchantSid": 2002,
  "merchantKey": "<KEY>",
  "merchantUserId": "user001",
  "merchantUsername": "testuser",
  "merchantFullname": "John Doe",
  "transactionId": "WD-20260919-0001",
  "service": "havale",
  "type": "direct",
  "hash": "<MD5_HASH>"
}

200 OK

{
  "code": 200,
  "message": "Save success.",
  "withdrawId": "w_01Hxxx"
}

Callback — İşlem Sonuç Bildirimi

Callback — Transaction Result Notification

SYSTEM → MERCHANT

Deposit veya withdraw işlemi sonuçlandığında platform, merchant tarafında tanımlı callback URL'sine sunucudan sunucuya bildirim gönderir.

When a deposit or withdrawal reaches a final result, the platform sends a server-to-server notification to the merchant's configured callback URL.

Hash doğrulaması: Callback hash'i sabit veya bağımsız bir değer değildir. Hash, callback request içinde gönderilen parametrelerin değerleri üzerinden, hash alanının kendisi hariç tutularak, entegrasyonda tanımlı sıraya göre üretilmelidir. Merchant aynı girdiyi üretip hash'i karşılaştırmalıdır.

Hash verification: The callback hash is not a fixed or independent value. It must be generated from the actual parameter values sent in the callback request, excluding the hash field itself and following the agreed canonical order. The merchant must rebuild the same input and compare the hash.

Merchant response zorunluluğu: Callback endpoint'i yalnızca HTTP status dönmemelidir. Merchant response body her durumda JSON olmalı ve mutlaka code ile message alanlarını içermelidir. HTTP status taşıma/protokol sonucunu, code ve message ise uygulama seviyesindeki sonucu açıklar.

Merchant response requirement: The callback endpoint must not return only an HTTP status. The merchant response body must always be JSON and must contain both code and message. The HTTP status represents the transport/protocol result, while code and message describe the application-level result.

Callback Body

{
  "hash": "<GENERATED_HASH>",
  "sid": 2002,
  "key": "<PARTNER_KEY>",
  "service": "havale",
  "method": "deposit",
  "user_id": "user001",
  "username": "testuser",
  "fullname": "John Doe",
  "amount": 1000.50,
  "currency": "TRY",
  "transaction_id": "12345",
  "status": "SUCC",
  "data": "",
  "trx": "TX987654321"
}

Callback Hash Girdisi Örneği

Callback Hash Input Example

sid2002keyDEMO_KEYservicehavalemethoddeposituser_iduser001usernametestuserfullnameJohn Doeamount1000.50currencyTRYtransaction_id12345statusSUCCdatatrxTX987654321

MD5:
15df138667da1e0e5361d1a4f2bbf606

Zorunlu Merchant Callback Response

Required Merchant Callback Response

Field	ZorunluRequired	AçıklamaDescription
`code`	EvetYes	Merchant uygulamasının callback sonucunu belirten kod.Application-level callback result code returned by the merchant.
`message`	EvetYes	Sonucu açıklayan okunabilir mesaj.Human-readable message describing the result.

Başarılı Response Örneği

Success Response Example

HTTP/1.1 200 OK
{
  "code": 200,
  "message": "Success."
}

Hata Response Örneği

Error Response Example

HTTP/1.1 400 Bad Request
{
  "code": 400,
  "message": "Invalid hash."
}

Güvenlik: Gerçek partner key, parola, raw JWT, T.C. kimlik numarası ve tam IBAN değerlerini herkese açık dokümantasyona veya uygulama loglarına yazmayın. Security: Do not publish real partner keys, passwords, raw JWTs, national ID values, or full IBANs in public documentation or application logs.