API Dokümantasyonu

Genel Bakış

Bu servis, kurumsal kullanıcıların (MARS PRO) API üzerinden kimlik doğrulaması yaparak hesap doğrulaması, para transferi ve hesap bakiyesi sorgulaması işlemlerinin gerçekleştirmesine olanak tanır.

Base URL: https://protransfer.marsneo.com

API Version: v4.2

Content-Type: application/json

Desteklenen Diller: Türkçe (tr), İngilizce (en)

PROD URL: https://protransfer.marsneo.com/evtpay-thirdparty-services/v1/

TEST URL: https://test-protransfer.marsneo.com/evtpay-thirdparty-services/v1/

---

Kimlik Doğrulama (Authentication)

Bu servis, kurumsal kullanıcıların API üzerinden kimlik doğrulaması yaparak hesap doğrulaması, para transferi ve hesap bakiyesi sorgulaması işlemlerinin gerçekleştirmesine olanak tanır.

Kimlik Doğrulama – HMAC Signature;

Gerekli Header'lar

Header	Tip	Zorunlu	Açıklama
Content-Type	string	Evet	application/json
X-Client-Id	string	Evet	İstemci benzersiz kimliği
X-Timestamp	string	Evet	Unix timestamp (saniye cinsinden)
X-Signature	string	Evet	HMAC-SHA256 imzası

HMAC Signature Oluşturma

HMAC İmza Nasıl Oluşturulur? İmza şu şekilde hesaplanır:

client_secret size özel gizli anahtardır (sunucu tarafında saklanmalıdır).

$data = $clientId . ':' . $timestamp;
$computedSignature = hash_hmac('sha256', $data, $clientSecret);

İmza, X-Signature başlığına yazılır.

İmza Doğrulama Süreci

1. Sunucu, istemciden gelen X-Client-Id ile ilişkili CLIENT_SECRET değerini alır

2. Gelen X-Timestamp değeri ile aynı data string'i oluşturur: "{CLIENT_ID}:{TIMESTAMP}"

3. Kendi HMAC-SHA256 imzasını hesaplar

4. Hesaplanan imza ile gelen X-Signature değerini karşılaştırır

5. Eşleşme varsa istek işlenir, yoksa 1001 hata kodu döner

Fail Response:

{
    "responseId": "000-1753878268-e6e150140b456b92e5e3bf7b9964a53db4ae",
    "isSuccessful": false,
    "errorCode": 12,
    "message": "Timestamp is invalid or expired.",
    "origMsgForClient": null,
    "data": null,
    "dataHash": null,
    "challenge": null
}

API Endpoints

1

Hesap Doğrulama:

Bir son kullanıcının hesabının doğrulanması için validation sorgusudur.

Endpoint: POST /api/accountVerification

Request Body: (urlencoded)

curl --location 'https://test-protransfer.marsneo.com/evtpay-thirdparty-services/v1/api/accountVerification' \
--header 'X-Client-Id: 8f2c6a41-9d49-4r6d-b8c1-2fbc4d0f73e2' \
--header 'X-Timestamp: 1765277155' \
--header 'X-Signature: 5cde10df9a8e08b8d0711b9d6503d30a38f9e328af4c4eb75d3301a15b5da582' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'msisdn=905399161021' \
--data-urlencode 'name=Deneme' \
--data-urlencode 'surname=Soyadı' \
--data-urlencode 'identityNumber=11111111111' \
--data-urlencode '[email protected]' \
--data-urlencode 'birthDate=09.09.1998' \
--data-urlencode 'iysCheck=false'

Parametre	Tip	Zorunlu	Açıklama
msisdn	string	Evet	B2B üyesi telefon numarası bilgisidir. Örnek: 905320001234
name	string	Hayır	B2B üyesi isim bilgisi.
surname	string	Hayır	B2B üyesi soyisim bilgisidir.
identityNumber	string	Hayır	B2B üyesi tckn bilgisidir.
email	string	Hayır	B2B üyesi e-posta bilgisidir.
birthDate	string	Hayır	B2B üyesi doğum günü bilgisidir.
iysCheck	boolean	Hayır	B2B üyesi izin bilgisi. Default olarak false ayarlanmıştır. True yapıldığı taktirde izin bilgisine izin vermiş sayılır ve sms ve varsa email izni verilmiş olur.

RESPONSE: Kullanıcı MARS’ta kayıtlı değilse:

{
    "responseId": "000-1753648718-1776c71458f3ba57a1920dd5b3b62eadaf57",
    "isSuccessful": false,
    "errorCode": 500,
    "message": "OK",
    "origMsgForClient": null,
    "data": null,
    "dataHash": null,
    "challenge": null
}

RESPONSE: Kullanıcı MARS’ta kayıtlı ise:

{
    "responseId": "000-1753648829-a4a9af3af0748a742c9ad1deed73ebbd139e",
    "isSuccessful": true,
    "errorCode": 0,
    "message": "Operation is successful!",
    "origMsgForClient": null,
    "data": {
        "response": {
            "firstName": "Sanem",
            "lastName": "Koca",
            "status": "active"
        }
    },
    "dataHash": null,
    "challenge": null
}

Eğer kullanıcı Mars’ta B2B kontrollerinden önce kayıtlıysa 'isMarsCustomer' true olacak gelecektir. Eğer B2B tarafından gelip üye olduysa 'isMarsCustomer' false olacaktır

2

Para Transferi (Cashback):

Bir son kullanıcının hesabına para (cashback) transfer yapmak için kullanılacak endpointtir.

Endpoint: POST /api/walletToWalletTransfer

Request Body: (urlencoded)

