Bayi Ödeme Başlatma ve Tamamlama

• Endpoint: /vpws/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, bayiye ait POS üzerinden kartlı ödeme işlemini başlatır.

Servis

• 3D'li (OTP doğrulamalı)
• 3D'siz (OTP doğrulama olmadan doğrudan)

ödeme akışlarını destekler.

VPWS kapsamında işlem, firma adına değil, AccessToken'a bağlı bayi kimliği altında gerçekleştirilir.

Not: Bayi yalnızca kendisine tanımlı tenantPosId değerleri ile işlem başlatabilir.

Header Bilgileri

Header Adı	Zorunlu	Açıklama
Authorization	Evet	Bearer {AccessToken}
Content-Type	Evet	application/json

Request Body

Üst Düzey Alanlar

Alan	Tip	Zorunlu	Açıklama
amount	number	Evet	İşlem tutarı
installment	int	Evet	Taksit sayısı (tek çekim için 1)
tenantPosId	string (GUID)	Evet	Kullanılacak POS kimliği
currencyCode	string	Evet	ISO 4217 para birimi kodu
use3D	boolean	Evet	3D Secure kullanılsın mı
returnUrl	string	3D'de Evet	OTP sonrası yönlendirme adresi
clientOrderReferenceCode	string	Hayır	Bayi sipariş referansı (idempotency önerilir)
contact	object	Evet	Kart sahibi bilgileri
card	object	Evet	Kart bilgileri

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 (regülasyona bağlı)
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)

Örnek Request

{
  "contact": {
    "name": "test",
    "surname": "soyadı",
    "email": "[email protected]",
    "tckn": "23671373136",
    "description": "est",
    "phone": "5002583519"
  },
  "card": {
    "cardNumber": "4155650100416111",
    "cardHolderName": "Emre Çağlar",
    "cvv": "000",
    "expMonth": 12,
    "expYear": 2030
  },
  "amount": 250,
  "installment": 1,
  "tenantPosId": "03cbbf3e-ff9e-ee11-98ef-005056b0d2e5",
  "currencyCode": "TRY",
  "use3D": true,
  "clientOrderReferenceCode": "46548545646565",
  "returnUrl": "https://google.com"
}

Örnek Response

{
  "message": null,
  "statusCode": 200,
  "exceptions": null,
  "data": {
    "redirectUrl": "https://...",
    "referenceNumber": "NTH2V00000000001",
    "transactionStatusId": 4,
    "errorMessage": null,
    "errorCode": null,
    "transactionId": "guid"
  },
  "oldData": null,
  "errors": null
}

Response Yapısı

Data Alanları

Alan	Tip	Açıklama
redirectUrl	string/null	3D'li akışta OTP sayfası URL'si
referenceNumber	string	Sistem referans numarası
transactionStatusId	int	İşlem durum kodu
errorMessage	string/null	Hata mesajı
errorCode	string/null	Hata kodu
transactionId	string (GUID)	İşlem kimliği

Akış Senaryoları

3D'li Ödeme (use3D: true)

1. /vpws/payment çağrılır.
2. redirectUrl döner.
3. Kullanıcı bankanın OTP sayfasına yönlenir.
4. OTP sonucu sisteme iletilir.
5. İşlem otomatik finalize edilir (AutoCommit).

3D'siz Ödeme (use3D: false)

1. Banka provizyonu anında alınır.
2. redirectUrl = null döner.
3. İşlem anında final duruma geçer.

Durum Kodları (transactionStatusId)

Kod	Açıklama
1	Başarılı
2	Başarısız
3	İşlemde / Beklemede

Örnek cURL

curl --location 'https://pgw.netahsilatdemo.com/vpws/payment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {AccessToken}' \
--data '{ ... }'

Notlar & En İyi Uygulamalar

• Bayi yalnızca kendisine tanımlı tenantPosId ile işlem yapabilir.

• 3D akışında returnUrl zorunludur.

• Idempotency için clientOrderReferenceCode benzersiz olmalıdır.

• Kart verileri loglanmamalıdır (PCI-DSS).

• İşlem sonucu kritik ise 3.4 – İşlem Sorgulama servisi ile doğrulama yapılmalıdır.

• BIN bazlı doğrulama (3.2) ödeme öncesi önerilir.