HPM Ödeme Linki Oluşturma

Açıklama

Bu servis, site sahibinin sisteminden gelen sipariş / işlem bilgileri ile ödeme isteği bazlı tek bir link üretir.

Üretilen link, kullanıcı tarafından tıklandığında Finrota ödeme ekranına yönlendirir ve ödeme orada tamamlanır.

Endpoint (Demo): https://pgw.netahsilatdemo.com/hpm
Metot: POST
Content-Type: application/json
Kimlik Doğrulama: Authorization: Bearer {token}

Request Body Yapısı

Alanlar ve Zorunluluk Durumu

Genel Alanlar

Alan	Tip	Zorunlu	Açıklama
`currencyCode`	String	Evet	Ödeme para birimi (örn: `TRY`, `USD`).
`clientOrderReference`	String	Evet	Site sahibinin kendi sipariş referansı. Sisteminizde benzersiz olmanız önerilir.
`amount`	Decimal	Evet	Ödeme tutarı. Pozitif olmalıdır.
`paymentSetId`	String	Evet	Finrota tarafında tanımlı ödeme seti / senaryosunun benzersiz kimliği (GUID).
`description`	String	Hayır	Ödeme açıklaması. Portal ve raporlarda görünebilir.

Müşteri Bilgileri (customer)

Alan	Tip	Zorunlu	Açıklama
`customer.email`	String	Evet	Müşterinin e-posta adresi. Bildirimler ve iletişim için kullanılır.
`customer.gsm`	String	Hayır	Müşterinin GSM numarası. SMS bildirimleri için kullanılabilir.
`customer.tckn`	String	Hayır	Müşterinin TCKN bilgisi. Kimlik doğrulama / raporlama için.
`customer.code`	String	Hayır	Site sahibinin sisteminde müşteriyi temsil eden kod.
`customer.name`	String	Hayır	Müşterinin adı.
`customer.surname`	String	Hayır	Müşterinin soyadı.
`customer.erpCode`	String	Hayır	Entegrasyon tarafında kullanılan ERP kodu.

Yönlendirme & Bildirim URL’leri

Alan	Tip	Zorunlu	Açıklama
`successURL`	String	Hayır	Ödeme başarılı olduktan sonra müşterinin tarayıcısının yönlendirileceği URL.
`failURL`	String	Hayır	Ödeme başarısız / iptal olduğunda müşterinin tarayıcısının yönlendirileceği URL.
`webhookURL`	String	Hayır	Ödeme sonuçlandığında, Finrota tarafından sunucu tarafına yapılacak HTTP POST çağrısı için kullanılacak webhook adresi.

Önemli – webhookURL Alanı

HPM isteğinde gönderdiğiniz webhookURL, ödeme tamamlandıktan sonra Finrota’nın sunucu tarafından çağıracağı (callback) URL’dir.
Finrota, ödeme işlemi sonuçlandığında bu adrese HTTP POST isteği gönderir.
webhookURL adresinizin, bu isteğe 200 OK yanıtı vermesi beklenir. 200 dışında cevaplar hata olarak değerlendirilebilir.
Gönderilen gövdede (body) ödeme işlemine ait özet bilgiler yer alır:

Alan	Açıklama
`Id`	İşlem ID’si (TransactionId).
`TransactionStatusId`	İşlem durumu (başarılı, başarısız vb. durum kodu).
`OrderReference`	Finrota tarafından üretilen sipariş referansı.
`ClientOrderReference`	Sizin gönderdiğiniz `clientOrderReference` değeri.
`PureAmount`	Net tahsilat tutarı.
`CurrencyId`	İşlem para birimi.
`VPosErrorCode`	Sanal pos hata kodu (varsa).
`VPosErrorMessage`	Sanal pos hata mesajı (varsa).

Örnek Webhook Gövdesi

{

"Id": "d6a1f4b2-1c3e-4a21-9b1e-11aa22bb33cc",

"TransactionStatusId": 1,

"OrderReference": "HPM-20251201-00001",

"ClientOrderReference": "0005",

"PureAmount": 150.00,

"CurrencyId": "TRY",

"VPosErrorCode": null,

"VPosErrorMessage": null

}

Back-end tarafınızda bu POST çağrısını karşılayıp, body’i okuyarak kendi sipariş kayıtlarınızı “ödendi / başarısız” olarak güncellemeniz gerekir.

Kullanıcı Doğrulama Alanları

Alan	Tip	Zorunlu	Açıklama
`userVerificationBy`	String	Evet	Müşteriyi doğrularken kullanılacak alan türü. Geçerli değerler: `Id`, `Email`, `Tckn`, `Gsm`.
`userVerificationFailBehavior`	String	Evet	Doğrulama başarısız olduğunda izlenecek davranış. Örn. `"Create"`: Kullanıcı bulunamazsa yeni müşteri oluşturma senaryosu. Diğer opsiyonlar portal konfigürasyonuna göre değişebilir (hata verme, varsayılan kullanıcı ile devam etme gibi).

Dinamik Alanlar (`additionalData`)

Alan	Tip	Zorunlu	Açıklama
`additionalData`	Object	Hayır	Dinamik alanların gönderileceği sözlük yapısı. Anahtarlar, Finrota’da tanımlı dinamik alan kodlarıdır. Örn: `"1606_Dinamik_Alan_tr": "4"`