Parametre Adı	Veri Tipi	Zorunluluk	Örnek Değer	Açıklama
phoneNumber	string	Evet	905320001234	Transferin yapılacağı B2B üyesi telefon numarası bilgisidir. Alan kodu ve telefon numarası birleşik şekilde + olmadan gönderilir
amount	float	Evet	3200.54	Gerçekleşmesi istenen transferin değeri
description	string	-	Hesabına para gönderdik.	Transfer için açıklama alanı
iban	string	-	TR120006123437784196845678	Transferin yapılacağı B2B üyesi IBAN bilgisidir.
receiverName	string	Eğer IBAN bilgisi girildiyse zorunludur.	Test Deneme	Transferin yapılacağı B2B üyesi IBAN bilgisi için alıcı isim soyisim bilgisidir.

phoneNumber veya iban bilgisi girilmesi zorunludur. İkisi birden boş olamaz.

Request Example: (urlencoded)

curl --location 'https://test-protransfer.marsneo.com/evtpay-thirdparty-services/v1/api/walletToWalletTransfer' \
--header 'X-Client-Id: 8f2c6a41-9d49-4r6d-b8c1-2fbc4d0f73e2' \
--header 'X-Timestamp: 1765291400' \
--header 'X-Signature: ec8d841a643d744bf416411b6cdbf8511ecbe38bbabd4faf66987e53a0c21e04' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'phoneNumber=905320001234' \
--data-urlencode 'amount=3200.54' \
--data-urlencode 'description=Hesabına para gönderdik.' \
--data-urlencode 'iban=TR120006123437784196845678' \
--data-urlencode 'receiverName=Test Deneme'

Başarılı Response:

{
    "responseId": "000-1753688808-1d9c700e7b86b43d8c1816bd58bd8072cecc",
    "isSuccessful": true,
    "errorCode": 0,
    "message": "Operation is successful!",
    "origMsgForClient": null,
    "data": {
        "response": {
            "paymentId": "000-1753688807-16a45160b7faad1c065fe2f6ede681c7dc37",
            "createdAt": "2025-07-28 07:46:47",
            "resultingBalance": [
                {
                    "currencyCode": 949,
                    "currencyAbbrv": "TL",
                    "totalBalance": 67.7,
                    "topUpBalance": 0,
                    "accountBalance": 67.7,
                    "bonusBalance": 0
                },
                {
                    "currencyCode": 978,
                    "currencyAbbrv": "EUR",
                    "totalBalance": 0,
                    "topUpBalance": 0,
                    "accountBalance": 0,
                    "bonusBalance": 0
                },
                {
                    "currencyCode": 840,
                    "currencyAbbrv": "USD",
                    "totalBalance": 0,
                    "topUpBalance": 0,
                    "accountBalance": 0,
                    "bonusBalance": 0
                }
            ]
        }
    },
    "dataHash": null,
    "challenge": null
}

Fail Response:

{
    "responseId": "000-1753886085-01f14fcff4e261cd7079031783bc47a4d5db",
    "isSuccessful": false,
    "errorCode": 500,
    "message": "Gönderici cüzdan numarası ile alıcı cüzdan numarası farklı olmalıdır.",
    "origMsgForClient": null,
    "data": null,
    "dataHash": null,
    "challenge": null
}

{
    "responseId": "000-1751541224-15c9c6f8fa01ce21f68455763af81d464a33",
    "isSuccessful": false,
    "errorCode": 35,
    "message": "Wallet not found!",
    "origMsgForClient": null,
    "data": null,
    "dataHash": null,
    "challenge": null
}

3

Hesap Bakiyesi Sorgulama:

MARS PRO hesabının kayıtlı bilgilerinin ve bakiyesinin sorgulandığı methottur. Partner tarafından gönderilecek cashback tutarı ödül bakiyesi olup son kullanıcı hesabından nakit çekilemez. Ancak hesaba bağlı MARS kartları ile müşteri harcama amaçlı kullanabilir.

Endpoint: POST /api/getWalletSummary

REQUEST BODY PARAMETERS: (urlencoded)

NULL

REQUEST EXAMPLE: (urlencoded)

NULL

RESPONSE:

{
    "responseId": "000-1753964547-264157fc59096f0c6dfb83aa84cc09d63165",
    "isSuccessful": true,
    "errorCode": 0,
    "message": "Operation is successful!",
    "origMsgForClient": null,
    "data": {
        "response": {
            "accountName": "Sanem Koca",
            "accountNumber": "905399161029",
            "balances": [
                {
                    "currencyCode": 840,
                    "currencyAbbrv": "USD",
                    "totalBalance": 0,
                    "topUpBalance": 0,
                    "accountBalance": 0,
                    "bonusBalance": 0
                },
                {
                    "currencyCode": 978,
                    "currencyAbbrv": "EUR",
                    "totalBalance": 0,
                    "topUpBalance": 0,
                    "accountBalance": 0,
                    "bonusBalance": 0
                },
                {
                    "currencyCode": 949,
                    "currencyAbbrv": "TL",
                    "totalBalance": 65.7,
                    "topUpBalance": 0,
                    "accountBalance": 65.7,
                    "bonusBalance": 0
                }
            ]
        }
    },
    "dataHash": null,
    "challenge": null
}

Fail Response:

{
    "responseId": "000-1751541224-15c9c6f8fa01ce21f68455763af81d464a33",
    "isSuccessful": false,
    "errorCode": 35,
    "message": "Wallet not found!",
    "origMsgForClient": null,
    "data": null,
    "dataHash": null,
    "challenge": null
}

^{_{© 2025 MARS Finansal Yazılım A.Ş. Tüm hakları saklıdır. Bu dokümanın izinsiz kopyalanması, çoğaltılması veya dağıtılması yasaktır.}}