MARSlı Kullanıcı

Bu doküman, “Mars Pay” ürünü ile ödeme alma işleminin teknik detaylarını içermektedir.

Mars Pay Butonu (Mars’lı Kullanıcı Akışı)

“ProAccount” Web/App uygulamalarında bulunan ödeme ekranlarına eklenecek “Mars ile Öde” butonu aracılığıyla, aşağıda detayları aktarılan ödeme süreci başlatılır. Mars uygulamasına yönlendirilen kullanıcı, işlemi uygulama üzerinden onaylayarak ödemeyi tamamlar. Başarılı ödeme sonrasında ProAccount sistemi, önceden tanımlanmış olan callback URL üzerinden bilgilendirilir ve kullanıcıya başarılı ödeme ekranı gösterilir.

Akış

Mars ile Öde butonuna tıklandıktan sonra aşağıdaki adımlar izlenir;

• Aşağıda verilen örnek request modeli ile PredefinedMarsPayTransaction endpoint’ine istek atılır ve başarılı (success) bir response beklenir.

• Response içinde gelen ConversationID, tüm ödeme akışı boyunca kullanılacaktır.

• Başarılı response sonrasında kullanıcı, https://pay.marsneo.com/marspay/{{conversationId}}/{{paymentType}} URL’ine yönlendirilen kullanıcı otomatik olarak Mars mobil uygulamasına yönlenir.

  • paymentType = 1; MARS'lı kullanıcı akışı.

• Eğer Mars mobil uygulaması kullanıcının cihazında yüklü değilse, ilgili uygulama mağazasına yönlendirilir. Uygulama indirilir ve kayıt işlemi gerçekleştirilir.

• Eğer kullanıcı daha önce kayıt olmuşsa, giriş (login) işlemini gerçekleştirir.

• Kullanıcı, “Mars Pay > Mars ile Öde” ekranına yönlendirilir ve Mars hesabındaki bakiyesiyle veya tanımlı diğer ödeme yöntemleriyle işlemi tamamlar.

• amount tutarı ProAccount’ın kurumsal Mars hesabına aktarılır.

• Ödeme işlemi tamamlandıktan sonra, MARS, işlem sonucuna bağlı olarak ProAccount tarafından tanımlanmış olan SuccessCallbackURL veya FailCallbackURL adreslerinden birini tetikler.

• ProAccount, https://prodapi.marsneo.com/evtpay-admin-api/v1/checkPaymentStatus endpoint’i üzerinden ödeme durumunu ve tutarını kontrol eder.

• checkPaymentStatus endpoint’inden dönen response değerine göre, kullanıcı ProAccount içerisinde ilgili ödeme sonucu ekranına yönlendirilir.

Mars ile Öde – Entegrasyon API Dokümantasyonu

Get Token (Login)

Bu endpoint, sistemdeki yönetici kullanıcıların kimlik doğrulamasını yaparak erişim için gerekli olan AccessToken bilgisini sağlar. Alınan AccessToken, diğer tüm servis çağrılarında header içinde AccessToken={{accessToken}} şeklinde gönderilmelidir.

POST: https://prodapi.marsneo.com/evtpay-admin-api/v1/login

Örnek Request:

{
  "data": {
    "username": "username",
    "password": "password"
  }
}

Örnek Response:

