Ödeme Başlatma ve Tamamlama

Endpoint: /pws/payment
HTTP Method: POST
Request Content-Type: application/json
Response Content-Type: application/json
Yetkilendirme: Geçerli AccessToken zorunludur.
(Bkz: 2. Kimlik Doğrulama – AccessToken Alınması)

Açıklama

Bu servis bir kart ödemesini başlatır**.**

3D’li ödeme: Banka OTP (3D Secure) adımı için redirectUrl döner; kullanıcı OTP’yi bankanın sayfasında tamamlar. Ardından otoCommit ile işlem otomatik finalize edilir (başarılı/başarısız).
3D’siz ödeme: Banka tarafı provizyonu başarılıysa OTP olmadan işlem anında tamamlanır (otoCommit anında gerçekleşir); redirectUrl dönmez.

Önemli: transactionStatusId alanı akışın durumunu verir (bkz. “Durum Kodları” bölümü).

Header Bilgileri

Header Adı	Zorunlu	Açıklama
Authorization	Evet	`Bearer {AccessToken}` formatında geçerli token.
Content-Type	Hayır	`application/json`

Request Body

Üst Düzey Alanlar

Alan	Tip	Zorunlu	Açıklama
`agentCode`	string	Evet	İşlem sahibi bayi/alt bayi/müşteri kodu (sistem kurallarına göre zorunlu)
`amount`	number	Evet	İşlem tutarı
`installment`	int	Evet	Taksit sayısı (tek çekim için `1`)
`tenantPosId`	string	Evet	Kullanılacak POS’un tenant kimliği (GUID)
`paymentSetDefinitionId`	string	Evet	Ödeme seti kimliği (GUID)
`currencyCode`	string	Evet	Para birimi (örn. `TRY`)
`use3D`	boolean	Evet	3D Secure kullanılsın mı
`returnUrl`	string	3D’de Evet	3D akışında OTP tamamlandıktan sonra dönüş URL’si
`clientOrderReferenceCode`	string	Hayır	Üye işyeri/uygulama sipariş referansı (idempotency takibi için önerilir)
`contact`	object	Evet	Kart sahibi iletişim bilgileri (aşağıda)
`card`	object	Evet	Kart bilgileri (aşağıda)

`Contact` Alanı

Alan	Tip	Zorunlu	Açıklama
`name`	string	Evet	Ad
`surname`	string	Evet	Soyad
`email`	string	Evet	E-posta
`tckn`	string	Hayır	TCKN (yerel regülasyonlara göre zorunlu olabilir)
`description`	string	Hayır	Açıklama
`phone`	string	Hayır	GSM

`Card` Alanı

Alan	Tip	Zorunlu	Açıklama
`cardNumber`	string	Evet	Kart numarası (PAN)
`cardHolderName`	string	Evet	Kart üzerindeki ad-soyad
`cvv`	string	Evet	Güvenlik kodu
`expMonth`	int	Evet	Son kullanma ayı (1–12)
`expYear`	int	Evet	Son kullanma yılı (YYYY)

Response Yapısı

Kök alanlar

Alan	Tip	Açıklama
`message`	string/null	Genel mesaj
`statusCode`	int	HTTP benzeri durum kodu (işlemsel)
`exceptions`	any	Hata ayrıntıları (varsa)
`data`	object	İşleme ait sonuçlar
`oldData`	any	Geriye dönük veri (varsa)
`errors`	any	Hata listesi (varsa)

`data` nesnesi

Alan	Tip	Açıklama
`redirectUrl`	string/null	3D’li akışta OTP için yönlendirme URL’si; 3D’siz akışta `null`
`referenceNumber`	string	Sistem referans numarası (ör. `NTH2P00000002248`)
`transactionStatusId`	int	İşlem durum kodu (bkz. “Durum Kodları”)
`errorMessage`	string/null	Banka/işlem hata mesajı (varsa)
`errorCode`	string/null	Banka/işlem hata kodu (varsa)
`isMembershipCompleted`	boolean	Üyelik/kayıt süreçleriyle ilişkili durum (varsa)
`currentAccountId`	string/null	İlişkili cari hesap kimliği (varsa)
`bonusText`	string/null	Bonus/puan bilgisi (varsa)
`memberId`	string (GUID)	Üye/müşteri kimliği
`transactionId`	string (GUID)	İşlem kimliği
`remainingErrorCount`	int/null	Kalan deneme sayısı (varsa)

