API İşlemleri

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.

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

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

AUTH

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; Tüm isteklerde aşağıdaki 3 adet header zorunludur:

📌 Gerekli Header'lar

Header	Açıklama	Örnek Değer
X-Client-Id	Size özel tanımlanan kimlik bilgisi	abc123
X-Timestamp	İsteğin gönderildiği UTC zamanı	1720000000 (Unix time)
X-Signature	HMAC-SHA256 ile oluşturulan imza	3a1f7f...

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

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

PHP

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

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

Fail Response:

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

1. HESAP DOĞRULAMA:

Bir son kullanıcının hesabının doğrulanması için validation sorgusudur. POST | {{BASE_URL}}/api/accountVerification

Parametre Adı	Veri Tipi	Zorunluluk	Örnek Değer	Açıklama
msisdn	string	Evet	905320001234	B2B üyesi telefon numarası bilgisidir. Alan kodu ve telefon numarası birleşik şekilde + olmadan gönderilir
name	string	-	Test	B2B üyesi isim bilgisidir.
surname	string	-	Test	B2B üyesi soyisim bilgisidir.
identityNumber	string	-	12345678901	B2B üyesi tckn bilgisidir.
email	string	-	[email protected]	B2B üyesi e-posta bilgisidir.
birthDate	string	-	01.02.1998	B2B üyesi doğum günü bilgisidir.
iysCheck	boolean	-	true	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.

REQUEST BODY PARAMETERS: (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'

RESPONSE: Eğer 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
}

Eğer kullanıcı MARS’ta kayıtlıysa:

{
    "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 (CASHBACK) TRANSFERİ:

Bir son kullanıcının hesabına para (cashback) transfer yapmak için kullanılacak endpointtir. POST | {{BASE_URL}}/api/walletToWalletTransfer

REQUEST BODY PARAMETERS: (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 de 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'

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 BAKİYESİ 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.

POST | {{BASE_URL}}/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
}