Payment with Points

CONNECTION ADDRESSES

Real Environment

It will also be forwarded.

Test Environment

https://testposws.param.com.tr/turkpos.ws/service_turkpos_prod.asmx

Test Parameter Value
CLIENT_CODE 10738
CLIENT_USERNAME Test
CLIENT_PASSWORD Test
GUID 0c13d406-873b-403b-9c09-a5766840d98c


  • Payment with Points
  • Transaction Inquiry
  • Transaction Cancellation/Refund Partial
Method Name: TP_WMD_UCD_WP

It is used to collect with points. This method supports both 3D and NS transactions. Islem_Guvenlik_Tip parameter takes the value 3D to start a 3D operation and NS to start a Nonsecure operation.

⚠ Important Information

For Nonsecure Transactions
  1. Points = 0 (Credit Card transaction without points, normal sales transaction)Toplam_Tutar value of TL is spent from the credit card. Any points no expenditure is incurred.
    Example: The basket amount is 5,58 TL and 5,58 TL of this amount is spent from the credit card. Credit There will be no additional spending of points from the card.
  2. Points = Toplam_Tutar (Collect using full points) The entire Toplam_Tutar value is debited from the credit card as points. Toplam_Tutar and Points parameter values must be equal.
    Example: Basket amount is 5.58 TL and the entire amount of 5.58 TL is collected as points If you want to buy a credit card, your credit card will spend 5.58 TL in points. From the credit card There will also be no TL expenditure.
  3. Points < Toplam_Tutar (Mixed transaction, points and credit card collection) TL is spent from the credit card by subtracting the Points value from the Toplam_Tutar value. Credit If the card TL redemption process is unsuccessful, no points will be redeemed. Credit card TL credit card redemption process if redemption process is successful and points redemption process is unsuccessful is canceled.
    Example: Basket amount is 5.58 TL and 1.42 TL of this amount is collected as points if desired, spending TL on your credit card is 4.16 TL, spending points on your credit card is 1.42 TL will be.
For 3D Transactions
  1. Points = 0 (Credit Card transaction without points, normal sales transaction) 3D verification to spend TL from credit card up to the value of Toplam_Tutar screen. If 3D verification is successful, TL is spent from the credit card. No points are spent.
    Example: The basket amount is 5,58 TL and 5,58 TL of this amount is spent from the credit card. Credit There will be no additional spending of points from the card.
  2. Points = Toplam_Tutar (Collect using full points) 3D verification to withdraw the entire Toplam_Tutar value from the credit card as points screen. If 3D verification is successful, points are spent from the credit card. TL is not spent from the credit card separately. Toplam_Tutar and Points parameter values must be equal.
    Example: Basket amount is 5.58 TL and the entire amount of 5.58 TL is collected as points If you want to buy a credit card, your credit card will spend 5.58 TL in points. From the credit card There will also be no TL expenditure.
  3. Points < Toplam_Tutar (Mixed transaction, points and credit card collection) To spend TL from the credit card by subtracting the Points value from the Toplam_Tutar value You will be directed to the 3D verification screen. Credit card TL spending if 3D verification is successful transaction is made. If the credit card TL spending process is unsuccessful, Credit card point spending transaction is not made. Credit card TL redemption successful and points redemption unsuccessful the credit card spending transaction is canceled.
    Example: Basket amount is 5.58 TL and 1.42 TL of this amount is collected as points if desired, spending TL on your credit card is 4.16 TL, spending points on your credit card is 1.42 TL will be.

