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

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.
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.
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

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.
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.
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>

<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