Akışlar (Adım Adım)

3D’li Ödeme Akışı (`use3D: true`)

Ödeme İsteği (POST /pws/payment)

İstek geçerliyse yanıt data.redirectUrl ve referenceNumber ile döner; transactionStatusId tipik olarak 4: “3D doğrulama bekleniyor” durumundadır**.**
OTP Adımı (Bankanın 3D Sayfası)

Müşteri redirectUrl’e yönlendirilir ve OTP doğrulamasını bankanın sayfasında tamamlar. Banka sonucunu (başarılı/başarısız) ödeme sistemine iletir.
OtoCommit (Otomatik Tamamlama)
- OTP başarılı ise: İşlem başarıyla tamamlanır.
- OTP başarısız ise: İşlem başarısız olur**.**
Son Durumun Sorgulanması (Önerilir)

İşlem durumunu teyit etmek için /pws/payment/transaction veya iptal/iade gibi sonraki adımlar kullanılabilir.

3D’li Örnek İstek
3D’li Örnek Yanıt

**`POST https://pgw.netahsilatdemo.com/pws/payment`** 

{  
"contact": {  
  "name": "John",  
  "surname": "Doe",  
  "email": "[email protected]",  
  "tckn": "00000000000",  
  "description": "test",  
  "phone": "5000000000"  
},  
"card": {  
  "cardNumber": "4155650100416111",  
  "cardHolderName": "Test Test",  
  "cvv": "715",  
  "expMonth": 1,  
  "expYear": 2050  
},  
"agentCode": "NT53240185",  
"amount": 52,  
"installment": 1,  
"tenantPosId": "384badef-11ec-ee11-98f2-005056b0d2e5",  
"paymentSetDefinitionId": "504978bf-bebd-40c5-89aa-b76f3a20341c",  
"currencyCode": "TRY",  
"use3D": true,  
"returnUrl": "https://google.com",  
"clientOrderReferenceCode": "11001122010"  
}

{  
  "message": null,  
  "statusCode": 200,  
  "exceptions": null,  
  "data": {  
    "redirectUrl": "https://test_pgwapi.e-cozum.com/ThreeDForm/Pg3ds?token=b80fbf89-9264-49c2-bf85-38ad89dc1c6d",  
    "referenceNumber": "NTH2P00000002248",  
    "transactionStatusId": 4,  
    "errorMessage": null,  
    "errorCode": null,  
    "isMembershipCompleted": false,  
    "currentAccountId": null,  
    "bonusText": null,  
    "memberId": "00000000-0000-0000-0000-000000000000",  
    "transactionId": "f9f0d542-e5e7-433e-be73-84a5aa0d2c56",  
    "remainingErrorCount": null  
  },  
  "oldData": null,  
  "errors": null  
}

OTP Sonrası

OTP başarılı → sistem otoCommit yapar ve işlem tamamlanır.
OTP başarısız → işlem tamamlanamaz.

3D’siz Ödeme Akışı (`use3D: false`)

Ödeme İsteği (POST /pws/payment)

Banka provizyonu anında değerlendirilir. Başarılıysa işlem anında tamamlanır (redirectUrl = null).
OtoCommit (Anlık)

3D olmadığı için OTP yoktur; işlem banka yanıtına göre anında başarılı/başarısız final duruma geçer.
Son Durumun Sorgulanması (Opsiyonel/Önerilir)

İşlem teyidi/raporlama için /pws/payment/transaction kullanılabilir.

3D’siz Örnek İstek
3D’siz Örnek Yanıt

POST https://pgw.netahsilatdemo.com/pws/payment  