userVerificationBy

Kullanıcının Finrota tarafında hangi alan üzerinden doğrulanacağını belirtir.

Olası değerler

"Id" – Müşterinin sistem ID’si ile doğrulama
"Email" – E-posta adresi ile doğrulama
"Tckn" – TCKN ile doğrulama
"Gsm" – GSM numarası ile doğrulama

userVerificationFailBehavior

Belirtilen userVerificationBy alanına göre kullanıcı bulunamazsa sistemin davranışını belirler.

Hata ver → Örneğin: "Error"
- Kullanıcı bulunamazsa istek hata ile sonuçlanır.
Yeni müşteri oluştur → "Create"
- Kullanıcı bulunamazsa Finrota tarafında yeni müşteri kaydı oluşturulur.
Varsayılan kullanıcı ile devam et → (örn. "Default" / "DefaultUser" vb.)
- Kullanıcı bulunamazsa sistem varsayılan tanımlı kullanıcı ile devam eder.

Not: Enum değerlerinin tam string karşılıkları (Error, DefaultUser vb.) entegrasyon sırasında tarafınıza net olarak iletilmelidir. Örnekte yalnızca "Create" değeri garanti edilmiştir.

additionalData

additionalData alanı, Finrota portalında tanımlı dinamik alanları beslemek için kullanılır.

Key’ler genellikle ilgili dinamik alan kodu/adı ile eşleşmelidir.

Örneğin

"additionalData": {   
  "1606_Dinamik_Alan_tr": "4",  
  "1606_dinamik_Alan_tr": "55"  
}

Örnek İstek (Request)

Header
Body
Örnek cURL

Authorization: Bearer {token}  
Content-Type: application/json

{  
  "currencyCode": "TRY",  
  "clientOrderReference": "0005",  
  "amount": 150,  
  "customer": {  
    "email": "[email protected]",  
    "gsm": "5000000000",  
    "tckn": "00000000000",  
    "code": "13wedas12",  
    "name": "John",  
    "surname": "Doe",  
    "erpCode": "asdc123ff19"  
  },  
  "successURL": "https://webhook.free.beeceptor.com/success",  
  "failURL": "https://google.com?q=fail",  
  "webhookURL": "https://yahoo.com",  
  "paymentSetId": "504978bf-bebd-40c5-89aa-b76f3a20341c",  
  "description": "hpm test",  
  "userVerificationBy": "Id",  
  "userVerificationFailBehavior": "Create",  
  "additionalData": {  
    "1606_Dinamik_Alan_tr": "4",  
    "1606_dinamik_Alan_tr": "55"  
  }  
}

curl --location 'https://pgw.netahsilatdemo.com/hpm' \  
--header 'Content-Type: application/json' \  
--header 'Authorization: Bearer {token}' \  
--data '{  
  "currencyCode": "TRY",  
  "clientOrderReference": "0005",  
  "amount": 150,  
  "customer": {  
    "email": "[email protected]",  
    "gsm": "5000000000",  
    "tckn": "00000000000",  
    "code": "13wedas12",  
    "name": "testadı7",  
    "surname": "testsoyadı6",  
    "erpCode": "asdc123ff19"  
  },  
  "successURL": "https://webhook.free.beeceptor.com/success",  
  "failURL": "https://google.com?q=fail",  
  "webhookURL": "https://yahoo.com",  
  "paymentSetId": "504978bf-bebd-40c5-89aa-b76f3a20341c",  
  "description": "hpm test",  
  "userVerificationBy": "Id",  
  "userVerificationFailBehavior": "Create",  
  "additionalData": {  
    "1606_Dinamik_Alan_tr": "4",  
    "1606_dinamik_Alan_tr": "55"  
  }  
}'

Yanıt (Response) Modeli

Başarılı bir istekte HPM, aşağıdaki yapıda bir cevap döner

{  
  "message": null,  
  "statusCode": 200,  
  "exceptions": null,  
  "data": {  
    "link": "https://testportal.netfinans.com/netahsilat/hpm?id=3e1c720e-baa1-4672-955f-07bad7a23133&timestamp=1764601213815&sign=b5c709a40eeeee308cf2f32a40457a2b8a8e88711352c93a4f91d109d7d23fd3",  
    "expiryUtc": "2025-12-01T15:15:13.8152725"  
  },  
  "oldData": null,  
  "errors": null  
}

Alan Açıklamaları

statusCode
- HTTP seviyesinden bağımsız olarak, uygulama içi durum kodunu da yansıtabilir. 200 → başarı.
data.link
- Kullanıcının yönlendirileceği tekil ödeme linki.
- Not: Her ödeme isteği için tek bir link döner.
- Bu link tarafında ödeme ekranına yönlenerek, istek aşamasında girilen bilgiler ile birlikte ödeme ekranında görüntülenecektir.
- Ödeme ekranına yönlendirdikten sonra, ödeme işlemini mevcut yapıda olduğu şekilde gerçekleştirilir.
data.expiryUtc
- Linkin geçerlilik bitiş tarihini/ saatini UTC formatında içerir.
- Format her zaman ISO-8601’dir (örn. "2025-12-01T15:15:13").
sign
- Güvenlik imzası linkin query string’i içinde yer alır (sign=...).
- Ayrı bir alan olarak JSON içinde dönmez.