{
  "responseId": "000-1717148012-f2f72c620f9df3fbf23c70689955af9bd6d9",
  "isSuccessful": true,
  "errorCode": 0,
  "message": "Operation is successful!",
  "data": {
    "accessToken": "000-1717148012-\nfe942455bfec4f5769957cb55a74b1d640ad",
    "expireDate": "2024-05-31T10:33:32+0000",
    "adminData": {
      "id": 46,
      "status": 1,
      "role": {
        "id": 6,
        "name": "Administrator ",
        "isSuperadmin": false,
        "auths": {
          "ADMIN_ROLES": [
            "LIST",
            "DELETE",
            "EDIT"
          ],
          "CAMPAIGN_PROMOCODES": [
            "LIST",
            "EDIT",
            "SET_USED"
          ],
          "CONTENT_AND_DEFINITIONS": [
            "DELETE",
            "EDIT",
            "LIST"
          ],
          "TRANSACTIONS": [
            "LIST"
          ],
          "USERS": [
            "SEE_PRIV_DATA",
            "EDIT",
            "LIST"
          ],
          "CAMPAIGNS_AND_COLONIES": [
            "LIST",
            "EDIT",
            "DELETE"
          ],
          "ADMINS": [
            "DELETE",
            "EDIT",
            "LIST"
          ],
          "API_TRANSLATIONS": [
            "LIST",
            "EDIT"
          ],
          "CUSTOMER_ORDERS": [
            "LIST",
            "EDIT_PRIV_DATA"
          ],
          "CUSTOMER_WALLETS": [
            "LIST",
            "EDIT_PRIV_DATA"
          ]
        }
      },
      "msisdn": "905057077007",
      "email": "[email protected]",
      "username": "omer.mars",
      "firstName": "Ömer",
      "middleName": "",
      "lastName": "Imzalı",
      "defaultLang": "en"
    }
  },
  "challenge": null
}

Token Refresh (refreshAccessToken)

Bu endpoint, süresi dolmak üzere olan veya süresi dolmuş AccessToken’ı yenilemek için kullanılır. Her istek için header’a AccessToken = {{accessToken}} eklenmelidir.

POST: https://prodapi.marsneo.com/evtpay-admin-api/v1/refreshAccessToken

Örnek Response:

{
  "responseId": "000-1717148079-209f480d8a211850b8ab0012ba2ff4011088",
  "isSuccessful": true,
  "errorCode": 0,
  "message": "Operation is successful!",
  "data": {
    "accessToken": "000-1717148079-\r\n3afd0c855d9bd92140937de25cc9e919bfb4",
    "expireDate": "2024-05-31T10:34:39+0000",
    "adminData": {
      "id": 46,
      "status": 1,
      "role": {
        "id": 6,
        "name": "Administrator ",
        "isSuperadmin": false,
        "auths": {
          "ADMIN_ROLES": [
            "LIST",
            "DELETE",
            "EDIT"
          ],
          "CAMPAIGN_PROMOCODES": [
            "LIST",
            "EDIT",
            "SET_USED"
          ],
          "CONTENT_AND_DEFINITIONS": [
            "DELETE",
            "EDIT",
            "LIST"
          ],
          "TRANSACTIONS": [
            "LIST",
            "pazarama-mars-pay.md 2024-05-31",
          ],
          "USERS": [
            "SEE_PRIV_DATA",
            "EDIT",
            "LIST"
          ],
          "CAMPAIGNS_AND_COLONIES": [
            "LIST",
            "EDIT",
            "DELETE"
          ],
          "ADMINS": [
            "DELETE",
            "EDIT",
            "LIST"
          ],
          "API_TRANSLATIONS": [
            "LIST",
            "EDIT"
          ],
          "CUSTOMER_ORDERS": [
            "LIST",
            "EDIT_PRIV_DATA"
          ],
          "CUSTOMER_WALLETS": [
            "LIST",
            "EDIT_PRIV_DATA"
          ]
        }
      },
      "msisdn": "905057077007",
      "email": "[email protected]",
      "username": "omer.mars",
      "firstName": "Ömer",
      "middleName": "",
      "lastName": "Imzalı",
      "defaultLang": "en"
    }
  },
  "challenge": null
}
 

Ödeme Başlatma (PredefinedMarsPayTransaction)

Servislere erişim sağlanmadan önce, aşağıdaki endpoint kullanılarak bir AccessToken alınmalıdır:

POST http://prodapi.marsneo.com/evtpay-admin-api/v1/login

Alınan AccessToken, tüm POST isteklerinin header’ında "AccessToken" anahtarıyla gönderilmelidir.

Ödeme başlatmak için: POST https://prodapi.marsneo.com/evtpay-admin-api/v1/predefinedMarsPayTransaction