{  
  "contact": {  
    "name": "John",  
    "surname": "Doe",  
    "email": "[email protected]",  
    "tckn": "00000000000",  
    "description": "test",  
    "phone": "5000000000"  
  },  
  "card": {  
    "cardNumber": "4155650100416111",  
    "cardHolderName": "Test Test",  
    "cvv": "715",  
    "expMonth": 1,  
    "expYear": 2050  
  },  
  "agentCode": "NT53240185",  
  "amount": 53,  
  "installment": 1,  
  "tenantPosId": "384badef-11ec-ee11-98f2-005056b0d2e5",  
  "paymentSetDefinitionId": "504978bf-bebd-40c5-89aa-b76f3a20341c",  
  "currencyCode": "TRY",  
  "use3D": false,  
  "returnUrl": "https://google.com",  
  "clientOrderReferenceCode": "11001122011"  
}

{  
  "message": null,  
  "statusCode": 200,  
  "exceptions": null,  
  "data": {  
    "redirectUrl": null,  
    "referenceNumber": "NTH2P00000002249",  
    "transactionStatusId": 1,  
    "errorMessage": null,  
    "errorCode": null,  
    "isMembershipCompleted": false,  
    "currentAccountId": null,  
    "bonusText": null,  
    "memberId": "00000000-0000-0000-0000-000000000000",  
    "transactionId": "99248acb-3dbe-4654-9f3f-49f02111ee3e",  
    "remainingErrorCount": null  
  },  
  "oldData": null,  
  "errors": null  
}

Not: 3D’siz akışta OTP yoktur. transactionStatusId çoğunlukla 1 (Başarılı) döner; başarısız durumda uygun hata bilgileri (errorCode, errorMessage) ile dönebilir.

Durum Kodları (transactionStatusId) – Örnek Haritalama

Not: Gerçek/nihai değerler sistem kurulumuna göre değişebilir; aşağıdaki harita belgelendirme amaçlıdır.

Kod	Durum	Açıklama
1	Ödeme Başarılı	Provizyon + capture tamam
2	Ödeme Başarısız	Banka/işlemsel hata
3	Bekliyor / İşlemde	Asenkron/ara durum
4	3D Doğrulama Bekleniyor	`redirectUrl` döner, OTP sonucu beklenecek
5	İptal Edildi	Sonradan iptal
6	İade Edildi / Kısmi İade	Sonradan iade

### Notlar & En İyi Uygulamalar {#notes-and-best-practices}

3D (OTP) Akışı: use3D=true ise returnUrl mutlaka geçerli olmalı. OTP sonucu sistemce alınır ve otoCommit ile finalize edilir.
3D’siz Akış: OTP yoktur; banka yanıtına göre anında finalize olur.
Provizyonlu Ödeme: Ödeme Seti “Ödeme Tipi” Provizyon seçiliyse, ödeme işlemi provizyonlu olarak gerçekleşir.
POS/Set Senkronu: tenantPosId ve paymentSetDefinitionId, /pws/paymentOptions çıktılarıyla uyumlu olmalı (taksit/komisyon seçimi buradan belirlenir).
Idempotency: Aynı sipariş için birden fazla deneme yapma ihtimali varsa clientOrderReferenceCode benzersiz tutulmalı.
Taksit Kuralları: Kart programı/BIN’e göre taksit kısıtları olabilir; /pws/paymentOptions/{bin} ile önceden doğrulama önerilir.
Hata Yönetimi: errorCode + errorMessage alanları banka/işlem kaynaklı hataların kök nedenini verir. Retri politikalarını bu kodlara göre belirleyin.
Güvenlik: Kart verilerini sadece TLS 1.2+ üzerinden gönderin. PCI-DSS gereksinimlerine uyun; kart verisini log’lamayın.
Durum Sorgulama: İşlem sonucu kritik ise /pws/payment/transaction ile referans numarası üzerinden son durumu doğrulayın.
Sonraki Adımlar: Başarılı işlemler için iptal/iade gereksinimi olursa /pws/payment/cancel ve /pws/payment/refund uç noktalarını kullanın.

Açıklama​

Header Bilgileri​

Request Body​

Üst Düzey Alanlar​

Contact Alanı​

Card Alanı​

Response Yapısı​

Kök alanlar​

data nesnesi​

Akışlar (Adım Adım)​

3D’li Ödeme Akışı (use3D: true)​

3D’siz Ödeme Akışı (use3D: false)​

Durum Kodları (transactionStatusId) – Örnek Haritalama​