Parameter Required Type Length Description
G Yes Object - ST_WS_Security Object
GUID Yes String 36 Main Key of the Merchant
KK_Sahibi Yes String 100 Credit Card Owner
KK_No Yes String 16 Credit Card Number
KK_SK_Ay Yes String 2 2-digit Expiry Month
KK_SK_Yil Yes String 4 4-digit Expiry Year
KK_CVC Yes String 3 CVC Code
KK_Sahibi_GSM No String 10 Credit Card Owner GSM No, without leading 0 (5xxxxxxxxx)
Hata_URL Yes String 256 URL to redirect in case of payment failure. For Islem_Guvenlik_Tip = "NS", this field can be left blank.
Basarili_URL Yes String 256 URL to redirect in case of successful payment. For Islem_Guvenlik_Tip = "NS", this field can be left blank.
Siparis_ID Yes String 50 Unique ID specific to the order. If you have sent this value before, the system assigns a new Siparis_ID. After the transaction, this Siparis_ID is returned.
Siparis_Aciklama No String 250 Description of the order
Taksit Yes Integer 2 Number of Installments. Send 1 for single payment.
Islem_Tutar Yes String - Order Amount, (only in comma decimal format like 1000.50)
Toplam_Tutar Yes String - Total Order Amount Including Commission, (only in comma decimal format like 1000.50)
Islem_Hash Yes String - Transaction Hash Value ( https://dev.param.com.tr/tr/hash-calculation You can find details according to the method name at the address.)
Islem_Guvenlik_Tip Yes String 2 3D or NS (Nonsecure)
Islem_ID No String - Unique ID other than Siparis_ID related to the transaction optional.
IPAdr Yes String 50 IP Address
Ref_URL No String 256 URL of the page where the payment is made
Data1 No String 250 Extra Field 1
Data2 No String 250 Extra Field 2
Data3 No String 250 Extra Field 3
Data4 No String 250 Extra Field 4
Data5 No String 250 Extra Field 5
Puan Yes String - Amount of points to be used, (only in comma decimal format like 1000.50)
Pos_ID No String - POS_ID value where the transaction will take place. Send "0" for default value.
Islem_Tip Yes String - For sales transactions, use the value SALE.
Parameter Type Length Description
Sonuc Integer - Transaction result
Sonuc_Str String - Transaction result description
Islem_ID Long - SID Value
Islem_GUID String - Transaction GUID value
UCD_HTML String - 3D HTML code
UCD_MD String - 3D MD value
Bank_Trans_ID String - Bank Transaction ID value
Bank_AuthCode String - Bank Auth Code value
Bank_HostMsg String - Bank HostMsg value
Banka_Sonuc_Kod Integer - Code returned by the bank
Bank_Extra String - Bank Extra value
Bank_HostRefNum String - Bank RRN value
Siparis_ID String - Siparis_ID value sent in the request

For NonSecure Transactions
If Sonuc > 0, UCD_HTML is checked for equality to 'NONSECURE'. If equal, the transaction ends. Islem_ID value represents the Receipt Number. For a successful NonSecure transaction, Sonuc > 0, Islem_ID > 0, and UCD_HTML='NONSECURE' must be true. Otherwise, the transaction fails. If a NONSECURE transaction fails, Sonuc_Str returns the error message from the bank.

For 3D Transactions
When you display UCD_HTML content, the Bank's 3D screen will appear. After 3D verification, Basarili_URL or Hata_URL pages will be posted with the following parameters.

Parameter Type Length Description
md String - MD value to be sent to UCD_MD parameter of TP_WMD_Pay method
mdStatus Integer 1 3D Verification Result. 1: Successful - In other cases, 3D verification fails.
orderId String - Order ID value sent to TP_WMD_UCD_WP method
transactionAmount String - Transaction Amount sent to TP_WMD_UCD_WP method
islemGUID String - Transaction GUID value returned from TP_WMD_UCD_WP method
islemHash String - Transaction Hash value returned from TP_WMD_UCD_WP method

Hash Check
The following steps should be applied to perform parameter validation.

Parameters creating the hash value
transactionGUID + md + mdStatus + orderId + GUID (key should be lowercase)

The hash value is encoded as base64. (SHA1)

Sample code
Dim _sha As SHA1 = New SHA1CryptoServiceProvider()
Dim _bytes() As Byte = System.Text.Encoding.UTF8.GetBytes(transactionGUID + md + mdStatus + orderId + GUID)
Dim _hashingbytes() As Byte = _sha.ComputeHash(_bytes)
Dim _hash As String = Convert.ToBase64String(_hashingbytes)

The hash value you generate must match the posted transactionHash value.

mdStatus Values

1 = Verified Transaction (Full 3D)
2, 3, 4 = Card not enrolled (Half 3D)
5, 6, 7, 8 = No valid verification or system error
0 = Verification Failed

mdStatus : 1, 2, 3, 4, you can send a request to the TP_WMD_Pay method to complete the payment.
3D verification failed if mdStatus : 0,5,6,7,8. Do not send a request to the TP_WMD_Pay method.

Completing the Sales Transaction (for 3D Transactions)
Method Name: TP_WMD_Pay

This method is used to debit the amount from the verified cards.

Parameter Required Type Length Description
G Yes Object - ST_WS_Security Object
GUID Yes String 36 Merchant Key
UCD_MD Yes String - Bank 3D MD value
Islem_GUID Yes String 36 Transaction GUID value
Siparis_ID Yes String - Order ID value
Parametre Type Length Description
Sonuc Integer - Transaction result
Sonuc_Ack String 36 Transaction result description
Dekont_ID String 36 Transaction receipt ID
Siparis_ID String - Order ID value
UCD_MD String - Bank 3D MD Value
Bank_Trans_ID String - Bank Transaction ID value
Bank_AuthCode String - Bank Auth Code value
Bank_HostMsg String - Bank HostMsg value
Bank_Extra String - Bank Extra value
Bank_Sonuc_Kod Integer - Bank Result Code value
Bank_HostRefNum String - Bank RRN value
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<TP_WMD_Pay xmlns="https://turkpos.com.tr/">
<G>
<CLIENT_CODE>10738</CLIENT_CODE>
<CLIENT_USERNAME>test</CLIENT_USERNAME>
<CLIENT_PASSWORD>test</CLIENT_PASSWORD>
</G>
<GUID>0c13d406-873b-403b-9c09-a5766840d98c</GUID>
<UCD_MD>TP_WMD_UCD' den dönen değer.</UCD_MD>
<Islem_GUID>TP_WMD_UCD_WP' den dönen değer.</Islem_GUID>
<Siparis_ID>TP_WMD_UCD_WP' de kullanılan Siparis_ID değeri</Siparis_ID>
</TP_WMD_Pay>
</soap:Body>
</soap:Envelope>
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<TP_WMD_PayResponse xmlns="https://turkpos.com.tr/">
<TP_WMD_PayResult>
<Sonuc>1</Sonuc>
<Sonuc_Ack>Başarılı</Sonuc_Ack>
<Dekont_ID>3003884577</Dekont_ID>
<Siparis_ID>testdokumani001</Siparis_ID>
<UCD_MD>1000000089300991</UCD_MD>
<Bank_Trans_ID>62802134</Bank_Trans_ID>
<Bank_AuthCode>S84698</Bank_AuthCode>
<Bank_HostMsg>Success</Bank_HostMsg>
<Bank_Extra>KazanilanPuan:|KazanilanPuanTLTutar:</Bank_Extra>
<Bank_Sonuc_Kod>0</Bank_Sonuc_Kod>
<Bank_HostRefNum>313711117493</Bank_HostRefNum>
<Komisyon_Oran>1.75</Komisyon_Oran>
</TP_WMD_PayResult>
</TP_WMD_PayResponse>
</soap:Body>
</soap:Envelope>

If Sonuc > 0 and Dekont_ID > 0, the transaction is successful. Otherwise the transaction is a failure.

Method Name: TP_Islem_Sorgulama_WP

It is used to query the transactions made with TP_WMD_UCD_WP method.

Parameter Required Type Length Description
G Yes Object - ST_WS_Security Object
GUID Yes String 36 Merchant Key
Dekont_ID No String - Dekont_ID value, optional
Siparis_ID No String 36 Order_ID value sent in TP_WMD_UCD_WP method.
Islem_ID No String 16 Islem_ID value, optional
Ref_No No String - Partial refund transactions can be queried using Ref_No value.
Parameter Type Length Description
Sonuc Integer - Transaction result
Sonuc_Str String - Transaction result description
Islem_ID Long - SID Value
Siparis_ID String - Order_ID value sent in the request
List Object - CL_WP: Transaction Details

CL_WP Object:

TP_Islem_Sorgulama_WP refers to the List type in the method return.

Parameter Type Length Description
Dekont_ID String - Dekont_ID value
Islem_Tip String - Transaction Type SALE - PRE_AUTH - POST_AUTH
Durum String - Transaction Status SUCCESS - PARTIAL_REFUND - FAIL - BANK_FAIL - CANCEL - REFUND
Tarih String - Transaction Date
Tutar Money - Transaction Amount
Komisyon_Oran Money - Transaction commission rate
Komisyon_Tutar Money - Transaction commission amount
Iade_Tutar Money - Total refunded amount
Iade_Edilebilir_Tutar Money - Remaining refundable amount
Banka_Sonuc_Aciklama String - Bank result description value
Taksit String - Installment value
Ext_Data String - Concatenated form of Data1, Data2, Data3, Data4, Data5 fields in the payment method with "|".
KK_No String - Masked credit card number value for the transaction
Bank_Extra String - Bank Extra value
Bank_HostRefNum String - Bank HostRefNum value
Bank_Trans_ID String - Bank Trans_ID value
Bank_AuthCode String - Bank AuthCode value
Method Name: TP_Islem_Iptal_Iade_Kismi_WP

It is used when canceling and refunding transactions made with the TP_WMD_UCD_WP method. Partial Refunds a pro-rata refund is made.

Parameter Required Type Length Description
G Yes Object - ST_WS_Security Object
GUID Yes String 36 Merchant Key
Durum Yes String - Cancellation or Refund
Siparis_ID No String 36 Order_ID value sent in TP_WMD_UCD_WP method.
Tutar Yes Money - Amount to be cancelled or refunded
Ref_No No String - This value is optional. When multiple partial refund records are sent with the same Ref_No, it ensures that no additional refund is made for that ref no if there is already a successful partial refund entry. If sent as empty, it won't check if partial refund has been made previously.
Parameter Type Length Description
Sonuc Integer - Transaction result
Sonuc_Str String - Transaction result description
Siparis_ID String - Order_ID value sent in the request
List Object - CL_WP_II: Transaction Details

CL_WP_II Object:

TP_Islem_Iptal_Iade_Kismi_WP refers to the List type in the method return.

Parameter Type Length Description
Sonuc Integer - Transaction result
Sonuc_Str String - Transaction result description
Banka_Sonuc_Kod Integer - Result code returned from the bank
Islem_Tip String - Accepts POINT (points) or SALE (sale) values.
Bank_Extra String - Bank extra value
Bank_HostRefNum String - Bank HostRefNum value
Bank_Trans_ID String - Bank Trans_ID value
Bank_AuthCode String - Bank AuthCode value