Ortak Veri Sözlüğü - StarPay

Servisler aynı kavram için her zaman aynı tipi kullanmaz (ör. currency). Aşağıdaki tablolar bu farkları servis bazında gösterir. API sözleşmesi metinle standartlaştırılmamıştır; her servisin kendi sayfasındaki tip geçerlidir.

Tanımlayıcı alanlar

Alan	Kim üretir	Nerede kullanılır	Açıklama
conversationId	Üye işyeri	Her istek (header veya form), yanıtta `responseHeader.conversationId`	İstek–yanıt eşleştirme referansı. İmzaya dahildir.
orderId	StarPay (Provision, Link ve Hosted yanıtında)	İade, İptal, Inquire	Ödeme yanıtında dönen sipariş numarası.
orderId (Hosted Payment isteği)	Üye işyeri	Hosted Payment başlatma isteği	İstekte üye işyerinin gönderdiği işlem benzersiz değeri.
paymentConversationId	—	Inquire isteği ve yanıtı	”Ödeme esnasında verilen benzersiz değer”.
originalOrderId	—	PostAuth isteği, Hosted Payment sorgulama yanıtı	Orijinal işlemin sipariş numarası.
threeDSessionId	StarPay	GetThreeDSession yanıtı → Init3ds, GetThreeDSessionResult, Provision	3D Secure oturum değeri.
cardToken	StarPay	Token yanıtı → Provision, GetThreeDSession, BIN, Puan Sorgulama, Linkle Ödeme	Kart bilgisinin yerine geçen değer.
trackingId	StarPay	Hosted Payment yanıtı ve sorgulaması	Hosted Payment işlem takip değeri.
merchantNumber	StarPay (tanımlama sırasında)	Kimlik doğrulama	İşyeri numarası (örn. `1100000000`).
merchantId	StarPay	Hosted Payment sorgulama yanıtı	GUID biçimli işyeri tanımlayıcısı; merchantNumber’dan farklıdır.

Tutar, para birimi ve taksit

Alan	Servis	Tip	Not
amount	Provision, GetThreeDSession, Return, Hosted Payment, Taksit	number (ondalıklı)	Örneklerde `5`, `5.0`, `30` biçimlerinde görülür.
pointAmount	Provision, GetThreeDSession, Linkle Ödeme	number	Kullanılacak puan tutarı.
currency	Provision, GetThreeDSession, Puan Sorgulama, Inquire yanıtı	string	Örneklerde `TRY`. Varsayılan değer `TRY` olarak belirtilmiştir.
currency	Hosted Payment	integer	Örneklerde `949`.
installmentCount	Provision, GetThreeDSession, Linkle Ödeme, Inquire yanıtı	integer	Taksitsiz işlem örneklerinde `0`.
installmentNumber / installmentNumberEnd	Taksit Sorgulama yanıtı	integer	Taksit aralığının başı ve sonu.
commissionRate	Taksit Sorgulama yanıtı	number	Komisyon oranı.

Tarih ve saat formatları

Servisler farklı tarih biçimleri döner. Karşılaştırma yapmadan önce alanın biçimini kontrol edin.

Alan	Servis	Tip	Örnek
responseHeader.responseDateTime	Tüm JSON servisleri	string	`20251205165616937`
reconciliationDate	Provision, Reverse, GetThreeDSession, Inquire (`provisionList`)	string	`20251205165616793`, `20250516000000000`
transactionDate	Inquire (`provisionList`)	string	`2025-05-16 13:43:49`
transactionDate, expiryDate	Hosted Payment sorgulama	string (ISO 8601 date-time)	`2024-04-24T15:32:52.421869`
pointExpiryDate	Puan Sorgulama	string (date-time)	`2025-12-05T13:12:02.953Z`

Enum değerleri

Değerler OpenAPI tanımındaki yazımıyla verilmiştir.

