Payment Initiation and Completion

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

Description

This service initiates a card payment.

• 3D Payment: Returns redirectUrl for the bank OTP (3D Secure) step; the user completes OTP on the bank's page. Then the transaction is automatically finalized via autoCommit (success/failure).

• Non-3D Payment: If the bank-side authorization is successful, the transaction is completed immediately without OTP (autoCommit happens instantly); redirectUrl is not returned.

Important: The transactionStatusId field indicates the flow status (see “Status Codes” section).

Header Information

Header Name	Required	Description
Authorization	Yes	Valid token in Bearer {AccessToken} format.
Content-Type	No	application/json

Request Body

Top-Level Fields

Field	Type	Required	Description
agentCode	string	Yes	Transaction owner agent/sub-agent/customer code (mandatory per system rules)
amount	number	Yes	Transaction amount
installment	int	Yes	Number of installments (1 for single payment)
tenantPosId	string	Yes	Tenant ID of the POS to be used (GUID)
paymentSetDefinitionId	string	Yes	Payment set ID (GUID)
currencyCode	string	Yes	Currency (e.g., TRY)
use3D	boolean	Yes	Whether to use 3D Secure
returnUrl	string	Yes for 3D	Return URL after OTP completion in 3D flow
clientOrderReferenceCode	string	No	Merchant/app order reference (recommended for idempotency tracking)
contact	object	Yes	Cardholder contact information (below)
card	object	Yes	Card information (below)

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 (may be mandatory per local regulations)
description	string	No	Description
phone	string	No	Mobile number

card Field

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

Response Structure

Root Fields

Field	Type	Description
message	string/null	General message
statusCode	int	HTTP-like status code (transactional)
exceptions	any	Error details (if any)
data	object	Transaction result
oldData	any	Historical data (if any)
errors	any	List of errors (if any)

data Object

Field	Type	Description
redirectUrl	string/null	Redirect URL for OTP in 3D flow; null in non-3D flow
referenceNumber	string	System reference number (e.g., NTH2P00000002248)
transactionStatusId	int	Transaction status code (see “Status Codes”)
errorMessage	string/null	Bank/transaction error message (if any)
errorCode	string/null	Bank/transaction error code (if any)
isMembershipCompleted	boolean	Status related to membership/registration (if any)
currentAccountId	string/null	Related current account ID (if any)
bonusText	string/null	Bonus/points information (if any)
memberId	string (GUID)	Member/customer ID
transactionId	string (GUID)	Transaction ID
remainingErrorCount	int/null	Remaining retry count (if any)

Flows (Step by Step)

3D Payment Flow (use3D: true)

1. Payment Request (POST /pws/payment)

   If the request is valid, the response returns data.redirectUrl and referenceNumber; transactionStatusId is typically 4: “Waiting for 3D verification”.

2. OTP Step (Bank’s 3D Page)

   Customer is redirected to redirectUrl and completes OTP verification on the bank's page. Bank communicates the result (success/failure) to the payment system.

3. AutoCommit (Automatic Completion)

   • If OTP is successful: Transaction is successfully completed.
   • If OTP is unsuccessful: Transaction fails.

4. Query Final Status (Recommended)

   Confirm transaction status via /pws/payment/transaction or subsequent steps like cancel/refund.

3D Example Request

**`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"  
}

3D Example Response

{  
  "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  
}

Post-OTP

• OTP successful → system autoCommits and transaction is completed.
• OTP failed → transaction cannot be completed.

Non-3D Payment Flow (use3D: false)

1. Payment Request (POST /pws/payment)

   Bank authorization is evaluated instantly. If successful, transaction is completed immediately (redirectUrl = null).

2. AutoCommit (Instant)

   No OTP because 3D is not used; transaction immediately transitions to success/failure final status based on bank response.

3. Query Final Status (Optional/Recommended)

   Use /pws/payment/transaction for confirmation/reporting.

Non-3D Example Request

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"  
}

Non-3D Example Response

{  
  "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  
}

Note: In non-3D flow, there is no OTP. transactionStatusId mostly returns 1 (Success); in failure cases, appropriate error details (errorCode, errorMessage) may be returned.

Status Codes (transactionStatusId) – Example Mapping

Note: Actual/final values may vary depending on system setup; the mapping below is for documentation purposes.

Code	Status	Description
1	Payment Successful	Authorization + capture completed
2	Payment Failed	Bank/transaction error
3	Pending / In Progress	Asynchronous/intermediate state
4	Waiting for 3D Verification	redirectUrl returned, OTP result pending
5	Cancelled	Cancelled afterwards
6	Refunded / Partial Refund	Refunded afterwards

### Notes & Best Practices {#notes-and-best-practices}

• 3D (OTP) Flow: If use3D=true, returnUrl must be valid. OTP result is captured by the system and finalized via autoCommit.

• Non-3D Flow: No OTP; finalized immediately based on bank response.

• Authorized Payment: If Payment Set “Payment Type” is set to Authorization, the transaction occurs as authorized.

• POS/Set Sync: tenantPosId and paymentSetDefinitionId must align with /pws/paymentOptions outputs (installment/commission selection is determined here).

• Idempotency: If multiple attempts for the same order are possible, clientOrderReferenceCode should be unique.

• Installment Rules: There may be installment restrictions based on card program/BIN; pre-validation via /pws/paymentOptions/{bin} is recommended.

• Error Handling: errorCode + errorMessage fields provide root cause of bank/transaction errors. Retry policies should be based on these codes.

• Security: Send card data only over TLS 1.2+; comply with PCI-DSS; do not log card data.

• Status Query: If transaction outcome is critical, verify final status using /pws/payment/transaction via reference number.

• Next Steps: For successful transactions requiring cancel/refund, use /pws/payment/cancel and /pws/payment/refund endpoints.