Dealer Payment Initiation and Completion

• Endpoint: /vpws/payment
• HTTP Method: POST
• Request Content-Type: application/json
• Response Content-Type: application/json
• Authorization: Valid AccessToken required.
  (See: 2. Authentication – Obtaining AccessToken)

Description

This service initiates a card payment through the POS assigned to the dealer.

The service supports

• 3D (OTP verification)
• Non-3D (direct, without OTP verification)

payment flows.

Within VPWS scope, the transaction is performed under the dealer identity linked to the AccessToken, not on behalf of the company.

Note: A dealer can only initiate transactions with tenantPosId values assigned to them.

Header Information

Header Name	Required	Description
Authorization	Yes	Bearer {AccessToken}
Content-Type	Yes	application/json

Request Body

Top-Level Fields

Field	Type	Required	Description
amount	number	Yes	Transaction amount
installment	int	Yes	Number of installments (use 1 for single payment)
tenantPosId	string (GUID)	Yes	POS identifier to be used
currencyCode	string	Yes	ISO 4217 currency code
use3D	boolean	Yes	Whether to use 3D Secure
returnUrl	string	Yes for 3D	Redirect URL after OTP
clientOrderReferenceCode	string	No	Dealer order reference (idempotency recommended)
contact	object	Yes	Cardholder information
card	object	Yes	Card information

contact Field

Field	Type	Required	Description
name	string	Yes	First name
surname	string	Yes	Last name
email	string	Yes	Email
tckn	string	No	National ID (regulation dependent)
description	string	No	Description
phone	string	No	Mobile phone

card Field

Field	Type	Required	Description
cardNumber	string	Yes	Card number (PAN)
cardHolderName	string	Yes	Name on card
cvv	string	Yes	Security code
expMonth	int	Yes	Expiration month (1–12)
expYear	int	Yes	Expiration year (YYYY)

Example Request

{
  "contact": {
    "name": "test",
    "surname": "surname",
    "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"
}

Example 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 Structure

data Fields

Field	Type	Description
redirectUrl	string/null	OTP page URL for 3D flow
referenceNumber	string	System reference number
transactionStatusId	int	Transaction status code
errorMessage	string/null	Error message
errorCode	string/null	Error code
transactionId	string (GUID)	Transaction identifier

Flow Scenarios

3D Payment (use3D: true)

1. /vpws/payment is called.
2. redirectUrl is returned.
3. User is redirected to bank's OTP page.
4. OTP result is sent to the system.
5. Transaction is automatically finalized (AutoCommit).

Non-3D Payment (use3D: false)

1. Bank provision is obtained immediately.
2. redirectUrl = null is returned.
3. Transaction immediately enters final state.

Status Codes (transactionStatusId)

Code	Description
1	Successful
2	Failed
3	Processing / Pending

Example cURL

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

Notes & Best Practices

• A dealer can only transact with tenantPosId assigned to them.

• In 3D flow, returnUrl is required.

• For idempotency, clientOrderReferenceCode should be unique.

• Card data must not be logged (PCI-DSS).

• If the transaction result is critical, verification should be done with the 3.4 – Transaction Query service.

• BIN-based validation (3.2) is recommended before payment.