Enum	Kullanıldığı alanlar	Değerler
PaymentType	`paymentType`	`Auth`, `PreAuth`, `PostAuth`
TransactionType	`transactionType`	`Auth`, `PreAuth`, `Return`, `PostAuth`, `Reverse`
TransactionStatus	`transactionStatus`	`Pending`, `Fail`, `Success`, `Returned`, `PartiallyReturned`, `Reversed`, `Closed`, `PartiallyClosed`
IntegrationMode	`integrationMode`	`Unknown`, `Api`, `Hpp`, `ManuelPaymentPage`, `LinkPaymentPage`, `OnUs`
HppPageViewType	`pageViewType`	`Redirect`, `Iframe`
CardBrand	`cardBrand`	`Undefined`, `UnionPay`, `Amex`, `Visa`, `Troy`, `MasterCard`, `Diners`, `JCB`, `ProprietaryDomestic`
CardType	`cardType`	`Unknown`, `Credit`, `Debit`, `Prepaid`
CardSubType	`cardSubType`	`Unknown`, `Classic`, `Business`, `Debit`, `Electron`, `Maestro`, `Proprietary`, `Gold`
CardNetwork	`cardNetwork`	`Unknown`, `CardFinans`, `World`, `Paraf`, `Maximum`, `Axess`, `Advantage`, `Bonus`, `BankKart`, `SaglamKart`, `Bank24`, `HasatKart`, `MilesAndSmiles`, `Neo`, `ShopAndFly`, `Tosla`, `UretenKart`, `Wings`, `Param`
ProfileCardType	Taksit yanıtında `profileCardType`	`Credit`, `Debit`, `International`, `Amex`, `Wallet`
ReturnStatus	Inquire yanıtında `returnStatus`	`NoAction`, `Pending`, `Approved`, `Rejected`
ReturnApprovalStatus	Return yanıtında `approvalStatus`	`None`, `PendingApproval`, `Approved`
ChannelStatus	Hosted sorgulama `hppStatus`	`Active`, `Passive`, `Expired`, `Cancelled`, `Completed`
ChannelPaymentStatus	Hosted sorgulama `hppPaymentStatus`	`Pending`, `Success`, `Failed`, `Expired`
WebhookStatus	Hosted sorgulama `webhookStatus`	`Pending`, `Completed`, `Failed`

Yanıt alanlarının ilişkisi

Alan	Anlamı
isSucceed	Servis yanıtındaki üst düzey başarı göstergesi. `false` ise işlem başarısız değerlendirilir. Inquire örnek yanıtında `isSucceed: true` iken `transactionStatus: Fail` döndüğü görülür; sorgulama servislerinde ödeme sonucunu `transactionStatus` alanından okuyun.
errorCode / errorMessage	Hata durumunda Hata Kodları tablosundaki kod ve mesaj.
responseHeader.responseCode	Servis yanıt kodu; `errorCode` ile aynı kod kümesi olmayabilir.
transactionStatus	Yalnızca ilgili işlemin durumunu bildiren servislerde (Inquire, Hosted Payment sorgulama) döner.
threeDResult / mdStatus / currentStep	Yalnızca 3D doğrulama adımını anlatır; ödemenin sonucu değildir. 3D Secure Ödeme Süreci sayfasına bakın.

Servis bazında farklılıklar

Konu	Farklılık
Kimlik doğrulama konumu	Kart Token ve Init3ds: form alanı. Diğer JSON servisleri ve Taksit/Hosted sorgulama: header.
İstek biçimi	Token ve Init3ds: `multipart/form-data`. Taksit Sorgulama ve Hosted sorgulama: GET. Diğerleri: `application/json`.
Taksit Sorgulama	`binNumber` ve `amount` header değil, query string parametresidir.
Para birimi	Hosted Payment: integer (`949`). Diğer servisler: string (`TRY`).
Tarih biçimi	Servise göre `yyyyMMddHHmmssfff`, `yyyy-MM-dd HH:mm:ss` veya ISO 8601.
Telefon kodu	Örneklerde `90` ve `+90` biçimleri birlikte görülür.
Enum yazımı	OpenAPI tanımındaki yazım (`PreAuth`, `PostAuth`, `MasterCard`) esas alınmalıdır.