Açıklama:

• conversationId : Her ödeme işlemi için benzersiz olarak üretilen bu kimlik, işlem sürecinin takibini sağlamak amacıyla kullanılır. Güvenlik ve işlem bütünlüğü gereği, oluşturulduğu andan itibaren 30 dakika süreyle geçerlidir. Bu süre zarfında işlem tamamlanmadığı takdirde, geçerliliğini yitirir ve yeni bir conversationId oluşturulması gerekir.

• productId [opsiyonel]: Belirli sayıda ürün satışı yapan firmalarda kullanılabilir, eğer kullanılacak ise her bir productId, entegrasyon öncesinde “Mars Pay” ürünleri ile eşleştirilmek üzere Mars ekibine bildirilmelidir

Örnek Request:

{
    "data": {
        "orderId":"12345678",
        "amount":1,
        "productId":1,
        "corporateId":"TRPX",
        "msisdn":"905511088790"
    }
}

Örnek Success Response:

{
    "responseId": "000-1746535947-a3b7eb61cc2714907b39d2db680beb906b84",
    "isSuccessful": true,
    "errorCode": 0,
    "message": "Operation is successful!",
    "data": {
        "conversationId": "000-1746535947-7f1e34fdae4d6aa5b6317cbf90d959dbb5e3"
    },
    "challenge": null
}

Ödeme Durumu Sorgulama (CheckPaymentStatus)

POST: https://prodapi.marsneo.com/evtpay-admin-api/v1/checkPaymentStatus

Bu endpoint, daha önce başlatılmış bir ödemenin durumunu kontrol etmek için kullanılır. Sorgulama, ödeme sürecinde kullanılan conversationId bilgisi ile yapılır.

Bu işlem, kullanıcının ödeme tamamlandıktan sonra doğru şekilde yönlendirilmesini sağlamak amacıyla ProAccount sisteminde kullanılmalıdır.

Örnek Request:

{
 "data": {
 "conversationId":"{{conversationId}}"
 }
}

Örnek Response-Success:

{
 "responseId": "000-1717148372-be6c5a2a75f7dbfef87810d8bea91189d32c",
 "isSuccessful": true,
 "errorCode": 0,
 "message": "Operation is successful!",
 "data": {
 "orderDetail": {
 "status": "SUCCESS",
 "orderId": "123456",
 "amount": 1025,
 "finishedDate": {{timestamp}},
 "paymentDate": {{timestamp}},
 },
 "challenge": null
}

Örnek Response-Failed:

{
 "responseId": "000-1717148372-be6c5a2a75f7dbfef87810d8bea91189d32c",
 "isSuccessful": true,
 "errorCode": 0,
 "message": "Operation is successful!",
 "data": {
 "orderDetail": {
 "status": "FAILED",
 "orderId": "123456",
 "amount": 1025,
 "finishedDate": {{timestamp}},
 "paymentDate": {{timestamp}},
 },
 "challenge": null
}

Örnek Response-NotFound:

{
 "responseId": "000-1717151254-49e6a5af24ea2ad6b923aa617a2e80773400",
 "isSuccessful": false,
 "errorCode": 21,
 "message": "Order not found!",
 "data": null,
 "challenge": null
}

Status Code Tablosu

Statu Adı	Kod	Açıklama
WAITING	0	İşlem beklemede. Henüz tamamlanmadı veya kullanıcı aksiyonu bekleniyor.
FAILED	-1	İşlem başarısız oldu.
SUCCESS	1	İşlem başarıyla tamamlandı.
PARTIAL_REFUNDED	4	İşlem kısmi olarak iade edildi.
REFUNDED	5	İşlem tamamen iade edildi.
CANCELLED	6	İşlem iptal edildi.

Bu belge, "MARS Pay" entegrasyonu ile ödeme alma sürecinin temel teknik bilgilerini içermektedir. Daha fazla bilgi veya teknik destek gerektiğinde, lütfen Mars geliştirme ekibi ile iletişime geçin.

İyi çalışmalar dileriz! Mars Dev Team