Introduction

Intended Audience

This overview document is written for technical people with a background in payments services; and implementing online payment functionality to the e-commerce sites and/or internal. ERP systems using ZiraatPay.

How to Contact Customer Support

For problems with transaction processing or your connection to the server, please contact Customer Support via phone +90 212 3190647 or info(at)ZiraatPay.com.tr email.

What is ZiraatPay?

ZiraatPay is an online payment solution developed by ZiraatPay Turkey. It offers a secure, easy and convenient checkout experience for both, customers and merchants. While Customers (Card Holders) enjoy the secure e-wallet and flexible payment features on check out pages; the Merchants are handling the payment without touching the credit card data so they remain PCI DSS compliant; and therefore eliminate the risks around fraud & secure storage of financially sensitive data.

Security

ZiraatPay is built on a robust and secure communication protocol. ZiraatPay API is a set of instructions submitted with standard HTTPS Post requests. At the server end, we use a certificate delivered by Verisign. The SSL encryption guarantees that it is our servers you are communicating with and that your data is transmitted in encrypted form. There is no need for a client SSL certificate. When we receive a request, we check the level of encryption. Directly TLSv1.1 version and next version is supported.

Supported Languages

The API supports all platforms & languages that can implement HTTP Post methods.

Response Parsing

ZiraatPay responses by default will be in form of JSON format. You can use any JSON parsing tool or framework to process ZiraatPay responses.

Test Environment

An API test environment is available and all API action types given in this document can be tested using by ZiraatPay API Test URL. All API requests should be sent to this URL address using HTTP POST method.

					https://test.ziraatpay.com.tr/ziraatpay/api/v2
				

Integration Environment

An API integration environment is available and all API action types given in this document can be tested using by ZiraatPay API Test URL. All API requests should be sent to this URL address using HTTP POST method.

					https://entegrasyon.ziraatpay.com.tr/ziraatpay/api/v2
				

Request & Response

ZiraatPay API Requests

A request to the ZiraatPay API is made a by sending a POST HTTP request to ZiraatPay API Endpoint URL. Each HTTP POST request send to the API URI should have a set of parameter-value pairs encoded in it, depending of the type of request being sent.

ZiraatPay API Responses

The ZiraatPay API response supports JSON data format. Each response, regardless of the success of the action, will return the RESPONSECODE and RESPONSEMSG parameters. Depending on the successfulness of the action the RESPONSECODE and RESPONSEMSG can have the specific value pairs. If an error has occurred and the API call is considered to be failed (RESPONSE is not equal to 00) the ERROR and ERRORCODE parameters will be present in the response.

Pagination

TO BE PROVIDED

Authentication

You authenticate to the API by providing your user information (secure credentials) in the request. You can manage your API user information from your account or by requesting related change from support team. Every API user have its own e-mail and password information. Your user e-mail and password pair carries many privileges, so be sure to keep them secret!

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate properly for all requests.

					MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT]

				

How to integrate?

Hosted Page (HP)

This model requires the merchants to use ZiraatPay's payment page hosted in Asseco environment. It is based on one way communication of the ‘transaction result’ to the Merchant system occurring at Step 4. HPP model simply assumes that the Merchant site has received the transmitted information and updated its own records accordingly. It has the following steps:

Step 1:

The Merchant Web Site makes a sale request by specifying the integration model as HPP. Order/Billing/Shipping details can also be passed at this stage to be displayed on ZiraatPay payment page for Customer’s information only.

Step 2:

The payment request is processed, a session token is created and sent back to the merchant site. Merchant Web Site receives the token and redirects Customer’s Browser to ZiraatPay Payment Pages with the given session token.

Step 3:

If there is any saved card detail for the Customer, his/her e-wallet is displayed for quick payment. If not, new card entry screen is displayed. Customer clicks on ‘pay’ button after entering/selecting the card to be used in payment. ZiraatPay processes the payment accordingly.

Step 4:

ZiraatPay redirects the Customer Browser to Merchant Web Site and also returns the transaction result.

Please note that Step 4 is a browser based HTTP re-direction and it all happens in customer's environment in which Asseco has no control over. There might be cases like where the customer may close the browser screen or internet connection may cuts off during this re-direction etc. Therefore merchants using this model should not completely rely on redirection process to obtain information about the payment result. They should use additional api calls to check the status of the payment. These details are available in API Model Integration document.

Direct POST - MOTO

This integration model is based on the scenario that the Payment Page is being hosted by Merchants but its form action is Direct Post to ZiraatPay so that any financially sensitive data will be collected still at the convenience of a merchant hosted page but to be fully compatible with PCI DSS. This will overcome the shortage of the API integration model for the merchants willing 100% compliance with PCI DSS without any additional effort on their side. Please see the flow below for details.

Step 1:

The Merchant Core System makes a Session Token request in order to get a valid key value for defining the session.

Step 2:

This session token request is processed; a session token is created and sent back to the merchant system in the API response.

Step 3:

Merchant system serves the payment page using the given secure session token.

Extra Point Step:

In Direct Post model merchant need to do a query points with SESSIONTOKEN, CARDPAN,CARDEXPIRY parameters. According to QUERYPOINTS response sample form points input should be set as sale by points samples. And to send the payment to related payment system, merchant needs to send payment system name as paymentSystem input parameter at sample form. Payment system name can be get via QUERYPAYMENTSYSTEMS with SESSIONTOKEN and BIN.

Step 4:

Cardholder interacts with the page and clicks on Confirm button. Merchant system submits all information received via this page to ZiraatPay system.

Step 5:

ZiraatPay processes the payment details via an invisible interim page.

Step 6:

ZiraatPay forwards the payment to the relevant VPOS, receives the result and redirect the cardholder back to merchant return url. The merchant is expected to listen and parse the payment result within the posted form.

Direct Post (MOTO) Test Form

<!DOCTYPE html> <html> <head> <title>Sample POST Form</title> <meta charset="utf-8"> <script> function hideCardPANData() { if (document .getElementById('isPayWithCardToken').checked) { document.getElementById('cardPANData').style.display = 'none'; document .getElementById('cardTokenContainer').style.display = 'block'; } else { document .getElementById('cardTokenContainer').style.display = 'none'; document.getElementById('cardPANData').style.display = 'block'; } } </script> <style type="text/css"> form { display: table; } p { display: table-row; } label { display: table-cell; } input { display: table-cell; } </style> </head> <body onload="hideCardPANData();"> <form action="https://vpos.ziraatpay.com.tr/merchant/post/sale/[SECURE_SESSION_TOKEN]" method="post"> <div> <label for="isPayWithCardToken">Pay with Card Token</label> <input type="checkbox" onclick="hideCardPANData();" name="isPayWithCardToken" id="isPayWithCardToken" autocomplete="off" maxlength="32" /> </div> <div class="container"> <div id="cardPANData"> <p> <label for="cardOwner">Card Owner Name</label> <input type="text" name="cardOwner" id="cardOwner" autocomplete="off" maxlength="32" /> </p> <p> <label for="pan">Card Number (PAN) </label> <input type="text" id="pan" name="pan" autocomplete="off" maxlength="19" /> </p> <p> <label for="expiryMonth">Expiration Date</label> <select name="expiryMonth" id="expiryMonth"> <option value="01">January</option> <option value="02">February</option> <option value="03">March</option> <option value="04">April</option> <option value="05">May</option> <option value="06">June</option> <option value="07">July</option> <option value="08">August</option> <option value="09">September</option> <option value="10">October</option> <option value="11">November</option> <option value="12">December</option> </select> <select name="expiryYear" id="expiryYear"> <option value="2016">2016</option> <option value="2017">2017</option> <option value="2018">2018</option> <option value="2019">2019</option> <option value="2020">2020</option> <option value="2021">2021</option> <option value="2022">2022</option> <option value="2023">2023</option> <option value="2024">2024</option> <option value="2025">2025</option> <option value="2026">2026</option> <option value="2027">2027</option> <option value="2028">2028</option> <option value="2029">2029</option> <option value="2030">2030</option> <option value="2031">2031</option> <option value="2032">2032</option> <option value="2033">2033</option> <option value="2034">2034</option> </select> </p> <p> <label for="cvv">Security Code (CVV)</label> <input type="input" name="cvv" id="cvv" autocomplete="off" maxlength="4" /> </p> <p> <label for="saveCard">Save Card</label> <input type="checkbox" name="saveCard" id="saveCard" value="YES" /> </p> <p> <label for="cardName">Card Name</label> <input type="text" name="cardName" id="cardName" /> </p> <p> <label for="installmentCount">Installment Count</label> <input type="text" name="installmentCount" id="installmentCount" /> </p> <input type="hidden" value="" name="points" id="points" /> <input type="hidden" value="" name="paymentSystem" id="paymentSystem" /> </div> <div id="cardTokenContainer"> <p> <label for="cardToken">>Card Token</label> <input type="text" name="cardToken" id="cardToken" autocomplete="off" maxlength="64" /> </p> <p> <label for="installmentCount">Installment Count</label> <input type="text" name="installmentCount" id="installmentCount" /> </p> </div> <input type="submit" value="Submit" /> </form> <script type="text/javascript" src="https://ZIRAATPAY_HOST/ziraatpay/static/external/whitewolf-v3.js"></script> <script type="text/javascript"> whitewolf.run(h.online-metrix.net, ORG_ID, SESSIONTOKEN); </script> <noscript> <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="https://h.online-metrix.net/tags?org_id=ORG_ID&session_id=UNIQUE_SESSION_ID&pageid=PAGEID"> </iframe> </noscript> </body> </html>

					
merchantPaymentId: PaymentId-FbnzDdx04fZu
apiMerchantId: 700100000
paymentSystem: My İşbank VPOS Account (Test)
paymentSystemType: ISBANK
paymentSystemEftCode: 0064
pgTranDate: 20170113 12:20:35
pgTranId: 17013MUjC07014059
pgTranRefId: 701300002882
pgTranApprCode: 733185
pgOrderId: PaymentId-FbnzDdx04fZu
sessionToken: FOEMQGVTVWOQCJRSS6DARRRV62RQK2FIKUY7ZMXKBNX6SOUJ
random: -349886350
customerId: Customer-QjOnxH8Z
SD_SHA512: bff497614a8767e3176fede4f3f8274225a8f619469a1c5eafe2e785fbc438aeb5345c51be30d976d53db5b73adf026347db1144c52cbc2133364aa13e933d45
sdSha512: 7f1485a24f1790e0791fe9de5ec33d4e98057578f77a4c39fdd4bd874079d6e3af9271da020c57ed8acd7642ec801ad80dae0c574462a58a6722fbfa361a0b65
responseCode: 00
responseMsg: Approved
                      
				

Direct POST - 3D Secure

This integration model is based on the scenario that the Payment Page is being hosted by Merchants but its form action is Direct Post to ZiraatPay so that any financially sensitive data will be collected still at the convenience of a merchant hosted page but to be fully compatible with PCI DSS. This will overcome the shortage of the API integration model for the merchants willing 100% compliance with PCI DSS without any additional effort on their side. Please see the flow below for details.

Step 1:

The Merchant Core System makes a Session Token request in order to get a valid key value for defining the session.

Step 2:

The payment session request is processed; a session token is created and sent back to the merchant system in the API response.

Step 3:

Merchant system serves the payment & wallet page using the given secure session token.

Extra Point Step:

In Direct Post model merchant need to do a query points with SESSIONTOKEN, CARDPAN,CARDEXPIRY parameters. According to QUERYPOINTS response sample form points input should be set as sale by points samples. And to send the payment to related payment system, merchant needs to send payment system name as paymentSystem input parameter at sample form. Payment system name can be get via QUERYPAYMENTSYSTEMS with SESSIONTOKEN and BIN.

Step 4:

Cardholder interacts with the page and clicks on Confirm button. Merchant system submits all information received via this page to ZiraatPay system.

Step 5:

ZiraatPay processes the payment details (and optionally starts 3D authentication process on behalf of the merchant) via an invisible interim page.

Step 6:

ZiraatPay performs MOTO sale (or optionally directs the cardholder to 3D authentication servers).

Step 7:

ACS server serves the 3D authentication page where the cardholder enters a dynamic code sent to his/her mobile phone.

Step 8:

ACS server authenticates the user and returns back to ZiraatPay invisible interim page. * Depending on authentication response, the transaction sent to bank either with full 3D details (if 3D authentication is done successfully) or as MOTO payment (if 3D authentication has failed).

Step 9:

ZiraatPay make return the response to merchant return url

Direct POST (3D Secure) Test Form

<!DOCTYPE html> <html> <head> <title>Sample POST Form</title> <meta charset="utf-8"> <script> function hideCardPANData() { if (document .getElementById('isPayWithCardToken').checked) { document.getElementById('cardPANData').style.display = 'none'; document .getElementById('cardTokenContainer').style.display = 'block'; } else { document .getElementById('cardTokenContainer').style.display = 'none'; document.getElementById('cardPANData').style.display = 'block'; } } </script> <style type="text/css"> form { display: table; } p { display: table-row; } label { display: table-cell; } input { display: table-cell; } </style> </head> <body onload="hideCardPANData();"> <form action="https://vpos.ziraatpay.com.tr/ziraatpay/api/v2/post/sale3d/[SECURE_SESSION_TOKEN]" method="post"> <div> <label for="isPayWithCardToken">Pay with Card Token</label> <input type="checkbox" onclick="hideCardPANData();" name="isPayWithCardToken" id="isPayWithCardToken" autocomplete="off" maxlength="32" /> </div> <div class="container"> <div id="cardPANData"> <p> <label for="cardOwner">Card Owner Name</label> <input type="text" name="cardOwner" id="cardOwner" autocomplete="off" maxlength="32" /> </p> <p> <label for="pan">Card Number (PAN)</label> <input type="text" id="pan" name="pan" autocomplete="off" maxlength="19" /> </p> <p> <label for="expiryMonth">Expiration Date</label> <select name="expiryMonth" id="expiryMonth"> <option value="01">January</option> <option value="02">February</option> <option value="03">March</option> <option value="04">April</option> <option value="05">May</option> <option value="06">June</option> <option value="07">July</option> <option value="08">August</option> <option value="09">September</option> <option value="10">October</option> <option value="11">November</option> <option value="12">December</option> </select> <select name="expiryYear" id="expiryYear"> <option value="2016">2016</option> <option value="2017">2017</option> <option value="2018">2018</option> <option value="2019">2019</option> <option value="2020">2020</option> <option value="2021">2021</option> <option value="2022">2022</option> <option value="2023">2023</option> <option value="2024">2024</option> <option value="2025">2025</option> <option value="2026">2026</option> <option value="2027">2027</option> <option value="2028">2028</option> <option value="2029">2029</option> <option value="2030">2030</option> <option value="2031">2031</option> <option value="2032">2032</option> <option value="2033">2033</option> <option value="2034">2034</option> </select> </p> <p> <label for="cvv">Security Code (CVV)</label> <input type="input" name="cvv" id="cvv" autocomplete="off" maxlength="4" /> </p> <p> <label for="saveCard">Save Card</label> <input type="checkbox" name="saveCard" id="saveCard" value="YES" /> </p> <p> <label for="cardName">Card Name</label> <input type="text" name="cardName" id="cardName" /> </p> <p> <label for="installmentCount">Installment Count</label> <input type="text" name="installmentCount" id="installmentCount" /> </p> <input type="hidden" value="" name="points" id="points" /> <input type="hidden" value="" name="paymentSystem" id="paymentSystem" /> </div> </div> <div id="cardTokenContainer"> <p> <label for="cardToken">Card Token</label> <input type="text" name="cardToken" id="cardToken" autocomplete="off" maxlength="64" /> </p> <p> <label for="installmentCount">Installment Count</label> <input type="text" name="installmentCount" id="installmentCount" /> </p> </div> <input type="submit" value="Submit" /> </form> <script type="text/javascript" src="https://ZIRAATPAY_HOST/ziraatpay/static/external/whitewolf-v3.js"></script> <script type="text/javascript"> whitewolf.run(h.online-metrix.net, ORG_ID, SESSIONTOKEN); </script> <noscript> <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="https://h.online-metrix.net/tags?org_id=ORG_ID&session_id=UNIQUE_SESSION_ID&pageid=PAGEID"> </iframe> </noscript> </body> </html>

Cardless Direct POST - 3D Secure

"Cardless DIRECT POST (3D Secure) Test Form" example should be considered in order to integrate via cardless payment methods specified below.

• Maximum Mobil

Cardless DIRECT POST (3D Secure) Test Form

<!DOCTYPE html> <html> <head> <title>Sample Cardless POST Form</title> <meta charset="utf-8"> </head> <body> <form action="https://vpos.ziraatpay.com.tr/ziraatpay/api/v2/post/sale3d/[SECURE_SESSION_TOKEN]" method="post"> <input type="text" name="installmentCount" id="installmentCount" /> <input type="hidden" value="" name="cardlessPaymentSystem" id="cardlessPaymentSystem" /> <input type="submit" value="Submit" /> </form> <script type="text/javascript" src="https://ZIRAATPAY_HOST/ziraatpay/static/external/whitewolf-v3.js"></script> <script type="text/javascript"> whitewolf.run(h.online-metrix.net, ORG_ID, SESSIONTOKEN); </script> <noscript> <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="https://h.online-metrix.net/tags?org_id=ORG_ID&session_id=UNIQUE_SESSION_ID&pageid=PAGEID"> </iframe> </noscript> </body> </html>

					
merchantPaymentId: PaymentId-FVKAjOiFHeuE
apiMerchantId: 700100000
paymentSystem: ISBANK TEST
paymentSystemType: ISBANK
paymentSystemEftCode: 0064
pgTranDate: 20170112 14:13:13
pgTranId: 17012ONNI07013454
pgTranRefId: 701200002832
pgTranApprCode: 733185
pgOrderId: PaymentId-FVKAjOiFHeuE
customerId: Customer-u1Q4G1oG
amount: 11.76
installment: 1
sessionToken: VYD7AXJ6C446GIN55V6KKOB677VRTOZHG5HTSMP3EJCMEQYF
random: tpN2ynMYAn
SD_SHA512: 0f2b4945aefc71f547107898c2002c40d9d4a1508f7f00ee894138f6bc247ebc1238ead5aa01b6ba09bc7932a5957235b7837cc0270781d0a45055fe31648b61
sdSha512: 099e32f8df3130457d2b1595b069794ef6ed08c85a679f72336c5371e91087b223536b317fc43643ae0da06ea29e985a3c8185ab611606308760b0c260aa412f
responseCode: 00
responseMsg: Approved
                      
				

Direct Post 3D Authentication

This integration model is based on the scenario that the process of 3D authentication is finished seperately from the Sale / Preauth API Call. Merchant offers a page where Card Holder enters his/her card data and submits them. This is where the process of 3D authentication starts. Depending on the response given from the authentication process, merchant issues authorization via API.

Step 1:

The Merchant Core System makes a Session Token request in order to get a valid key value for defining the session.

Step 2:

The payment session request is processed; a session token is created and sent back to the merchant system in the API response.

Step 3:

Merchant system serves the payment & wallet page using the given secure session token.

Step 4:

Cardholder interacts with the page and clicks on Submit button. Merchant system submits all information received via this page to MSU system.

Step 5:

MSU receives POST request from the merchant's page and directs it to the 3D ACS (Access Control Server) in order to continue with the 3D authentication flow.

Step 6:

ACS serves the 3D Security Page where the Card Holder must enter the correct (dynamic) code sent to his/her mobile phone in order to authenticate.

Step 7:

MSU handles the response of the 3D Authentication of success or failure.

Step 8:

The final response of the 3D Authentication process is forwarded to the merchant's page. The merchant is expected to listen and parse the result within the posted form later on issues authorization via API (Sale / Preauth).

3D Authentication Direct Post Test Form

3D Authentication with Card Data Form

			
<form action="https://test.ziraatpay.com.tr/ziraatpay/api/v2/post/auth3d/[SECURE_SESSION_TOKEN]" method="post">
	<input type="text" name="cardOwner" placeholder="Card Owner" maxlength="32" />
	<input type="text" name="pan" placeholder="PAN" maxlength="19" />
	<select name="expiryMonth">
		<option value="01">January</option>
		<option value="02">February</option>
	</select> 
	<select name="expiryYear">
		<option value="2019">2019</option>
		<option value="2020">2020</option>
		<option value="2021">2021</option>
	</select>
	<input type="password" name="cvv" placeholder="CVV" maxlength="4" />
	<input type="checkbox" name="saveCard" />
	<input type="text" name="cardName" placeholder="Card Name"/>
	<input type="text" name="cardCutoffDay" placeholder="Card Cutoff Day"/>
	<input type="text" name="installmentCount" placeholder="Installment Count"/>
	<input type="hidden" name="points" />
	<input type="submit" value="Submit" />
</form>
			
		

3D Authentication with Card Token Form

			
<form action="https://test.ziraatpay.com.tr/ziraatpay/api/v2/post/auth3d/[SECURE_SESSION_TOKEN]" method="POST">
	<input name="pan" type="text" size="20" />
	<input name="cardOwner" type="text" size="20" />
	<input name="expiryMonth" type="text" size="2"/>
	<input name="expiryYear" type="text" size="4"/>
	<input name="cvv" type="text" size="4"/>
	<input name="cardCutoffDay" type="text" size="2"/>
	<input name="callbackUrl" value="[merchant-return-url-handler]" />
	<input type="submit" value="Complete Payment"/>
</form>

or if the payment will be done with an existing tokenized card
			
<form action="https://test.ziraatpay.com.tr/ziraatpay/api/v2/post/auth3d/[SECURE_SESSION_TOKEN]" method="POST">
	<input name="cardToken" type="text"  placeholder="Card Token"size="20" />
	<input name="cvv" type="text" placeholder="CVV" size="4" />
	<input type="submit" value="Complete Payment"/>
</form>
			
		

					
sessionToken: 3URSNNY5C6ZATI656WIPXZXDSTAN3PNGLTXLY75H7FNBA7UJ
auth3DToken: AUTH3DTOKEN
responseCode: 00
responseMsg: Approved
mdStatus: 1
mdErrorMsg: Authenticated
                      
				

API & HPP URLs

API URL: https://vpos.ziraatpay.com.tr/ziraatpay/api/v2
Hosted Payment Page URL (HPP): https://vpos.ziraatpay.com.tr/payment/[SECURE_SESSION_TOKEN]
DirectPost 3D URL: https://vpos.ziraatpay.com.tr/ziraatpay/api/v2/post/sale3d/[SECURE_SESSION_TOKEN]
DirectPost Non3D URL: https://vpos.ziraatpay.com.tr/merchant/post/sale/[SECURE_SESSION_TOKEN]

Global Open Source E-Commerce Platforms

As ZiraatPay, we are integrated with more than one E-commerce platforms, you can download the relevant plugin from the list below and install it into your system.

OpenCart

OpenCart is an open source online shopping management system. Thanks to OpenCart, you can manage your online store and easily perform integrated transactions.

Presta Shop

PrestaShop is a free PHP-based e-commerce software published in open source. It is one of the most preferred software options in the field of e-commerce.

Woo Commerce

WooCommerce is an open-source e-commerce plugin developed by WordPress developers. With a total of 63 language options, this plugin is continually updated by WordPress developers due to its open-source nature, and custom modules are developed to meet various needs.

"Our plugins are developed by our partner, EticSoft. Click here to download the plugins. You can submit your requests regarding the plugins through the Send Notification - EticSoft Support address."

Error Handling

If a request results in an error the ERROR and ERRORCODE parameters will be present in the response. Generally, there are two types of errors that can occur: core errors and payment gateway originating errors.

Core Errors

Core errors occur mostly because of invalid parameter values. These errors have the following code format: ERR100xx

Payment Gateway (vPOS) Errors

The ZiraatPay API uses a set of error codes for errors that originate from the payment gateway that is being used. This error set is derived from the ISO-8583 field 39 response values. The code format for these errors is ERR200xx.

Additional error related response parameters

There are two additional API response parameters that may help you indicate the cause of the error that has occurred in the case where the error originates from the payment gateway. These are PGTRANERRORCODE and PGTRANERRORTEXT . These two parameters are especially useful when you get an error from the payment gateway that is still not mapped in our error set. In this case the PGTRANERRORCODE and PGTRANERRORTEXT can help you determine the cause of the error.

Error response examples

Here are API response examples for multiple cases when an error has occurred.

					{ 
    "errorCode" : "ERR10027", 
    "responseCode" : "99", 
    "errorMsg" : "Geçersiz kart bilgisi (TOKEN) belirtilmiş", 
    "responseMsg" : "Declined",
    "violatorParam" : ""
}                       
				

					{
    "errorCode":"ERR20051",
    "responseCode":"99",
    "errorMsg":"Belirtilen kredi kartının limiti bu işlem için yeterli değildir",
    "responseMsg":"Declined",
    "violatorParam":""
}						
				

					{
    "errorCode":"ERR20099",
    "responseCode":"99",
    "errorMsg":"Lütfen yeniden deneyiniz, sorun devam ederse bankanızla iletişime geçiniz.",
    "responseMsg":"Declined",
    "violatorParam":""
}						
				

					{
    "apiMerchantId" : "6008138000",
    "paymentSystem" : "Teb test ps",
    "pgTranDate" : "20141215 17:22:54",
    "merchantPaymentId" : "session-a7bAS3AddR5PApN",
    "pgTranId" : "14349RW4Q89120700",
    "pgTranRefId" : "4398417187960",
    "pgOrderId" : "session-a7bRkDJK091pN",
    "responseCode" : "00",
    "responseMsg" : "Approved"
}						
				

Notifications

ZiraatPay has a built-in mechanism that is used to notify the respective merchant of events related to financial transactions.
More specifically, ZiraatPay sends notification messages to a merchant about specific events when:

• An approved transaction is performed

This notification service is triggered for approved transactions when ZiraatPay receives a response from the bank payment gateway for its request initiated for a particular transaction which confirms that this transaction is approved.
Note that a network timeout of 5 seconds applies when attempting to deliver the notification on merchant's endpoint.

How It Works?

A merchant should create a listener endpoint and the URL pointing to this endpoint should be added to this merchant's profile. ZiraatPay then sends notifications to the merchant when a particular event occurs which is mentioned in the list above.
When one such time event occurs, ZiraatPay then sends a secure FORM POST to the URL containing the respective parameters shown in the right.

					NOTIFICATIONTYPE: TRANSACTIONAPPROVED
CHANNEL: [MERCHANTBUSINESSID]
CUSTOMER: [CUSTOMERID]
CUSTOMERNAME: [CUSTOMERNAME]   
AMOUNT: [AMOUNT]
TRANSACTIONTYPE: [TRANSACTIONTYPE]
CURRENCY: [CURRENCY]
STATUS: [STATUS]
MERCHANTPAYMENTID: [MERCHANTPAYMENTID]
PGTRANSACTIONID: [PGTRANSACTIONID]
INSTALLMENTCOUNT: [INSTALLMENTCOUNT]
EFTCODE: [INSTALLMENTCOUNT]
				

Metadata

ZiraatPay Domain contains some important ojects and shares them with integrated clients.

Transaction

Each financial request refers a transaction in ZiraatPay domain. All settlement is done via transaction records.

A transaction has a type that can have one of these status any time. Please see the definitions given right handside.

					/* Sale */ SALE,
/* Pre-authorization */	PREAUTH,
/* Post-authorization */ POSTAUTH,
/* Refund */ REFUND,
/* Partial Refund */ PTREFUND,
/* Credit, Free refund */ CREDIT,
/* Void action */ VOID
				

					/* In Progress, Created */ IP,
/* CAncelled by CardHolder during approval */ CA,
/* FAiled / Declined (Response from the integrated vPOS) */	FA,
/* APproved (Response from the integrated vPOS) */ AP,
/* VoiDed (As secondary process) (Response from the integrated vPOS) */ VD,
/* Needs manual review (Response from the integrated vPOS exists) */ MR
			 
				
				

Other Usage Features

You can find other usages of ZiraatPay API below

Pay By Link

Providing an URL Link to the Payment Page is an alternative way of inviting card holders via remote channels like SMS, Mobile App Notificatins, Push Messages, e-Mails etc to make a payment. In this model, merchants need to create a payment page link and send it to their customers. When customers click on the link, they will be directed to the payment page where it already has all the neccessary payment information such as payment amount, shopping basket content etc. Then the customer will enter the card information and complete the payment.

In order to create a payment page link, merchants are required to send a SESSIONTOKEN request to ZiraatPay API by supplying all the relevant parameters. ZiraatPay will process this request, generate a session token information and return it to the merchant. This token is then used to generate the payment page link in order to do a sale or preauth transaction and it's sent to the cardholder (customer). The customer is expected to click on the link and complete the transaction before the link expires. When the clicked link has expired, the cardholder will be directed to the "Finalised Session" page. There is also another page called "Invalid Session" page which is served when the provided payment page link does not include a valid session token value. The expiry duration of the payment page link is set by the merchants using SESSIONTOKEN parameter which has a default value of 7 Days.

The response of successfully completed transactions is posted to the URL address specified in RETURNURL parameter of the SESSIONTOKEN request.

Step 1:

Merchant creates a new session token via ZiraatPay API SESSIONTOKEN request.

Step 2:

Merchant generates payment page link with that session token (E.g. https://test.ZiraatPay.com.tr/merchant/payment/[SESSIONTOKEN])

Step 3:

Link will be sent via SMS, e-mail, mobile app notification etc. to customer

Step 4:

Customer goes to the payment page via that link and finish the sale action.

Step 5:

Response of sale action will be returned to the URL which was mentioned on RETURNURL parameter's value as a POST request.

Test Cards

Here you can find Test Cards for different Banks
For all Nestpay banks, "a" should be used as 3D Secure password.

					
					

                    

                        

                            

                                
Bank
                                
Card Number
                                
Card Expiry
                                
CVV
                                
3D Secure Password
                            
                        
                        

                            

                                
Ziraat-VISA
                                
4546711234567894
                                
12/2026
                                
000
                                
a
                            
                        
                        

                            

                                
Ziraat-MASTER
                                
5401341234567891
                                
12/2026
                                
000
                                
a
                            
                        
                         
                        

                            

                                
AKBANK-VISA
                                
4355084355084358
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
AKBANK-MASTER
                                
5571135571135575
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
TEB-VISA
                                
4402934402934406
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
TEB-MASTER
                                
5101385101385104
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
HALKBANK-VISA
                                
4920244920244921
                                
12/2030
                                
001
                                
a
                            
                        
                        

                            

                                
HALKBANK-MASTER
                                
5404355404355405
                                
12/2030
                                
001
                                
a
                            
                        
                        

                            

                                
FINANSBANK-VISA
                                
4022774022774026
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
FINANSBANK-MASTER
                                
5456165456165454
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
ISBANK-VISA
                                
4508034508034509
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
ISBANK-MASTER
                                
5406675406675403
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
ANADOLUBANK-VISA
                                
4258464258464253
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
ANADOLUBANK-MASTER
                                
5222405222405229 
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
HSBC
                                
5100051016005572
                                
01/2020
                                
742
                                
a
                            
                        
                        

                            

                                
INGBANK-VISA
                                
4555714555714556
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
INGBANK-MASTER
                                
5400245400245409
                                
12/2030
                                
000
                                
a
                            
                        
                        

                            

                                
QNBFINANS-TROY
                                
9792350046201275
                                
07/2027
                                
993
                            
                        
                        

                            

                                
GARANTI-TROY
                                
9792052565200010
                                
01/2027
                                
327
                            
                        
                        

                            

                                
YKB-TROY
                                
6501617060023449
                                
12/2026
                                
000
                            
                        
                        

                            

                                
YKB-TROY
                                
6501617025774490
                                
12/2026
                                
000
                            
                        
                        

                            

                                
YKB-TROY
                                
6501617063597076
                                
12/2026
                                
000
                            
                        
                        

                            

                                
TURKIYE FINANS-TROY
                                
9792182023832743
                                
10/2028
                                
878
                                
a
                            
                        
                         

                            

                                
SEKERBANK-TROY
                                
6501750104751517
                                
12/2027
                                
516
                                
a
                            
                        
                         

                            

                                
AKBANK-TROY
                                
9792072000017956
                                
12/2027
                                
000
                                
a
                            
                        
                        

                            

                                
ABANK-TROY
                                
36577312700094
                                
12/2027
                                
000
                                
a
                            
                        
                        

                            

                                
YKB-VISA
                                
4506344103118942
                                
12/2025
                                
000
                            
                        
                        

                            

                                
YKB-VISA
                                
4506347023253988
                                
12/2025
                                
000
                            
                        
                        

                            

                                
YKB-VISA
                                
4506347028991897
                                
12/2025
                                
000
                            
                        
                        

                            

                                
YKB-VISA
                                
4506347026523718
                                
12/2025
                                
000
                            
                        
                        

                            

                                
YKB-MASTER
                                
5400617004770430
                                
12/2025
                                
000
                            
                        
                        

                            

                                
YKB-MASTER
                                
5400617020092306
                                
12/2025
                                
000
                            
                        
                        

                            

                                
YKB-MASTER
                                
5400617030400291
                                
12/2025
                                
000
                            
                        
                         

                            

                                
GARANTI-VISA
                                
4824892919057014
                                
12/2025
                                
067
                            
                        
                         

                            

                                
GARANTI-MASTER
                                
5378297758742014
                                
05/2025
                                
467
                            
                        
                        

                            

                                
KUVEYTTURK-MASTER
                                
5188961939192544
                                
06/2025
                                
929
                                
123456
                            
                        
                         

                            

                                
VAKIFBANK-VISA
                                
4938460158754205
                                
01/2024
                                
715
                                
123456
                            
                        
                        

                            

                                
VAKIFBANK-VISA
                                
4119790155203496
                                
04/2024
                                
579
                                
123456
                            
                        
                        

                            

                                
VAKIFBANK-MASTER
                                
5400617020092306
                                
12/2025
                                
Yok
                                
123456
                            
                        
				
                
					
				

Financial Transaction

The available transaction types in ZiraatPay system are listed and explained below:

Sale

A Sale transaction is a credit card transaction that immediately charges a customer's credit card.

Request parameters:

ACTION:

SALE, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTPAYMENTID:

string, conditional Max length: 128 Unique Payment ID given by Merchant.

CUSTOMER:

string, conditional Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

AMOUNT:

decimal, conditional Max length: 30 Amount of payment / transaction. Please note that, this amount is tax included, ZiraatPay doesn't consider any other tax calculation.

CURRENCY:

string, conditional Max length: 3 ISO Alpha transaction currency code like TRY, EUR, USD, GBP. Please check https://en.wikipedia.org/wiki/ISO_4217#Position_of_ISO_4217_code_in_amounts for details. See all possible values (33)

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CUSTOMEREMAIL:

string, conditional Max length: 64 Customer e-mail. This information should be passed correctly if the customer information services are used.

CUSTOMERNAME:

string, conditional Max length: 128 Name of the Customer. This information should be passed correctly if the customer information services are used.

CUSTOMERPHONE:

string, conditional Max length: 64 Customer phone / mobile number. This information should be passed correctly if the customer information services are used.

CUSTOMERIP:

string, conditional Max length: 39 Customer IP Address

CUSTOMERUSERAGENT:

string, optional Max length: 512 Customer User Agent

CUSTOMERBIRTHDAY:

date, optional Max length: 16 Format: [dd-MM-yyyy] Customer Birthday.

TCKN:

string, optional Max length: 16 Customer Identity Number.

AUTH3DTOKEN:

string, optional Max length: 16 description

CARDTOKEN:

string, conditional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

CARDPAN:

string, conditional Max length: 19 PAN (Primary account number), card number. Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CARDEXPIRY:

string, conditional Max length: 7 Expiry date of the card. Format should be [mm.yy].

NAMEONCARD:

string, conditional Max length: 64 Name on the card.

CARDCVV:

string, optional Max length: 4 Security number of the card, CVV value.

SAVECARD:

string, optional Max length: 3 If this has 'yes' value all cards are saved automatically on the payment page. Save Card parameter cannot be used for API integration model.

CARDSAVENAME:

string, optional Max length: 64 Given name for the saved card.

INSTALLMENTS:

integer, optional Max length: 2 Default value: '1' Number of installments. Specified number should exist in the payment system as defined.

POINTS:

string, optional Max length: 500

Sale by points can be used via points argument of sale action. This parameter gets its argument as a json format and parse it according to payment system.

AKBANK SALE BY POINTS SAMPLE

• POINTS must be json String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"XCBCHIPPARA", "value":"10"}]
• MULTIPLE POINTS USAGE: [{"name":"XCBCHIPPARA", "value":"10"},{"name":"PCBCHIPPARA", "value":"10"},{"name":"CCBCHIPPARA", "value":"10"}]

ISBANK SALE BY POINTS SAMPLE

• POINTS must be JSOn String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"MAXIPUAN","value":"1"}]

FINANSBANK SALE BY POINTS SAMPLE

• You can use points if and only if PARAPUAN equal to AMOUNT
• POINTS must be JSOn String, you can use POINTS argument in SALE method like below
POINTS : [{"name":"PARAPUAN","value":"10"}]

TEB BANK SALE BY POINTS SAMPLE

• You can use points if and only if KULLANBONUS equal to AMOUNT
• POINTS must be JSOn String, you can use POINTS argument in SALE method like below
POINTS : [{"name":"KULLANBONUS","value":"10"}]

HALKBANK SALE BY POINTS SAMPLE

• POINTS must be json String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"ODUL", "value":"10"}]

AKTIFBANK SALE BY POINTS SAMPLE

• POINTS must be json String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"KULLANPUAN","value":"10"}]

GARANTI BANK SALE BY POINTS SAMPLE

• POINTS must be json String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"FBB","value":"5160.02"},{"name":"BNS","value":"91462.68"}]

YAPI KREDI BANK SALE BY POINTS SAMPLE

• POINTS must be json String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"PUAN","value":"10.00"}]

HSBC BANK SALE BY POINTS SAMPLE

• POINTS must be json String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"ODUL","value":"10.00"}]

VAKIFBANK SALE BY POINTS SAMPLE

• POINTS must be JSOn String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"PUAN","value":"283567.72"}]

SEKERBANK SALE BY POINTS SAMPLE

• POINTS must be JSON String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"KULLANBONUS","value":"10"}]

DENIZBANK SALE BY POINTS SAMPLE

• POINTS must be JSON String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"BONUSAMOUNT","value":"10.00"}]

ZIRAATBANK SALE BY POINTS SAMPLE

• POINTS must be JSON String, you can use POINTS argument in SALE method like below
• POINTS : [{"name":"PUANSORGU","value":"PUANSORGU"},{"name":"KULLANPUAN","value":"10"}]

BILLTOADDRESSLINE:

string, optional Max length: 255 Bill To Address Line

BILLTOCITY:

string, optional Max length: 32 Bill To City

BILLTOPOSTALCODE:

string, optional Max length: 16 Bill To Postal Code

BILLTOCOUNTRY:

string, optional Max length: 32 Bill To Country
An alpha-3 code in ISO 3166-1 standard should be sent.

SHIPTOADDRESSLINE:

string, optional Max length: 255 Ship To Address Line

SHIPTOCITY:

string, optional Max length: 32 Ship To City

SHIPTOPOSTALCODE:

string, optional Max length: 16 Ship To Postal Code

SHIPTOCOUNTRY:

string, optional Max length: 32 Ship To Country
An alpha-3 code in ISO 3166-1 standard should be sent.

FASTSHIPPING:

string, optional Max length: 3 This param indicates that the shipping option is selected as fast, urgent, quick etc. If fast shipment is the option, then the merchant should send this parameter with "yes" value. See all possible values (2)

EXTRA:

string, optional Max length: 4000 Extra Parameter is a custom parameter that is used to pass additional parameters to session token. This parameter is expected to be in JSON(URL-ENCODED) format. If they are mispelled, they will be ignored! Supported parameters are: CardHolderAgreementMode(value: NONE/SHOW/SHOWCHECKED/SHOWCHECKEDDISABLED), AlwaysSaveCard(value: true/false), BuyerType (value: L for logged in customer; A for anonymous, F for the first shopping with memebership. OR it can be 0, 1, 2 for those cases), IsbankBolumKodu(string), IframeDomainUrl indicates from which URL address payment will be proceesed., PREAUTH=YES parameter indicates that payment will be processed as pre-authorization even if is started as sale., IGNORECUSTOMERCOMMISSION(values : YES/NO).
EXTRA: {"AlwaysSaveCard": "true", "BuyerType": "L", "IsbankBolumKodu": 12, "CardHolderAgreementMode": "SHOWCHECKED", "IGNORECUSTOMERCOMMISSION" : "YES"}

Other bank parameters

• MAXIMUMMOBIL - include Maximum Mobil payment system name like below to have Maximum Mobil tab on Default HPP
  {"MaximumMobilPaymentSystem":"PaymentSystemName"}
• GIROGATE payment methods. If one of payment methods is sent as "Yes", authentication will be done using GiroGate payment methods. Possible values: YES/NO.
  • SOFORT: {"SOFORT": "YES"}
  • SAFETYPAY: {"SAFETYPAY": "YES"}
  • QIWI: {"QIWI": "YES"}
  • GIROPAY: {"GIROPAY": "YES"}
  • IDEAL: {"IDEAL": "YES"}
  • FINNISHONLINEBANKING: {"FINNISHONLINEBANKING": "YES"}
  • BANCONTACT: {"BANCONTACT": "YES"}
  • ALIPAY: {"ALIPAY": "YES"}
  • MULTIBANCO: {"MULTIBANCO": "YES"}
  • TRUSTPAY: {"TRUSTPAY": "YES"}
  • EPS: {"EPS": "YES"}
  • MYBANK: {"MYBANK": "YES"}
  • P24: {"P24": "YES"}
  • BOLETO: {"BOLETO": "YES"}
  • ELO: {"ELO": "YES"}
  • SEPA: {"SEPA": "YES"}
  • UPOP: {"UPOP": "YES"}
• ISBANK - include in extra like below to send agriculture template info to Isbank when doing imece card operations.
  {"IMCKOD":"imckod", "FDONEM":"fdonem"}

SHIPTOPHONE:

string, optional Max length: 32 Phone number of shipment information

BILLTOPHONE:

string, optional Max length: 32 Phone number of billment information

BUYERTYPE:

string, optional Max length: 1 Default value: 'A' Member/Anonymous user flag See all possible values ()

SELLERID:

string, optional Max length: 1024 Unique value per seller.

COMMISSIONAMOUNT:

string, optional Max length: 512 description

DISCOUNTAMOUNT:

decimal, optional Max length: 30 The amount to be discounted from ORDERITEMS total amount. When provided, the AMOUNT field should be equal to the subtraction of ORDERITEMS total amount with DISCOUNTAMOUNT. (AMOUNT = ORDERITEMS - DISCOUNTAMOUNT)

FORGROUP:

string, optional Max length: 3 Default value: 'YES' Specifies the for group featured usages. Available values are 'yes' and 'no'.

TOTALSELLERCOMMISSIONAMOUNT:

decimal, optional Max length: 30 description

TOTALSELLERPAYMENTAMOUNT:

decimal, optional Max length: 30 description

NOTIFICATIONURL:

string, optional Max length: 255 description

SELLERPAYMENTAMOUNT:

string, optional Max length: 512 description

CUSTOMERTYPE:

string, optional Max length: 32 description See all possible values (4)

CAMPAIGNS:

string, optional Max length: 1024 It represents the campaigns which is provided encoded JSON object. Example: [{"campaignCode": "taks3","campaignName": "2","campaignExtra": "ArtiTaksit"}] - while sending the request it must be encoded

					
ACTION: SALE
AMOUNT: 18.75
CURRENCY: TRY
MERCHANTPAYMENTID: PaymentId-3gMvdMzXMj2q
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT]
CUSTOMER: Customer-Lsw7mJAm
CUSTOMERNAME: Name Lsw7mJAm
CUSTOMEREMAIL: Lsw7mJAm@email.com
CUSTOMERIP: 127.0.0.1
CUSTOMERUSERAGENT: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.81 Safari/537.36
NAMEONCARD: Name Lsw7mJAm
CUSTOMERPHONE: +901638874658
CUSTOMERBIRTHDAY: 01-01-2001
BILLTOADDRESSLINE: Road
BILLTOCITY: Istanbul
BILLTOCOUNTRY: Turkey
BILLTOPOSTALCODE: 1103
BILLTOPHONE: 123456789
SHIPTOADDRESSLINE: Road
SHIPTOCITY: Ankara
SHIPTOCOUNTRY: Turkey
SHIPTOPOSTALCODE: 1105
SHIPTOPHONE: 987654321
CARDPAN: 5456165456165454
CARDEXPIRY: 12.2020
CARDCVV: 000
		 
				

					{
  "action" : "SALE",
  "merchant" : "10000000",
  "amount" : 18.75,
  "currency" : "TRY",
  "apiMerchantId" : "600600000",
  "paymentSystem" : "My Finans Webpos Online Account (Test)",
  "paymentSystemType" : "FINANS",
  "paymentSystemEftCode" : "0111",
  "pgTranDate" : "20160729 12:18:53",
  "merchantPaymentId" : "PaymentId-3gMvdMzXMj2q",
  "pgTranId" : "16211MS3D00124776",
  "pgTranRefId" : "621112352883",
  "pgOrderId" : "PaymentId-3gMvdMzXMj2q",
  "responseCode" : "00",
  "responseMsg" : "Approved"
}                       
				

Preauth

A PreAuth transaction is a credit card transaction that reserves funds on a customer's credit card. PreAuth transaction does not charge the card until you perform a PostAuth transaction. Please note that Pre-Authorizations reserve funds for varying periods, depending on the issuing credit card company's policy. The period may be as little as three days or as long as several months. For your protection it is recommended that you confirm delivery of the product/service as soon as possible after pre-authorization.

Request parameters:

ACTION:

PREAUTH, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTPAYMENTID:

string, conditional Max length: 128 Unique Payment ID given by Merchant.

CUSTOMER:

string, conditional Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

AMOUNT:

decimal, conditional Max length: 30 Amount of payment / transaction. Please note that, this amount is tax included, ZiraatPay doesn't consider any other tax calculation.

CURRENCY:

string, conditional Max length: 3 ISO Alpha transaction currency code like TRY, EUR, USD, GBP. Please check https://en.wikipedia.org/wiki/ISO_4217#Position_of_ISO_4217_code_in_amounts for details. See all possible values (33)

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CARDTOKEN:

string, conditional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

CARDPAN:

string, conditional Max length: 19 PAN (Primary account number), card number. Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CARDEXPIRY:

string, conditional Max length: 7 Expiry date of the card. Format should be [mm.yy].

NAMEONCARD:

string, conditional Max length: 64 Name on the card.

CUSTOMEREMAIL:

string, conditional Max length: 64 Customer e-mail. This information should be passed correctly if the customer information services are used.

CUSTOMERNAME:

string, conditional Max length: 128 Name of the Customer. This information should be passed correctly if the customer information services are used.

CUSTOMERPHONE:

string, conditional Max length: 64 Customer phone / mobile number. This information should be passed correctly if the customer information services are used.

CUSTOMERIP:

string, conditional Max length: 39 Customer IP Address

CUSTOMERUSERAGENT:

string, optional Max length: 512 Customer User Agent

CUSTOMERBIRTHDAY:

date, optional Max length: 16 Format: [dd-MM-yyyy] Customer Birthday.

TCKN:

string, optional Max length: 16 Customer Identity Number.

AUTH3DTOKEN:

string, optional Max length: 16 description

INSTALLMENTS:

integer, optional Max length: 2 Default value: '1' Number of installments. Specified number should exist in the payment system as defined.

CARDCVV:

string, optional Max length: 4 Security number of the card, CVV value.

SAVECARD:

string, optional Max length: 3 If this has 'yes' value all cards are saved automatically on the payment page. Save Card parameter cannot be used for API integration model.

CARDSAVENAME:

string, optional Max length: 64 Given name for the saved card.

BILLTOADDRESSLINE:

string, optional Max length: 255 Bill To Address Line

BILLTOCITY:

string, optional Max length: 32 Bill To City

BILLTOPOSTALCODE:

string, optional Max length: 16 Bill To Postal Code

BILLTOCOUNTRY:

string, optional Max length: 32 Bill To Country
An alpha-3 code in ISO 3166-1 standard should be sent.

SHIPTOADDRESSLINE:

string, optional Max length: 255 Ship To Address Line

SHIPTOCITY:

string, optional Max length: 32 Ship To City

SHIPTOPOSTALCODE:

string, optional Max length: 16 Ship To Postal Code

SHIPTOCOUNTRY:

string, optional Max length: 32 Ship To Country
An alpha-3 code in ISO 3166-1 standard should be sent.

FASTSHIPPING:

string, optional Max length: 3 This param indicates that the shipping option is selected as fast, urgent, quick etc. If fast shipment is the option, then the merchant should send this parameter with "yes" value. See all possible values (2)

EXTRA:

string, optional Max length: 4000 Extra Parameter is a custom parameter that is used to pass additional parameters to session token. This parameter is expected to be in JSON(URL-ENCODED) format. If they are mispelled, they will be ignored! Supported parameters are: CardHolderAgreementMode(value: NONE/SHOW/SHOWCHECKED/SHOWCHECKEDDISABLED), AlwaysSaveCard(value: true/false), BuyerType (value: L for logged in customer; A for anonymous, F for the first shopping with memebership. OR it can be 0, 1, 2 for those cases), IsbankBolumKodu(string), IframeDomainUrl indicates from which URL address payment will be proceesed., PREAUTH=YES parameter indicates that payment will be processed as pre-authorization even if is started as sale., IGNORECUSTOMERCOMMISSION(values : YES/NO).
EXTRA: {"AlwaysSaveCard": "true", "BuyerType": "L", "IsbankBolumKodu": 12, "CardHolderAgreementMode": "SHOWCHECKED", "IGNORECUSTOMERCOMMISSION" : "YES"}

Other bank parameters

• MAXIMUMMOBIL - include Maximum Mobil payment system name like below to have Maximum Mobil tab on Default HPP
  {"MaximumMobilPaymentSystem":"PaymentSystemName"}
• GIROGATE payment methods. If one of payment methods is sent as "Yes", authentication will be done using GiroGate payment methods. Possible values: YES/NO.
  • SOFORT: {"SOFORT": "YES"}
  • SAFETYPAY: {"SAFETYPAY": "YES"}
  • QIWI: {"QIWI": "YES"}
  • GIROPAY: {"GIROPAY": "YES"}
  • IDEAL: {"IDEAL": "YES"}
  • FINNISHONLINEBANKING: {"FINNISHONLINEBANKING": "YES"}
  • BANCONTACT: {"BANCONTACT": "YES"}
  • ALIPAY: {"ALIPAY": "YES"}
  • MULTIBANCO: {"MULTIBANCO": "YES"}
  • TRUSTPAY: {"TRUSTPAY": "YES"}
  • EPS: {"EPS": "YES"}
  • MYBANK: {"MYBANK": "YES"}
  • P24: {"P24": "YES"}
  • BOLETO: {"BOLETO": "YES"}
  • ELO: {"ELO": "YES"}
  • SEPA: {"SEPA": "YES"}
  • UPOP: {"UPOP": "YES"}
• ISBANK - include in extra like below to send agriculture template info to Isbank when doing imece card operations.
  {"IMCKOD":"imckod", "FDONEM":"fdonem"}

SHIPTOPHONE:

string, optional Max length: 32 Phone number of shipment information

BILLTOPHONE:

string, optional Max length: 32 Phone number of billment information

BUYERTYPE:

string, optional Max length: 1 Default value: 'A' Member/Anonymous user flag See all possible values ()

SELLERID:

string, optional Max length: 1024 Unique value per seller.

COMMISSIONAMOUNT:

string, optional Max length: 512 description

SELLERPAYMENTAMOUNT:

string, optional Max length: 512 description

DISCOUNTAMOUNT:

decimal, optional Max length: 30 The amount to be discounted from ORDERITEMS total amount. When provided, the AMOUNT field should be equal to the subtraction of ORDERITEMS total amount with DISCOUNTAMOUNT. (AMOUNT = ORDERITEMS - DISCOUNTAMOUNT)

FORGROUP:

string, optional Max length: 3 Default value: 'YES' Specifies the for group featured usages. Available values are 'yes' and 'no'.

NOTIFICATIONURL:

string, optional Max length: 255 description

CUSTOMERTYPE:

string, optional Max length: 32 description See all possible values (4)

					ACTION: PREAUTH
AMOUNT: 18.73
CURRENCY: TRY
MERCHANTPAYMENTID: PaymentId-a1aJk7isjUFa
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD
MERCHANT: [MERCHANT]
CUSTOMER: Customer-8UtUjDuF
CUSTOMERNAME: Name 8UtUjDuF
CUSTOMEREMAIL: 8UtUjDuF@email.com
CUSTOMERIP: 127.0.0.1
CUSTOMERUSERAGENT: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.81 Safari/537.36
NAMEONCARD: Name 8UtUjDuF
CUSTOMERPHONE: +903150474176
CUSTOMERBIRTHDAY: 01-01-2001
BILLTOADDRESSLINE: Road
BILLTOCITY: Istanbul
BILLTOCOUNTRY: Turkey
BILLTOPOSTALCODE: 1103
BILLTOPHONE: 123456789
SHIPTOADDRESSLINE: Road
SHIPTOCITY: Ankara
SHIPTOCOUNTRY: Turkey
SHIPTOPOSTALCODE: 1105
SHIPTOPHONE: 987654321
CARDPAN: 4022774022774026   
CARDEXPIRY: 12.2020
CARDCVV: 000
SELLERID: seller01; seller02
COMMISSIONAMOUNT: 50,55;35,62
           
				

					{
  "action" : "PREAUTH",
  "merchant" : "10000000",
  "amount" : 18.73,
  "currency" : "TRY",
  "apiMerchantId" : "600600000",
  "paymentSystem" : "My Finans Webpos Online Account (Test)",
  "paymentSystemType" : "FINANS",
  "paymentSystemEftCode" : "0111",
  "pgTranDate" : "20160729 12:28:16",
  "merchantPaymentId" : "PaymentId-a1aJk7isjUFa",
  "pgTranId" : "16211McQE00102144",
  "pgTranRefId" : "621112352885",
  "pgOrderId" : "PaymentId-a1aJk7isjUFa",
  "responseCode" : "00",
  "responseMsg" : "Approved"
}                     
				

Postauth

PostAuth is a credit card transaction that captures the funds on the customer’s card for a specified amount reserved earlier using PreAuth transaction. If you enter a larger total in the PostAuth transaction than what was specified for the PreAuth transaction, the PostAuth transaction may be declined. If you enter a smaller amount than was pre-authorized, an adjustment is made to the authorization to capture only the smaller amount of funds on the customer’s card for the transaction. PostAuth transactions must be completed within certain amount of time after the the pre-authorization is obtained. This time period varies between 3 days and 75 days depending on the card issuer’s policy.

Request parameters:

ACTION:

POSTAUTH, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

PGTRANID:

string, conditional Max length: 64 Transaction ID given by payment gateway.

MERCHANTPAYMENTID:

string, conditional Max length: 128 Unique Payment ID given by Merchant.

AMOUNT:

decimal, optional Max length: 30 Default value: '0' Amount of payment / transaction. Please note that, this amount is tax included, ZiraatPay doesn't consider any other tax calculation.

ORDERITEMS:

string, optional Max length: 100000 Order items as array in JSON Format. Order items should be URL encoded. Please see the request samples for valid JSON data format.

					ACTION: POSTAUTH
MERCHANT: [MERCHANT]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPAYMENTID: ziraatpay-1352728431091
ORDERITEMS:  [
{
	"productCode": "T00D3AITCC",
	"quantity": 2
},
{
	"productCode": "B00D9AVYBM",
	"amount": 150
}
				

					{
    "action"   : "POSTAUTH",
    "merchant" : "testmerchant",
    "amount"   :   "17.22",
    "currency" : "TRY",
    "pgTranId": "12317QR6A12524",
    "merchantPaymentId": "ziraatpay-1352728431091",
    "responseMsg": "Approved",
    "responseCode": "00",
    "pgTranRefId": "231700000252",
    "pgOrderId": "ORDER-12317QQDG12490",
    "apiMerchantId":"700100000",
    "paymentSystem":"ISBANK TEST",
    "pgTranDate":"20140927 14:51:27"
}                        
				

Void

A void transaction cancels any transaction, apart from itself. Void cannot be voided. You will get success response for void transactions only if they are not included in the end-of-day settlement process taking place at the issuer’s side. This is the process runs at the end of business day to settle all transactions. This is when the actual funds are transferred from the cardholder’s credit card to merchant’s bank account. So, for example; if you would like to void a sale or postauth transaction that is already processed as part of the end-of-day settlement, then you will get a failed error code for the void request. In this case, you will need to use refund as alternative to void action.

Request parameters:

ACTION:

VOID, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

PGTRANID:

string, conditional Max length: 64 Transaction ID given by payment gateway.

MERCHANTPAYMENTID:

string, conditional Max length: 128 Unique Payment ID given by Merchant.

					ACTION: VOID
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT]
PGTRANID: 14339MfqD01014997   
REFLECTCOMMISSION : 
				

					{
    "merchantPaymentId":"session-QKFRg437iRrg",
    "pgTranId":"14339MfqD01014997",
    "pgTranRefId":"433912398111",
    "pgOrderId":"session-QKFRg437iRrg",
    "responseCode":"00",
    "responseMsg":"Approved"
}                       
				

Refund

A Refund transaction returns funds to a customer’s credit card for an existing order on the system. To perform a refund, you need the transaction number, which you can find in your reports. If you perform a return of the full payment amount, the payment amount will be reset to the original amount.

Request parameters:

ACTION:

REFUND, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

AMOUNT:

decimal, optional Max length: 30 Amount of payment / transaction. Please note that, this amount is tax included, ZiraatPay doesn't consider any other tax calculation.

CURRENCY:

string, optional Max length: 3 ISO Alpha transaction currency code like TRY, EUR, USD, GBP. Please check https://en.wikipedia.org/wiki/ISO_4217#Position_of_ISO_4217_code_in_amounts for details. See all possible values (33)

PGTRANID:

string, conditional Max length: 64 Transaction ID given by payment gateway.

MERCHANTPAYMENTID:

string, conditional Max length: 128 Unique Payment ID given by Merchant.

NOTIFICATIONURL:

string, optional Max length: 255 description

ORDERITEMS:

string, optional Max length: 100000 Order items as array in JSON Format. Order items should be URL encoded. Please see the request samples for valid JSON data format.

REFLECTCOMMISSION:

string, optional Max length: 3 Default value: 'NO' description See all possible values (2)

					ACTION: REFUND
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT]
CURRENCY: TRY
AMOUNT: 17.17
PGTRANID: 14339MjuG01015018
REFLECTCOMMISSION: No
				

					{
    "merchantPaymentId":"session-deQdckAmzHK4",
    "pgTranId":"14339MkiG01015022",
    "pgTranRefId":"433912398115",
    "pgOrderId":"session-deQdckAmzHK4",
    "responseCode":"00",
    "responseMsg":"Approved",
    "refundType":"FULL"
}                       
				

Session

Session Token

Session token can be used both for browser based integrations and API integrations. System return a key which has an access to API in a limited time (default 7 days, it is configurable). Generally session token action expect that each session should have an unique merchantPaymentId parameter. In case when you redirect your customer with same parameter set you can use same session token unless it is obeying the below criteria :

If merchant don't have a sucessfull or voided transation with this merchantPaymentId.

If session token is still active, it means the creation time of session token is early than 7 days.

If all core paramaters(amount, customer,currency,sessionType and returnUrl) of session token is same unless one of this parameter is changed in other attempts with this sessionToken system return an error code.

Merchant can send sessionToken request with same merchantPaymentId according to these rules.

				
<!--
    NOTE
    * Replace UNIQUE_SESSION_ID with a uniquely generated handle
    * PAGEID is only needed for TDCloud, replace PAGEID with an unique ID for that page, if omitted, default is 1 for production
    * For production replace h.online-metrix.net with a local URL and configure your web server to redirect to h.online-metrix.net. When using whitewolf, if a web server is configured, HOST should be the host of your web server, if not configured the HOST should be h.online-metrix.net
    * Replace ZIRAATPAY_HOST with the appropriate host
        Test:       test.ziraatpay.com.tr
        Production: vpos.ziraatpay.com.tr
-->
<script type="text/javascript" src="https://ZIRAATPAY_HOST/ziraatpay/static/external/whitewolf-v3.js"></script>
<script type="text/javascript">
	whitewolf.run(HOST, ORG_ID, UNIQUE_SESSION_ID);
</script>
<noscript>
    <iframe
        style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;"
        src="https://h.online-metrix.net/tags?org_id=ORG_ID&session_id=UNIQUE_SESSION_ID&pageid=PAGEID">
    </iframe>
</noscript>
				
			

Request parameters:

ACTION:

SESSIONTOKEN, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, required Max length: 128 API User.

MERCHANTPASSWORD:

string, required Max length: 128 API User password.

MERCHANT:

string, required Max length: 128 Merchant business code defined in the system.

SESSIONTYPE:

string, required Max length: 15 Session type is a session for payment or wallet (PAYMENTSESSION or WALLETSESSION) See all possible values (2)

RETURNURL:

string, required Max length: 256 Return URL after successful / failed payment.

MERCHANTPAYMENTID:

string, conditional Max length: 128 Unique Payment ID given by Merchant.

AMOUNT:

decimal, conditional Max length: 30 Amount of payment / transaction. Please note that, this amount is tax included, ZiraatPay doesn't consider any other tax calculation.

CURRENCY:

string, conditional Max length: 3 ISO Alpha transaction currency code like TRY, EUR, USD, GBP. Please check https://en.wikipedia.org/wiki/ISO_4217#Position_of_ISO_4217_code_in_amounts for details. See all possible values (33)

CUSTOMER:

string, required Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

CUSTOMEREMAIL:

string, optional Max length: 64 Customer e-mail. This information should be passed correctly if the customer information services are used.

CUSTOMERNAME:

string, required Max length: 128 Name of the Customer. This information should be passed correctly if the customer information services are used.

CUSTOMERPHONE:

string, optional Max length: 64 Customer phone / mobile number. This information should be passed correctly if the customer information services are used.

CUSTOMERBIRTHDAY:

date, optional Max length: 16 Format: [dd-MM-yyyy] Customer Birthday.

CUSTOMERIP:

string, required Max length: 39 Customer IP Address

CUSTOMERUSERAGENT:

string, optional Max length: 512 Customer User Agent

ORDERITEMS:

string, conditional Max length: 100000 Order items as array in JSON Format. Order items should be URL encoded. Please see the request samples for valid JSON data format.

HASORDERITEMS:

string, optional Max length: 3 description

TCKN:

string, optional Max length: 16 Customer Identity Number.

SESSIONEXPIRY:

string, optional Max length: 5 Default value: '168h' Session expiry time, default value is 7 days ( 7x24 hours ).

LANGUAGE:

string, optional Max length: 2 Default value: 'tr' Locale of pages displayed during payment.

BILLTOADDRESSLINE:

string, optional Max length: 255 Bill To Address Line

BILLTOCITY:

string, optional Max length: 32 Bill To City

BILLTOPOSTALCODE:

string, optional Max length: 16 Bill To Postal Code

BILLTOCOUNTRY:

string, optional Max length: 32 Bill To Country
An alpha-3 code in ISO 3166-1 standard should be sent.

SHIPTOADDRESSLINE:

string, optional Max length: 255 Ship To Address Line

SHIPTOCITY:

string, optional Max length: 32 Ship To City

SHIPTOPOSTALCODE:

string, optional Max length: 32 Ship To Postal Code

SHIPTOCOUNTRY:

string, optional Max length: 32 Ship To Country
An alpha-3 code in ISO 3166-1 standard should be sent.

FASTSHIPPING:

string, optional Max length: 3 Default value: 'NO' This param indicates that the shipping option is selected as fast, urgent, quick etc. If fast shipment is the option, then the merchant should send this parameter with "yes" value. See all possible values (2)

EXTRA:

string, optional Max length: 4000 Extra Parameter is a custom parameter that is used to pass additional parameters to session token. This parameter is expected to be in JSON(URL-ENCODED) format. If they are mispelled, they will be ignored! Supported parameters are: CardHolderAgreementMode(value: NONE/SHOW/SHOWCHECKED/SHOWCHECKEDDISABLED), AlwaysSaveCard(value: true/false), BuyerType (value: L for logged in customer; A for anonymous, F for the first shopping with memebership. OR it can be 0, 1, 2 for those cases), IsbankBolumKodu(string), IframeDomainUrl indicates from which URL address payment will be proceesed., PREAUTH=YES parameter indicates that payment will be processed as pre-authorization even if is started as sale., IGNORECUSTOMERCOMMISSION(values : YES/NO).
EXTRA: {"AlwaysSaveCard": "true", "BuyerType": "L", "IsbankBolumKodu": 12, "CardHolderAgreementMode": "SHOWCHECKED", "IGNORECUSTOMERCOMMISSION" : "YES"}

Other bank parameters

• MAXIMUMMOBIL - include Maximum Mobil payment system name like below to have Maximum Mobil tab on Default HPP
  {"MaximumMobilPaymentSystem":"PaymentSystemName"}
• GIROGATE payment methods. If one of payment methods is sent as "Yes", authentication will be done using GiroGate payment methods. Possible values: YES/NO.
  • SOFORT: {"SOFORT": "YES"}
  • SAFETYPAY: {"SAFETYPAY": "YES"}
  • QIWI: {"QIWI": "YES"}
  • GIROPAY: {"GIROPAY": "YES"}
  • IDEAL: {"IDEAL": "YES"}
  • FINNISHONLINEBANKING: {"FINNISHONLINEBANKING": "YES"}
  • BANCONTACT: {"BANCONTACT": "YES"}
  • ALIPAY: {"ALIPAY": "YES"}
  • MULTIBANCO: {"MULTIBANCO": "YES"}
  • TRUSTPAY: {"TRUSTPAY": "YES"}
  • EPS: {"EPS": "YES"}
  • MYBANK: {"MYBANK": "YES"}
  • P24: {"P24": "YES"}
  • BOLETO: {"BOLETO": "YES"}
  • ELO: {"ELO": "YES"}
  • SEPA: {"SEPA": "YES"}
  • UPOP: {"UPOP": "YES"}
• ISBANK - include in extra like below to send agriculture template info to Isbank when doing imece card operations.
  {"IMCKOD":"imckod", "FDONEM":"fdonem"}

SHIPTOPHONE:

string, optional Max length: 32 Phone number of shipment information

BILLTOPHONE:

string, optional Max length: 32 Phone number of billment information

DISCOUNTAMOUNT:

decimal, optional Max length: 30 The amount to be discounted from ORDERITEMS total amount. When provided, the AMOUNT field should be equal to the subtraction of ORDERITEMS total amount with DISCOUNTAMOUNT. (AMOUNT = ORDERITEMS - DISCOUNTAMOUNT)

SELLERID:

string, optional Max length: 1024 Unique value per seller.

COMMISSIONAMOUNT:

string, optional Max length: 512 description

SELLERPAYMENTAMOUNT:

string, optional Max length: 512 description

TOTALSELLERCOMMISSIONAMOUNT:

decimal, optional Max length: 30 description

TOTALSELLERPAYMENTAMOUNT:

decimal, optional Max length: 30 description

CUSTOMERTYPE:

string, optional Max length: 32 description See all possible values (4)

					ACTION: SESSIONTOKEN   
MERCHANTUSER: [MERCHANTUSER]   
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT]
AMOUNT: 11.21
CURRENCY: TRY
MERCHANTPAYMENTID: PaymentId-FuldmrwwiOpb
RETURNURL: https://neon-app.local.payten.com.tr/msu.merchant/index.jsp
CUSTOMER: Customer-jNPz2qSI
CUSTOMERNAME: Name jNPz2qSI
CUSTOMEREMAIL: jNPz2qSI@email.com
CUSTOMERIP: 127.0.0.1
CUSTOMERUSERAGENT: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.81 Safari/537.36
NAMEONCARD: Name jNPz2qSI
CUSTOMERPHONE: 6381053412
ORDERITEMS:  [ 
        { 
            "productCode": "T00D3AITCC",
            "name": "Galaxy Note 3", 
            "description": "Description of Galaxy Note 3", 
            "quantity": 2, 
            "amount": 449.99
        }, 
        { 
            "productCode": "B00D9AVYBM",
            "name": "Samsung Galaxy S III", 
            "description": "Samsung Galaxy S III (S3) Triband White (Boost Mobile)", 
            "quantity": 1, 
            "amount": 149.95 
        }, 
        { 
            "productCode": "B00NQGP5M8",
            "name": "Apple iPhone 6", 
            "description": "Apple iPhone 6, Gold, 64 GB (Unlocked) by Apple", 
            "quantity": 1, 
            "amount": 139.95 
        }, 
        { 
            "productCode": "B00U8KSUIG",
            "name": "Samsung Galaxy S6", 
            "description": "Samsung Galaxy S6 SM-G920F 32GB (FACTORY UNLOCKED) 5.1 QHDBlack-InternationalVersion", 
            "quantity": 1, 
            "amount": 129.95 
        } 
]

DISCOUNTAMOUNT: 2.50
BILLTOADDRESSLINE: Road
BILLTOCITY: Istanbul
BILLTOCOUNTRY: Turkey
BILLTOPOSTALCODE: 1103
BILLTOPHONE: 123456789
SHIPTOADDRESSLINE: Road
SHIPTOCITY: Ankara
SHIPTOCOUNTRY: Turkey
SHIPTOPOSTALCODE: 1105
SHIPTOPHONE: 987654321
SESSIONTYPE: PAYMENTSESSION
SELLERID: seller01; seller02
COMMISSIONAMOUNT: 50.55;35.62
		

					{
  "sessionToken" : "HCZVQH5FIR5QBHBQCT6AMUJLVHEHXCMSQ2HA5I6WCGQKQNQX",
  "responseCode" : "00",
  "responseMsg" : "Approved"
}
				

					ACTION: SESSIONTOKEN   
AMOUNT: 17.82
CURRENCY: TRY
MERCHANTPAYMENTID: PaymentId-DkOxtbUcP7gF
MERCHANTUSER: [MERCHANTUSER] 
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT]
RETURNURL: https://neon-app.local.payten.com.tr/msu.merchant/index.jsp
CUSTOMER: Customer-PJYbATmL
CUSTOMERNAME: Name PJYbATmL
CUSTOMEREMAIL: PJYbATmL@email.com
CUSTOMERIP: 127.0.0.1
CUSTOMERUSERAGENT: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.81 Safari/537.36
NAMEONCARD: Name PJYbATmL
CUSTOMERPHONE: 8487817375
ORDERITEMS:  [ 
        { 
            "productCode": "T00D3AITCC", 
            "name": "Galaxy Note 3", 
            "description": "Description of Galaxy Note 3", 
            "quantity": 2, 
            "amount": 449.99
        }, 
        { 
            "productCode": "B00D9AVYBM", 
            "name": "Samsung Galaxy S III", 
            "description": "Samsung Galaxy S III (S3) Triband White (Boost Mobile)", 
            "quantity": 1, 
            "amount": 149.95 
        }, 
        { 
            "productCode": "B00NQGP5M8", 
            "name": "Apple iPhone 6", 
            "description": "Apple iPhone 6, Gold, 64 GB (Unlocked) by Apple", 
            "quantity": 1, 
            "amount": 139.95 
        }, 
        { 
            "productCode": "B00U8KSUIG", 
            "name": "Samsung Galaxy S6", 
            "description": "Samsung Galaxy S6 SM-G920F 32GB (FACTORY UNLOCKED) 5.1 QHDBlack-InternationalVersion", 
            "quantity": 1, 
            "amount": 129.95 
        } 
] 
BILLTOADDRESSLINE: Road
BILLTOCITY: Istanbul
BILLTOCOUNTRY: Turkey
BILLTOPOSTALCODE: 1103
BILLTOPHONE: 123456789
SHIPTOADDRESSLINE: Road
SHIPTOCITY: Ankara
SHIPTOCOUNTRY: Turkey
SHIPTOPOSTALCODE: 1105
SHIPTOPHONE: 987654321
SESSIONTYPE: WALLETSESSION

					{
  "sessionToken" : "HZ3JBAFJ72AJTWRR75JOKWTFHMVHG7Y6UH6VTAGABLMV7LID",
  "responseCode" : "00",
  "responseMsg" : "Approved"
}
				

Pay by Link Payment Actions

Add Pay by Link Payment

See Description

Note: If Pay By Link Payment is created with existing customer just parameter CUSTOMER should be sent, otherwise if it's new customer parameters CUSTOMERNAME, CUSTOMERPHONE and CUSTOMEREMAIL are required and should be sent on request.

Request parameters:

ACTION:

PAYBYLINKPAYMENT, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONEXPIRY:

string, required Max length: 6 Default value: '168h' Session expiry time, default value is 7 days ( 7x24 hours ).

MERCHANTPAYMENTID:

string, required Max length: 128 Unique Payment ID given by Merchant.

AMOUNT:

decimal, required Max length: 30 Amount of payment / transaction. Please note that, this amount is tax included, ZiraatPay doesn't consider any other tax calculation.

CURRENCY:

string, required Max length: 3 ISO Alpha transaction currency code like TRY, EUR, USD, GBP. Please check https://en.wikipedia.org/wiki/ISO_4217#Position_of_ISO_4217_code_in_amounts for details. See all possible values (33)

CUSTOMER:

string, required Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

RETURNURL:

string, optional Max length: 512 Return URL after successful / failed payment.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CUSTOMEREMAIL:

string, conditional Max length: 64 Customer e-mail. This information should be passed correctly if the customer information services are used.

CUSTOMERNAME:

string, conditional Max length: 128 Name of the Customer. This information should be passed correctly if the customer information services are used.

CUSTOMERPHONE:

string, optional Max length: 64 Customer phone / mobile number. This information should be passed correctly if the customer information services are used.

TCKN:

string, optional Max length: 11 Customer Identity Number.

LANGUAGE:

string, optional Max length: 2 Default value: 'tr' Locale of pages displayed during payment.

ORDERITEMS:

string, optional Max length: 100000 Order items as array in JSON Format. Order items should be URL encoded. Please see the request samples for valid JSON data format.

NOTIFICATIONCHANNELS:

string, optional Max length: 16 The NOTIFICATIONCHANNELS parameter is used to specify notification channels. If more than one channel is to be notified, the channel must be combined (with a comma). Ex: EMAIL,SMS

BILLTOADDRESSLINE:

string, optional Max length: 255 Bill To Address Line

BILLTOCITY:

string, optional Max length: 32 Bill To City

BILLTOPOSTALCODE:

string, optional Max length: 16 Bill To Postal Code

BILLTOCOUNTRY:

string, optional Max length: 32 Bill To Country
An alpha-3 code in ISO 3166-1 standard should be sent.

BILLTOPHONE:

string, optional Max length: 32 Phone number of billment information

SHIPTOADDRESSLINE:

string, optional Max length: 255 Ship To Address Line

SHIPTOCITY:

string, optional Max length: 32 Ship To City

SHIPTOPOSTALCODE:

string, optional Max length: 32 Ship To Postal Code

SHIPTOCOUNTRY:

string, optional Max length: 32 Ship To Country
An alpha-3 code in ISO 3166-1 standard should be sent.

SHIPTOPHONE:

string, optional Max length: 32 Phone number of shipment information

EXTRA:

string, optional Max length: 4000 Extra Parameter is a custom parameter that is used to pass additional parameters to session token. This parameter is expected to be in JSON(URL-ENCODED) format. If they are mispelled, they will be ignored! Supported parameters are: CardHolderAgreementMode(value: NONE/SHOW/SHOWCHECKED/SHOWCHECKEDDISABLED), AlwaysSaveCard(value: true/false), BuyerType (value: L for logged in customer; A for anonymous, F for the first shopping with memebership. OR it can be 0, 1, 2 for those cases), IsbankBolumKodu(string), IframeDomainUrl indicates from which URL address payment will be proceesed., PREAUTH=YES parameter indicates that payment will be processed as pre-authorization even if is started as sale., IGNORECUSTOMERCOMMISSION(values : YES/NO).
EXTRA: {"AlwaysSaveCard": "true", "BuyerType": "L", "IsbankBolumKodu": 12, "CardHolderAgreementMode": "SHOWCHECKED", "IGNORECUSTOMERCOMMISSION" : "YES"}

Other bank parameters

• MAXIMUMMOBIL - include Maximum Mobil payment system name like below to have Maximum Mobil tab on Default HPP
  {"MaximumMobilPaymentSystem":"PaymentSystemName"}
• GIROGATE payment methods. If one of payment methods is sent as "Yes", authentication will be done using GiroGate payment methods. Possible values: YES/NO.
  • SOFORT: {"SOFORT": "YES"}
  • SAFETYPAY: {"SAFETYPAY": "YES"}
  • QIWI: {"QIWI": "YES"}
  • GIROPAY: {"GIROPAY": "YES"}
  • IDEAL: {"IDEAL": "YES"}
  • FINNISHONLINEBANKING: {"FINNISHONLINEBANKING": "YES"}
  • BANCONTACT: {"BANCONTACT": "YES"}
  • ALIPAY: {"ALIPAY": "YES"}
  • MULTIBANCO: {"MULTIBANCO": "YES"}
  • TRUSTPAY: {"TRUSTPAY": "YES"}
  • EPS: {"EPS": "YES"}
  • MYBANK: {"MYBANK": "YES"}
  • P24: {"P24": "YES"}
  • BOLETO: {"BOLETO": "YES"}
  • ELO: {"ELO": "YES"}
  • SEPA: {"SEPA": "YES"}
  • UPOP: {"UPOP": "YES"}
• ISBANK - include in extra like below to send agriculture template info to Isbank when doing imece card operations.
  {"IMCKOD":"imckod", "FDONEM":"fdonem"}

					
ACTION: PAYBYLINKPAYMENT   
MERCHANTUSER: [MERCHANTUSER]   
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT]
CUSTOMER: Customer-UCUoumJV   
SESSIONTYPE: PAYMENTSESSION   
MERCHANTPAYMENTID: Payment-UCUoumJV   
AMOUNT: 10.00   
CURRENCY: TRY   
CUSTOMEREMAIL: customerEmail-UCUoumJV   
CUSTOMERNAME: CustomerNameUCUoumJV   
CUSTOMERPHONE: 123456789     
RETURNURL: http://merchantReturnUrl
SESSIONTYPE: PAYMENTSESSION
SESSIONEXPIRY: 168h
EXTRA:[
	{ 
		"IsbankBolumKodu": 1
	}
     ]  
ORDERITEMS:[ 
        { 
            "code": "T00D3AITCC", 
            "name": "Galaxy Note 3", 
            "description": "Description of Galaxy Note 3", 
            "quantity": 2, 
            "amount": 449.99
        }, 
        { 
            "code": "B00D9AVYBM", 
            "name": "Samsung Galaxy S III", 
            "description": "Samsung Galaxy S III (S3) Triband White (Boost Mobile)", 
            "quantity": 1, 
            "amount": 149.95 
        }, 
        { 
            "code": "B00NQGP5M8", 
            "name": "Apple iPhone 6", 
            "description": "Apple iPhone 6, Gold, 64 GB (Unlocked) by Apple", 
            "quantity": 1, 
            "amount": 139.95 
        }, 
        { 
            "code": "B00U8KSUIG", 
            "name": "Samsung Galaxy S6", 
            "description": "Samsung Galaxy S6 SM-G920F 32GB (FACTORY UNLOCKED) 5.1 QHDBlack-InternationalVersion", 
            "quantity": 1, 
            "amount": 129.95 
        } 
    ]    

					
{
  "sessionToken" : "HZ3JBAFJ72AJTWRR75JOKWTFHMVHG7Y6UH6VTAGABLMV7LID",
  "responseCode" : "00",
  "responseMsg" : "Approved"
}
				

Cancel Pay by Link Payment

The PAYBYLINKPAYMENTCANCEL action is used for cancelling a Pay By Link Payment

Request parameters:

ACTION:

PAYBYLINKPAYMENTCANCEL, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

PAYBYLINKTOKEN:

string, required Max length: 48 description

					
ACTION: PAYBYLINKPAYMENTCANCEL   
MERCHANTUSER: [MERCHANTUSER]   
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT] 
PAYBYLINKTOKEN: [PAYBYLINKTOKEN] 

					
{
  "responseCode" : "00",
  "responseMsg" : "Approved"
}
				

Resend Pay by Link Payment

The PAYBYLINKPAYMENTRESEND action is used for resending a remainder email to Card Holder to complete the payment

Request parameters:

ACTION:

PAYBYLINKPAYMENTRESEND, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

PAYBYLINKTOKEN:

string, required Max length: 48 description

NOTIFICATIONCHANNELS:

string, optional Max length: 16 The NOTIFICATIONCHANNELS parameter is used to specify notification channels. If more than one channel is to be notified, the channel must be combined (with a comma). Ex: EMAIL,SMS

					
ACTION: PAYBYLINKPAYMENTRESEND   
MERCHANTUSER: [MERCHANTUSER]   
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT] 
PAYBYLINKTOKEN: [PAYBYLINKTOKEN] 

					
{
  "responseCode" : "00",
  "responseMsg" : "Approved"
}
				

Recurring Plan Actions

Add Recurring Plan

The RECURRINGPLAN action is a group of payments which will be executed separately in specified / scheduled time with defined amount(s).

Request parameters:

ACTION:

RECURRINGPLANADD, required Max length: 128 Core parameter which specifies the main action for the API call.

INSTANTPAYMENT:

string, optional Max length: 3 Default value: 'NO' description See all possible values (2)

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CARDTOKEN:

string, conditional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

CARDPAN:

string, conditional Max length: 19 PAN (Primary account number), card number. Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CARDEXPIRY:

string, conditional Max length: 7 Expiry date of the card. Format should be [mm.yy].

NAMEONCARD:

string, conditional Max length: 64 Name on the card.

CARDSAVENAME:

string, optional Max length: 64 Given name for the saved card.

CUSTOMER:

string, conditional Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

CUSTOMERNAME:

string, optional Max length: 128 Name of the Customer. This information should be passed correctly if the customer information services are used.

CUSTOMEREMAIL:

string, required Max length: 64 Customer e-mail. This information should be passed correctly if the customer information services are used.

CUSTOMERPHONE:

string, optional Max length: 64 Customer phone / mobile number. This information should be passed correctly if the customer information services are used.

RECURRINGPLANCODE:

string, required Max length: 16 Unique code of a recurring plan.

FIRSTAMOUNT:

decimal, optional Max length: 30 Amount of the first payment of recurring plan.

RECURRINGAMOUNT:

decimal, required Max length: 30 Amount of the recurring payments.

RECURRENCECOUNT:

decimal, required Max length: 2 Default value: '1' Recurrence count of a recurring plan.

FREQUENCY:

string, required Max length: 4 Frequency of a payment. D for day, M for month, Y should be used for years. (Ex. 5D, 3M, 1Y)

STARTDATE:

date, optional Max length: 16 Format: [dd-MM-yyyy] Start date of the transaction query.

CURRENCY:

string, conditional Max length: 3 ISO Alpha transaction currency code like TRY, EUR, USD, GBP. Please check https://en.wikipedia.org/wiki/ISO_4217#Position_of_ISO_4217_code_in_amounts for details. See all possible values (33)

PAYMENTSYSTEM:

string, optional Max length: 128 Name of the payment system (bank payment gateway / vPOS account). Specified name should match the one given in ZiraatPay. If not provided, ZiraatPay smart switch feature will be used.

FORGROUP:

string, optional Max length: 3 Default value: 'YES' Specifies the for group featured usages. Available values are 'yes' and 'no'.

ORDERITEMS:

string, optional Max length: 100000 Order items as array in JSON Format. Order items should be URL encoded. Please see the request samples for valid JSON data format.

TOTALSELLERCOMMISSIONAMOUNT:

decimal, optional Max length: 30 description

TOTALSELLERPAYMENTAMOUNT:

decimal, optional Max length: 30 description

					ACTION: RECURRINGPLANADD   
INSTANTPAYMENT: YES		
MERCHANTUSER: [MERCHANTUSER]   
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT]  
CUSTOMER: merchant-2yQZyloV
CUSTOMERNAME: CustomerName 2yQZyloV
CUSTOMEREMAIL: 2yQZyloV@email.com
CARDPAN: 4242420000004242
CARDEXPIRY: 12.2020
NAMEONCARD: Test User
RECURRINGPLANCODE: Code-JSjAuDXf
FIRSTAMOUNT: 1.00
RECURRINGAMOUNT: 100.00
RECURRENCECOUNT: 5
FREQUENCY: 5D
CURRENCY: TRY
STARTDATE: 01-10-2015
PAYMENTSYSTEM: GarantiPOS     

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "recurringPlanCode" : "Code-JSjAuDXf"
}
				

Edit Recurring Plan

Edit Recurring Plan

The RECURRINGPLANEDIT is an action that allows you to change some properties of Recurring Plans and Recurring Payments. You can change STATUS, CARD INFORMATION, RECURRING AMOUNT and PAYMENT SYSTEM of recurring plan and STATUS, START DATE and AMOUNT of a specific recurring payment.

Request parameters:

ACTION:

RECURRINGPLANEDIT, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

RECURRINGPLANCODE:

string, required Max length: 16 Unique code of a recurring plan.

RECURRINGSTATUS:

string, optional Max length: 16 Recurring Plan and Recurring Payment status.

RECURRINGAMOUNT:

decimal, optional Max length: 30 Amount of the recurring payments.

PAYMENTSYSTEM:

string, optional Max length: 128 Name of the payment system (bank payment gateway / vPOS account). Specified name should match the one given in ZiraatPay. If not provided, ZiraatPay smart switch feature will be used.

RECURRENCE:

decimal, optional Max length: 2 Recurring Payment order which will be edited.

STARTDATE:

date, optional Max length: 16 Format: [dd-MM-yyyy] Start date of the transaction query.

AMOUNT:

decimal, optional Max length: 30 Amount of payment / transaction. Please note that, this amount is tax included, ZiraatPay doesn't consider any other tax calculation.

					ACTION: RECURRINGPLANEDIT   
MERCHANTUSER: [MERCHANTUSER]   
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANT: [MERCHANT]  
CARDPAN: 
CARDEXPIRY: 
NAMEONCARD: 
RECURRINGPLANCODE: Code-JSjAuDXf
RECURRINGAMOUNT: 50.00
RECURRINGSTATUS: INACTIVE
RECURRENCECOUNT:
STARTDATE: 
AMOUNT:
PAYMENTSYSTEM:      

					{
  "action" : "RECURRINGPLANEDIT",
  "responseCode" : "00",
  "responseMsg" : "Approved"
}
				

Recurring Plan Card Actions

Add Recurring Plan Card

RECURRINGPLANCARDADD action lets you to add card and relate it to recurring plan.

Request parameters:

ACTION:

RECURRINGPLANCARDADD, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

RECURRINGPLANCODE:

string, required Max length: 16 Unique code of a recurring plan.

CARDTOKEN:

string, conditional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

CARDPAN:

string, conditional Max length: 19 PAN (Primary account number), card number. Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CARDEXPIRY:

string, conditional Max length: 7 Expiry date of the card. Format should be [mm.yy].

NAMEONCARD:

string, conditional Max length: 64 Name on the card.

CARDSAVENAME:

string, optional Max length: 64 Given name for the saved card.

					ACTION: RECURRINGPLANCARDADD   
MERCHANT: [MERCHANT]  
MERCHANTUSER: [MERCHANTUSER]   
MERCHANTPASSWORD: [MERCHANTPASSWORD]
CARDPAN: 4242420000004242
CARDEXPIRY: 12.2020
NAMEONCARD: Test User
CARDSAVENAME: Test Name
CARDTOKEN: 
RECURRINGPLANCODE: Code-JSjAuDXf   

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "cardToken" : "T45FWSAXNHZPC4NYCGVQSYY4INTCCPB3GC5MJ2HGD2YKLCG6"
}
				

Delete RecurringPlan Card

RECURRINGPLANCARDDELETE action lets you to remove relation between card and recurring plan.

Request parameters:

ACTION:

RECURRINGPLANCARDDELETE, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

RECURRINGPLANCODE:

string, required Max length: 16 Unique code of a recurring plan.

CARDTOKEN:

string, required Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

					ACTION: RECURRINGPLANCARDDELETE   
MERCHANT: [MERCHANT]  
MERCHANTUSER: [MERCHANTUSER]   
MERCHANTPASSWORD: [MERCHANTPASSWORD]
CARDTOKEN: [CARDTOKEN]
RECURRINGPLANCODE: [RECURRINGPLANCODE]

					{
  "responseCode" : "00",
  "responseMsg" : "Approved"
}
				

e-Wallet actions

Edit Card

The EWALLETEDITCARD request lets you edit the existing cards by providing their token value. The only fields that are allowed to be edited are the card’s expiry date and the saved card name.

Request parameters:

ACTION:

EWALLETEDITCARD, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CARDTOKEN:

string, required Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

CUSTOMER:

string, conditional Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

CARDEXPIRY:

string, optional Max length: 7 Expiry date of the card. Format should be [mm.yy].

NAMEONCARD:

string, optional Max length: 64 Name on the card.

CARDSAVENAME:

string, optional Max length: 64 Given name for the saved card.

					MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
ACTION: EWALLETEDITCARD
CARDTOKEN: ZP7BJ24P5HTA4EKKHMOAEAPWJWSWKMCKQ54EWK37IBAEUPPN
CARDSAVENAME: My Card Name (New)
CARDEXPIRY: 12.2020     
				

					{
    "cardToken":"ZP7BJ24P5HTA4EKKHMOAEAPWJWSWKMCKQ54EWK37IBAEUPPN",
    "responseCode":"00",
    "responseMsg":"Approved"
}                       
				

Delete Card

The EWALLETDELETECARD request allows you to remove customer cards from ZiraatPay system. Once a card is removed it cannot be queried, edited or used for any kind of payment. The ewalletremove request can be sent to ZiraatPay using the following fields:

Request parameters:

ACTION:

EWALLETDELETECARD, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CARDTOKEN:

string, required Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

					ACTION: EWALLETDELETECARD
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
CARDTOKEN: ZP7BJ24P5HTA4EKKHMOAEAPWJWSWKMCKQ54EWK37IBAEUPPN
				

					{
    "responseCode":"00",
    "responseMsg":"Approved"
}                       
				

Seller Actions

Add Seller

The SELLERADD action lets you add a seller. You should give the required parameters also optional parameters like TCKN.

Request parameters:

ACTION:

SELLERADD, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SELLERID:

string, required Max length: 32 Unique value per seller.

NAME:

string, required Max length: 512 Name

LASTNAME:

string, required Max length: 512 description

EMAIL:

string, required Max length: 512 description

MOBILENUMBER:

string, required Max length: 64 description

TCKN:

string, conditional Max length: 11 Customer Identity Number.

VKN:

string, conditional Max length: 10 Tax identification number

IBAN:

string, required Max length: 34 description

IBANUSD:

string, optional Max length: 34 description

IBANEUR:

string, optional Max length: 34 description

IBANGBP:

string, optional Max length: 34 description

SELLERPAYMENTDAYS:

string, required Max length: 32 Seller payment days should be sent in index format, separated with semicolon. Indexes for days are as follow: Monday(0), Tuesday(1), Wednesday(2), Thursday(3), Friday(4). Example for seller payment days to be on Monday and Friday, the value of SELLERPAYMENTDAYS parameter should be sent as follow: 0;4;

ACCOUNTOWNERNAME:

string, conditional Max length: 512 description

ACCOUNTOWNERLASTNAME:

string, conditional Max length: 512 description

SELLERPAYMENTDUEDAY:

integer, optional Max length: 2 description

COMMERCIALTITLE:

string, conditional Max length: 512 description

STATUS:

string, optional Max length: 2 Status information. See all possible values (4)

COMMISSIONAPPLYTYPE:

string, conditional Max length: 3 Only CA parameter is available for COMMISSIONAPPLYTYPE. Other parameters are not applicable See all possible values (3)

COMMISSIONAPPLIERTYPE:

string, conditional Max length: 3 Only CA parameter is available for COMMISSIONAPPLIERTYPE. Other parameters are not applicable See all possible values (3)

COMMISSIONVALUE:

decimal, optional Max length: 30 description

ONBEHALFOFMERCHANT:

string, optional Max length: 16 description

SELLERURL:

string, optional Max length: 256 description

ISDEFAULT:

string, optional Max length: 3 Default value: 'NO' description

					ACTION: SELLERADD
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
SELLERID: [SELLER ID]
NAME: [SELLER NAME]
LASTNAME: [SELLER LASTNAME]
EMAIL: [seller@email.com]
MOBILENUMBER: [1234567890]
TCKN: [012345678911]
SELLERPAYMENTDUEDAY: [2]

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "seller" : {
    "sellerId" : "Seller-vd6ShJUF",
    "name" : "Seller01",
    "lastName" : "LastName-XKGo",
    "email" : "seler01@email.com",
    "mobileNumber" : "+900408866157",
    "status" : "WA",
    "sellerpaymentdueday" : "2",
    "merchant" : {
      "businessId" : "10000000",
      "name" : "MSU Test Merchant",
      "address" : "İTÜ Ayazağa Kampüsü Teknokent ARI 1 Binası No: 12 34469 Maslak",
      "phone" : "+902123650505",
      "webAddress" : "http://www.asseco-see.com.tr/"
    }
  }
}
				

Edit Seller

The SELLEREDIT action lets you edit an existing seller. You should provide seller id and merchant and you can update name, last name, mobile number, email, TCKN and status.

Request parameters:

ACTION:

SELLEREDIT, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SELLERID:

string, required Max length: 32 Unique value per seller.

NAME:

string, optional Max length: 512 Name

LASTNAME:

string, optional Max length: 512 description

EMAIL:

string, optional Max length: 512 description

MOBILENUMBER:

string, optional Max length: 64 description

STATUS:

string, optional Max length: 2 Status information. See all possible values (4)

TCKN:

string, conditional Max length: 11 Customer Identity Number.

VKN:

string, conditional Max length: 10 Tax identification number

IBAN:

string, required Max length: 34 description

IBANUSD:

string, optional Max length: 34 description

IBANEUR:

string, optional Max length: 34 description

IBANGBP:

string, optional Max length: 34 description

SELLERPAYMENTDAYS:

string, required Max length: 32 Seller payment days should be sent in index format, separated with semicolon. Indexes for days are as follow: Monday(0), Tuesday(1), Wednesday(2), Thursday(3), Friday(4). Example for seller payment days to be on Monday and Friday, the value of SELLERPAYMENTDAYS parameter should be sent as follow: 0;4;

ACCOUNTOWNERNAME:

string, conditional Max length: 512 description

ACCOUNTOWNERLASTNAME:

string, conditional Max length: 512 description

SELLERPAYMENTDUEDAY:

integer, optional Max length: 2 description

COMMERCIALTITLE:

string, conditional Max length: 512 description

COMMISSIONAPPLYTYPE:

string, conditional Max length: 3 Only CA parameter is available for COMMISSIONAPPLYTYPE. Other parameters are not applicable See all possible values (3)

COMMISSIONAPPLIERTYPE:

string, conditional Max length: 3 Only CA parameter is available for COMMISSIONAPPLIERTYPE. Other parameters are not applicable See all possible values (3)

COMMISSIONVALUE:

decimal, optional Max length: 30 description

ONBEHALFOFMERCHANT:

string, optional Max length: 16 description

SELLERURL:

string, optional Max length: 256 description

ISDEFAULT:

string, optional Max length: 3 Default value: 'NO' description

					ACTION: SELLEREDIT
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
SELLERID: [SELLER ID]
NAME: []
LASTNAME: []
EMAIL: []
MOBILENUMBER: []
TCKN: []
STATUS: []
SELLERPAYMENTDUEDAY: []

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "seller" : {
    "sellerId" : "Seller-vd6ShJUF",
    "name" : "Seller01",
    "lastName" : "LastName-XKGo",
    "email" : "seler01@email.com",
    "mobileNumber" : "+900408866157",
    "status" : "OK",
    "sellerpaymentdueday" :  "2"
    "merchant" : {
      "businessId" : "10000000",
      "name" : "MSU Test Merchant",
      "address" : "İTÜ Ayazağa Kampüsü Teknokent ARI 1 Binası No: 12 34469 Maslak",
      "phone" : "+902123650505",
      "webAddress" : "http://www.asseco-see.com.tr/"
    }
  }
}
		

Seller Payment Date Update

Update the payment date of a seller transaction

Request parameters:

ACTION:

UPDATEPAYMENTDATE, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTPAYMENTID:

string, optional Max length: 128 Unique Payment ID given by Merchant.

PGTRANID:

string, optional Max length: 64 Transaction ID given by payment gateway.

ORDERITEMS:

string, required Max length: 4096 Order items as array in JSON Format. Order items should be URL encoded. Please see the request samples for valid JSON data format.

					ACTION: UPDATESELLERPAYMENTDATE
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
SESSIONTOKEN: [SESSIONTOKEN]
MERCHANTPAYMENTID: [MERCHANTPAYMENTID]
PGTRANID: [21127PnXF19482]
ORDERITEMS: [ URLEncoded [{"pgTranId": "23268LaVH13763","merchantPaymentDate":"08.04.2024"},{"pgTranId": "23263Q7kC16459","merchantPaymentDate":"08.04.2024"}] ]

					{
    "responseCode": "00",
    "responseMsg": "Approved"
}
				

Application Actions

Add Application

The APPLICATIONADD action lets you add a application. You should give the required parameters.

Request parameters:

ACTION:

APPLICATIONADD, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

APPLICATIONNAME:

string, required Max length: 256 description

APPLICATIONEMAIL:

string, required Max length: 64 description

APPLICATIONPHONE:

string, required Max length: 64 description

APPLICATIONWEBADDRESS:

string, required Max length: 256 description

APPLICATIONTURNOVER:

string, required Max length: 256 description

APPLICATIONCOMPANYTYPE:

string, optional Max length: 16 description See all possible values (4)

APPLICATIONSHAREHOLDERS:

string, optional Max length: 100000 description

APPLICATIONMERCHANT:

string, optional Max length: 100000 description

APPLICATIONFINANCIALDATA:

string, optional Max length: 100000 description

APPLICATIONSALESUPPORTDATA:

string, optional Max length: 100000 description

APPLICATIONRISKMANAGEMENTDATA:

string, optional Max length: 100000 description

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

					ACTION: APPLICATIONADD
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
APPLICATIONNAME: [APPLICATIONNAME]
APPLICATIONEMAIL: [APPLICATIONEMAIL]
APPLICATIONPHONE: [APPLICATIONPHONE]
APPLICATIONWEBADDRESS: [APPLICATIONWEBADDRESS]
APPLICATIONTURNOVER: [APPLICATIONTURNOVER]
APPLICATIONCOMPANYTYPE: [APPLICATIONCOMPANYTYPE]
APPLICATIONSHAREHOLDERS:[APPLICATIONSHAREHOLDERS]
APPLICATIONMERCHANT:[APPLICATIONMERCHANT]
APPLICATIONSALESUPPORTDATA:[APPLICATIONSALESUPPORTDATA]
APPLICATIONRISKMANAGEMENTDATA:[APPLICATIONRISKMANAGEMENTDATA]

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "application" : {
    "applicationName" : "Application Name",
    "applicationEmail" : "Application Email",
    "applicationPhone" : "Application Phone",
    "applicationWebAddress" : "www.google.com",
    "applicationTurnover" : "Application Turnover",
    "applicationCompanyType" : "Application company type",
    "applicationDate": "2022-04-01 08:23:28.211",
    "applicationCode": "UKKYXGJNUFEJIHSBUS4MR3S3G2ODAE7QY53LLCMEZ7H7SJSB",
    "applicationStatus": "PA",
    "applicationShareholders":[
            {
                "name": "002",
                "surname": "002",
                "phone": "+38345698325",
                "email": "002@gmail.com",
                "idNumber": "002",
                "signAuthority": "YES",
                "signAuthorityDuration": "01-02-2026 01:00"
            },
            {
                "name": "001",
                "surname": "001",
                "phone": "+38345698325",
                "email": "001@gmail.com",
                "idNumber": "001",
                "signAuthority": "NO",
                "signAuthorityDuration": "01-02-2026 01:00"
            }
        ],
     "applicationMerchant": [
            {
                "commercialTitle": "123",
                "name": "123",
                "surname": "123",
                "email": "123@email.com",
                "phoneNumber": "+38345698325",
                "landPhone": "+3834569832",
                "address": "123",
                "eCommerce": "123"
            }
        ],
       "applicationFinancialData": {
            "merchantCommissionSchema": "MCS_ZERO_COMMISSION",
            "paymentSystemPool": "testPaymentSystemPool"
        },
        "applicationSaleSupportData": {
             "ssl": "test_ssl2",
             "content": "test_content2",
             "whois": "test_whois",
             "tradeRegistryNumber": "test_tradeRegistryNumber"
        },
         "applicationRiskManagmentDataVo": {
            "kkbPoint": "kkbPoint",
            "mcc": "1352",
            "threeDCondition": "THD_ALL",
            "threeDLimit": "0",
            "complaintRecord": "complaintRecord",
            "product": "DON",
            "contractSigned": "YES",
            "blockageTimeAndDay": "",
            "integrationModel": "API",
            "guaranteeAmount": "50.5",
            "guaranteeAmountStartDate": "01-02-2026 01:00",
            "guaranteeAmountEndDate": "01-02-2026 01:00",
            "foreignCardPermission": "YES"
        }
  }
}
	

Edit Application

The APPLICATIONEDIT option lets you edit an application. You should give the required parameters name and email and send the optional parameters that you want to edit.

Request parameters:

ACTION:

APPLICATIONEDIT, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

APPLICATIONNAME:

string, conditional Max length: 256 description

APPLICATIONEMAIL:

string, conditional Max length: 64 description

APPLICATIONCODE:

string, optional Max length: 64 Application code

APPLICATIONPHONE:

string, optional Max length: 64 description

APPLICATIONWEBADDRESS:

string, optional Max length: 256 description

APPLICATIONTURNOVER:

string, optional Max length: 256 description

APPLICATIONCOMPANYTYPE:

string, optional Max length: 16 description See all possible values (4)

APPLICATIONSTATUS:

string, optional Max length: 16 description See all possible values (23)

APPLICATIONSHAREHOLDERS:

string, optional Max length: 100000 description

APPLICATIONSIGNAUTHORITIES:

string, optional Max length: 100000 description

APPLICATIONMERCHANT:

string, optional Max length: 100000 description

APPLICATIONDOCUMENTDATA:

string, optional Max length: 10000000 description

APPLICATIONFINANCIALDATA:

string, optional Max length: 100000 description

APPLICATIONSALESUPPORTDATA:

string, optional Max length: 100000 description

APPLICATIONRISKMANAGEMENTDATA:

string, optional Max length: 100000 description

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

					ACTION: APPLICATIONEDIT
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
APPLICATIONNAME: [APPLICATIONNAME]
APPLICATIONEMAIL: [APPLICATIONEMAIL]
APPLICATIONPHONE: [APPLICATIONPHONE]
APPLICATIONWEBADDRESS: [APPLICATIONWEBADDRESS]
APPLICATIONTURNOVER: [APPLICATIONTURNOVER]
APPLICATIONCOMPANYTYPE: [APPLICATIONCOMPANYTYPE]
APPLICATIONSTATUS:[APPLICATIONSTATUS]
APPLICATIONSHAREHOLDERS:[APPLICATIONSHAREHOLDERS]
APPLICATIONMERCHANT:[APPLICATIONMERCHANT]
APPLICATIONSALESUPPORTDATA:[APPLICATIONSALESUPPORTDATA]
APPLICATIONDOCUMENTDATA:[APPLICATIONDOCUMENTDATA]
APPLICATIONRISKMANAGEMENTDATA:[APPLICATIONRISKMANAGEMENTDATA]

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "application" : {
    "applicationName" : "Application Name",
    "applicationEmail" : "Application Email",
    "applicationPhone" : "Application Phone",
    "applicationWebAddress" : "www.google.com",
    "applicationTurnover" : "Application Turnover",
    "applicationStatus" : "Application status",
    "applicationCompanyType" : "Application company type",
    "applicationDate": "2022-04-01 08:23:28.211",
    "applicationCode": "UKKYXGJNUFEJIHSBUS4MR3S3G2ODAE7QY53LLCMEZ7H7SJSB",
    "applicationShareholders":[
            {
                "name": "002",
                "surname": "002",
                "phone": "+38345698325",
                "email": "002@gmail.com",
                "idNumber": "002",
                "signAuthority": "YES",
                "signAuthorityDuration": "01-02-2026 01:00"
            },
            {
                "name": "001",
                "surname": "001",
                "phone": "+38345698325",
                "email": "001@gmail.com",
                "idNumber": "001",
                "signAuthority": "NO",
                "signAuthorityDuration": "01-02-2026 01:00"
            }
        ],
     "applicationMerchant": [
            {
                "commercialTitle": "123",
                "name": "123",
                "surname": "123",
                "email": "123@email.com",
                "phoneNumber": "+38345698325",
                "landPhone": "+3834569832",
                "address": "123",
                "eCommerce": "123"
            }
        ],
      "applicationFinancialData": {
            "merchantCommissionSchema": "MCS_ZERO_COMMISSION",
            "paymentSystemPool": "testPaymentSystemPool"
        },
      "applicationSaleSupportData": {
             "ssl": "test_ssl2",
             "content": "test_content2",
             "whois": "test_whois",
             "tradeRegistryNumber": "test_tradeRegistryNumber"
        },
       "applicationDocumentData": [
        {
            "fileType": "JPEG",
            "fileContent": "iLe+8q38tU8zEAOSimLdxx8ZQWMHY4HbOMDIUX6ygt/W8dBAKBQCAQCAQCgUAgEAgEAuFkwP8ATX9UIiXmF98AAAAASUVORK5CYII=",
            "documentType": "IDENTITY",
            "fileName": "fileName"
        }
    ],
     "applicationRiskManagmentDataVo": {
            "kkbPoint": "kkbPoint",
            "mcc": "1352",
            "threeDCondition": "THD_ALL",
            "threeDLimit": "0",
            "complaintRecord": "complaintRecord",
            "product": "DON",
            "contractSigned": "YES",
            "blockageTimeAndDay": "",
            "integrationModel": "API",
            "guaranteeAmount": "50.5",
            "guaranteeAmountStartDate": "01-02-2026 01:00",
            "guaranteeAmountEndDate": "01-02-2026 01:00",
            "foreignCardPermission": "YES"
        }
  }
}
	

Query Application

The QUERYAPPLICATION action lets you query a application. You should give the required parameters.

Request parameters:

ACTION:

QUERYAPPLICATION, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

APPLICATIONNAME:

string, optional Max length: 256 description

APPLICATIONEMAIL:

string, optional Max length: 64 description

APPLICATIONCODE:

string, optional Max length: 64 Application code

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

					ACTION: QUERYAPPLICATION
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
   "applications": [{
    "applicationName" : "Application Name",
    "applicationEmail" : "Application Email",
    "applicationPhone" : "Application Phone",
    "applicationWebAddress" : "www.google.com",
    "applicationTurnover" : "Application Turnover",
    "applicationStatus" : "Application status",
    "applicationCompanyType" : "Application company type",
    "applicationCode": "UKKYXGJNUFEJIHSBUS4MR3S3G2ODAE7QY53LLCMEZ7H7SJSB"
        "applicationShareholders":[
            {
                "name": "002",
                "surname": "002",
                "phone": "+38345698325",
                "email": "002@gmail.com",
                "idNumber": "002",
                "signAuthority": "YES",
                "signAuthorityDuration": "01-02-2026 01:00"
            },
            {
                "name": "001",
                "surname": "001",
                "phone": "+38345698325",
                "email": "001@gmail.com",
                "idNumber": "001",
                "signAuthority": "NO",
                "signAuthorityDuration": "01-02-2026 01:00"
            }
        ],
     "applicationMerchant": [
            {
                "commercialTitle": "123",
                "name": "123",
                "surname": "123",
                "email": "123@email.com",
                "phoneNumber": "+38345698325",
                "landPhone": "+3834569832",
                "address": "123",
                "eCommerce": "123"
            }
        ],
       "applicationFinancialData": {
            "merchantCommissionSchema": "MCS_ZERO_COMMISSION",
            "paymentSystemPool": "testPaymentSystemPool"
        },
        "applicationSaleSupportData": {
             "ssl": "test_ssl2",
             "content": "test_content2",
             "whois": "test_whois",
             "tradeRegistryNumber": "test_tradeRegistryNumber"
        },
         "applicationRiskManagmentDataVo": {
            "kkbPoint": "kkbPoint",
            "mcc": "1352",
            "threeDCondition": "THD_ALL",
            "threeDLimit": "0",
            "complaintRecord": "complaintRecord",
            "product": "DON",
            "contractSigned": "YES",
            "blockageTimeAndDay": "",
            "integrationModel": "API",
            "guaranteeAmount": "50.5",
            "guaranteeAmountStartDate": "01-02-2026 01:00",
            "guaranteeAmountEndDate": "01-02-2026 01:00",
            "foreignCardPermission": "YES"
        }
     }]  
}
	

Approve Application

The APPLICATIONAPPROVE action lets you approve a application. You should give the required parameters.

Request parameters:

ACTION:

APPLICATIONAPPROVE, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

APPLICATIONEMAIL:

string, required Max length: 64 description

APPLICATIONNAME:

string, required Max length: 256 description

APPLICATIONSTATUS:

string, required Max length: 4 description See all possible values (23)

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

APPLICATIONREJECTMSG:

string, optional Max length: 256 description

					ACTION: APPLICATIONAPPROVE
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
APPLICATIONEMAIL: [APPLICATIONEMAIL]
APPLICATIONPHONE: [APPLICATIONPHONE]

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "application" : {
    "applicationName" : "Application Name",
    "applicationEmail" : "Application Email",
    "applicationPhone" : "Application Phone",
    "applicationWebAddress" : "www.google.com",
    "applicationTurnover" : "Application Turnover",
    "applicationStatus" : "Application status",
    "applicationCompanyType" : "Application company type"
  }
}
	

Currency Actions

Currency Exchange

Currency Exchange

Request parameters:

ACTION:

CURRENCYEXCHANGE, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

FROMCURRENCY:

string, required Max length: 3 description See all possible values (33)

TOCURRENCY:

string, required Max length: 3 description See all possible values (33)

AMOUNT:

decimal, optional Max length: 30 Amount of payment / transaction. Please note that, this amount is tax included, ZiraatPay doesn't consider any other tax calculation.

					ACTION: CURRENCYEXCHANGE
MERCHANTUSER: apiuser@testmerchant.com   
MERCHANTPASSWORD: Pluto321`   
MERCHANT: 10000000      
FROMCURRENCY: USD   
TOCURRENCY: TRY   
AMOUNT: 10.00 

				{
	"fromCurrency": "USD",
	"toCurrency": "TRY",
	"amount": "10.00",
	"convertedAmount": "60.62"
}
				

Edit Seller

The SELLEREDIT action lets you edit an existing seller. You should provide seller id and merchant and you can update name, last name, mobile number, email, TCKN and status.

Request parameters:

ACTION:

SELLEREDIT, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SELLERID:

string, required Max length: 32 Unique value per seller.

NAME:

string, optional Max length: 512 Name

LASTNAME:

string, optional Max length: 512 description

EMAIL:

string, optional Max length: 512 description

MOBILENUMBER:

string, optional Max length: 64 description

STATUS:

string, optional Max length: 2 Status information. See all possible values (4)

TCKN:

string, conditional Max length: 11 Customer Identity Number.

VKN:

string, conditional Max length: 10 Tax identification number

IBAN:

string, required Max length: 34 description

IBANUSD:

string, optional Max length: 34 description

IBANEUR:

string, optional Max length: 34 description

IBANGBP:

string, optional Max length: 34 description

SELLERPAYMENTDAYS:

string, required Max length: 32 Seller payment days should be sent in index format, separated with semicolon. Indexes for days are as follow: Monday(0), Tuesday(1), Wednesday(2), Thursday(3), Friday(4). Example for seller payment days to be on Monday and Friday, the value of SELLERPAYMENTDAYS parameter should be sent as follow: 0;4;

ACCOUNTOWNERNAME:

string, conditional Max length: 512 description

ACCOUNTOWNERLASTNAME:

string, conditional Max length: 512 description

SELLERPAYMENTDUEDAY:

integer, optional Max length: 2 description

COMMERCIALTITLE:

string, conditional Max length: 512 description

COMMISSIONAPPLYTYPE:

string, conditional Max length: 3 Only CA parameter is available for COMMISSIONAPPLYTYPE. Other parameters are not applicable See all possible values (3)

COMMISSIONAPPLIERTYPE:

string, conditional Max length: 3 Only CA parameter is available for COMMISSIONAPPLIERTYPE. Other parameters are not applicable See all possible values (3)

COMMISSIONVALUE:

decimal, optional Max length: 30 description

ONBEHALFOFMERCHANT:

string, optional Max length: 16 description

SELLERURL:

string, optional Max length: 256 description

ISDEFAULT:

string, optional Max length: 3 Default value: 'NO' description

					ACTION: SELLERADD
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
SELLERID: [SELLER ID]
NAME: []
LASTNAME: []
EMAIL: []
MOBILENUMBER: []
TCKN: []
STATUS: []

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "seller" : {
    "sellerId" : "Seller-vd6ShJUF",
    "name" : "Seller01",
    "lastName" : "LastName-XKGo",
    "email" : "seler01@email.com",
    "mobileNumber" : "+900408866157",
    "status" : "OK",
    "merchant" : {
      "businessId" : "10000000",
      "name" : "MSU Test Merchant",
      "address" : "İTÜ Ayazağa Kampüsü Teknokent ARI 1 Binası No: 12 34469 Maslak",
      "phone" : "+902123650505",
      "webAddress" : "http://www.asseco-see.com.tr/"
    }
  }
}
				

Customer Commission Actions

Edit Customer Commission

The EDITCUSTOMERCOMMISSION request can be used to edit customer cost commission schema.

Request parameters:

ACTION:

EDITCUSTOMERCOMMISSION, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CURRENCYCOMMISSIONS:

string, required Max length: 200000 description

ACTIVATIONDATE:

date, required Max length: 32 Format: [dd-MM-yyyy HH:mm] Activation date in Coordinated Universal Time (UTC) standard

					
ACTION: EDITCUSTOMERCOMMISSION
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
SESSIONTOKEN: [SESSIONTOKEN]
DEFAULTCOMMISSION: [DEFAULTCOMMISSION]
PAYMENTSYSTEMBASEDCOMMISSIONLIST: [PAYMENTSYSTEMBASEDCOMMISSIONLIST]
ACTIVATIONDATE: [dd-MM-yyyy HH:mm]
					
				

				
{
  "responseCode" : "00",
  "responseMsg" : "Approved"
}
				
			

OTP Actions

Add OTP

The OTPADD request can be used to generate and add a new OTP (One time password)

Request parameters:

ACTION:

OTPADD, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

EMAIL:

string, required Max length: 64 description

				
ACTION: OTPADD
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
EMAIL: [EMAIL]
				
			

				
{
	"responseCode": "00",
	"responseMsg": "Approved",
	"otp": {
		"otpCode": "107038",
		"createdTs": "2022-08-18 16:08:43.578",
		"status": "OK"
	}
}
				
			

Edit OTP

The OTPEDIT request can be used to generate and edit OTP (One time password)

Request parameters:

ACTION:

OTPEDIT, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

OTPCODE:

string, required Max length: 6 description

OTPSTATUS:

string, required Max length: 2 description See all possible values (4)

EMAIL:

string, required Max length: 64 description

				
ACTION: OTPEDIT
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
EMAIL: [EMAIL]
				
			

				
{
	"responseCode": "00",
	"responseMsg": "Approved",
	"otp": {
		"otpCode": "107038",
		"createdTs": "2022-08-18 16:08:43.578",
		"status": "OK"
	}
}
				
			

Bin Rule Actions

Add Bin Rule

The BINRULEADD request can be used to generate and add a new Bin Rule

Request parameters:

ACTION:

BINRULEADD, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

RULENAME:

string, required Max length: 128 Bin Rule

CARDBRAND:

string, conditional Max length: 8 description See all possible values (9)

CARDTYPE:

string, conditional Max length: 8 description See all possible values (6)

CARDNETWORK:

string, conditional Max length: 8 description See all possible values (10)

ISSUER:

string, conditional Max length: 128 description

COUNTRYISOA3:

string, conditional Max length: 3 description

LOWERLIMIT:

decimal, optional Max length: 22 description

UPPERLIMIT:

decimal, optional Max length: 22 description

STATUS:

string, required Max length: 2 Status information. See all possible values (4)

INSTALLMENTTYPE:

string, optional Max length: 64 description See all possible values (2)

INSTALLMENTCOUNT:

integer, optional Max length: 2 Default value: '1' description

				
ACTION: BINRULEADD
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
RULENAME: [RULENAME]
STATUS: [STATUS]
CARDBRAND: [CARDBRAND]
CARDTYPE: [CARDTYPE]
CARDNETWORK: [CARDNETWORK]
COUNTRYISOA3: [COUNTRYISOA3]
ISSUER: [ISSUER]
LOWERLIMIT: [LOWERLIMIT]
UPPERLIMIT: [UPPERLIMIT]
INSTALLMENTTYPE: [INSTALLMENTTYPE]
INSTALLMENTCOUNT: [INSTALLMENTCOUNT]
				
			

				
{
    "responseCode": "00",
    "responseMsg": "Approved",
    "binRule": {
        "ruleName": "TEST11",
        "cardBrand": "VISA",
        "cardType": "DEBIT",
        "countryIsoA3": "ALB",
        "issuer": "test11",
        "cardNetwork": "WORLD",
        "lowerLimit": 2.5,
        "upperLimit": 3.7,
        "status": "OK",
        "installmentType": MULTIPLESHOT,
        "installmentCount": 3      
    }

				

Query Bin Rule

The QUERYBINRULE Query bin rule can be used to get all bin rules on the system

Request parameters:

ACTION:

QUERYBINRULE, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

RULENAME:

string, optional Max length: 128 Bin Rule

				
ACTION: QUERYBINRULE
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
RULENAME: [RULENAME]
				
			

				
{
    "responseCode": "00",
    "responseMsg": "Approved",
    "binRules": [
        {
            "ruleName": "TESTDEMO19",
            "cardBrand": "VISA",
            "cardType": "CREDIT",
            "countryIsoA3": "TUR",
            "issuer": "test11",
            "cardNetwork": "WORLD",
            "lowerLimit": 2.5,
            "upperLimit": 3.7,
            "status": "OK",
            "installmentType": MULTIPLESHOT,
       		"installmentCount": 3
        }   "status": "OK"
        },
        {
            "ruleName": "RuleForTest",
            "cardBrand": "MC",
            "countryIsoA3": "TUR",
            "issuer": "test11",
            "cardNetwork": "WORLD",
            "lowerLimit": 2.5,
            "upperLimit": 3.7,
            "status": "OK",
            "installmentType": ONESHOT,
       		"installmentCount": 1            
        }
    ]
}
				

Delete Bin Rule

The BINRULEDELETE request can be used to delete an existing Bin Rule

Request parameters:

ACTION:

BINRULEDELETE, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

RULENAME:

string, required Max length: 128 Bin Rule

				
ACTION: BINRULEDELETE
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
RULENAME: [RULENAME]
				
			

				
{
	"responseCode": "00",
	"responseMsg": "Approved"
}
				
			

Edit Bin Rule

The BINRULEEDIT request can be used to edit an existing Bin Rule

Request parameters:

ACTION:

BINRULEEDIT, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

RULENAME:

string, required Max length: 128 Bin Rule

CARDBRAND:

string, conditional Max length: 8 description See all possible values (9)

CARDTYPE:

string, conditional Max length: 8 description See all possible values (6)

CARDNETWORK:

string, conditional Max length: 8 description See all possible values (10)

ISSUER:

string, conditional Max length: 128 description

COUNTRYISOA3:

string, conditional Max length: 3 description

LOWERLIMIT:

decimal, optional Max length: 22 description

UPPERLIMIT:

decimal, optional Max length: 22 description

STATUS:

string, optional Max length: 2 Status information. See all possible values (4)

INSTALLMENTTYPE:

string, optional Max length: 64 description See all possible values (2)

INSTALLMENTCOUNT:

integer, optional Max length: 2 Default value: '1' description

				
ACTION: BINRULEEDIT
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
RULENAME: [RULENAME]
STATUS: [STATUS]
CARDBRAND: [CARDBRAND]
CARDTYPE: [CARDTYPE]
CARDNETWORK: [CARDNETWORK]
COUNTRYISOA3: [COUNTRYISOA3]
ISSUER: [ISSUER]
LOWERLIMIT: [LOWERLIMIT]
UPPERLIMIT: [UPPERLIMIT]
INSTALLMENTTYPE: [INSTALLMENTTYPE]
INSTALLMENTCOUNT: [INSTALLMENTCOUNT]
				
			

				
{
    "responseCode": "00",
    "responseMsg": "Approved",
    "binRule": {
        "ruleName": "TEST12",
        "cardBrand": "VISA",
        "cardType": "DEBIT",
        "countryIsoA3": "ALB",
        "issuer": "test12",
        "cardNetwork": "WORLD",
        "lowerLimit": 2.7,
        "upperLimit": 3.9,
        "status": "OK",
        "installmentType": "MULTIPLESHOT",
        "installmentCount": "4"
    }
}
				
			

Merchant Settings

The MERCHANTSETTINGSEDIT Merchant Settings Edit

This api call lets you update existing merchant settings such as STATUS, PAYMENT POLICY OR THREE D RESTRICTIONS.
Payment Policy Values: THD_ALL (Always use 3D Secure/Her zaman 3D Güvenlik kullan) THD_OPT (3D Secure is optional(Card Holder decides)/ Kart sahibi (Müşteri) isterse, 3D Güvenlik kullan) THD_BASED_ON_LIMIT (Use 3D Secure depending on the Transaction Amount / İşlem miktarına göre 3D kullan) THD_OPT_SAVED_CARDS (Always 3D for new cards, optional 3D for saved cards/Yeni kartlarda her zaman, kayıtlı kartlarda müşteri isterse 3D Güvenlik kullan)
Three D Restriction Values: NO_RESTRICTION (No 3D restriction/3D kısıtlaması yok FULL_THD (Only allow Full-3D secure transactions (mdStatus=1) / Sadece Full-3D güvenlikli işlemlere izin ver (mdStatus=1) HALF_THD_MD12 (Allow Half-Secure 3D transactions if issuer bank or card is not registered to directory (mdStatus=1, 2)/ ğer banka veya kart dizine kayıtlı değilse Half-Secure 3D işlemlere izin ver (mdStatus=1, 2)) HALF_THD_MD129(Allow Half-Secure 3D transactions if merchant is not registered to directory (mdStatus=1, 2, 9)/Eğer üye işyeri dizine kayıtlı değilse Half-Secure 3D işlemlerine izin ver (mdStatus=1, 2, 9) )

Request parameters:

ACTION:

MERCHANTSETTINGSEDIT, required Max length: 128 Core parameter which specifies the main action for the API call.

ONBEHALFOFMERCHANT:

string, required Max length: 64 description

MERCHANTUSER:

string, required Max length: 128 API User.

MERCHANTPASSWORD:

string, required Max length: 128 API User password.

STATUS:

string, optional Max length: 2 Status information. See all possible values (4)

THREEDRESTRICTION:

string, optional Max length: 20 description See all possible values (2)

PAYMENTPOLICY:

string, optional Max length: 20 description See all possible values (4)

THREEDAMOUNTLIMIT:

decimal, optional Max length: 22 description

				
ACTION:MERCHANTSETTINGSEDIT
MERCHANTPASSWORD:[PASSWORD]
ONBEHALFOFMERCHANT:10000000
MERCHANTUSER:[SYSTEMUSER]
STATUS:OK
PAYMENTPOLICY:THD_BASED_ON_LIMIT
THREEDRESTRICTION:FULL_THD
THREEDAMOUNTLIMIT:3.5
				
			

				
{
    "merchantSettings": {
        "businessId": "10000000",
        "name": "ZiraatPay",
        "paymentPolicy": "THD_BASED_ON_LIMIT",
        "integrationModel": "ALL",
        "threeDAmountLimit": 3.5,
        "status": "OK",
        "threeDRestriction": "FULL_THD"
    }
}
				
			

Validate User

The VALIDATEUSER api call will be used to validate user.

Request parameters:

ACTION:

VALIDATEUSER, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, required Max length: 128 API User.

MERCHANTPASSWORD:

string, required Max length: 128 API User password.

USERPHONE:

string, required Max length: 20 Phone number of the Merchant user.

USEREMAIL:

string, optional Max length: 128 Email address of the merchant user.

TERMINALID:

string, required Max length: 7 Unique Terminal ID of the merchant.

				
ACTION:VALIDATEUSER
MERCHANTPASSWORD:[PASSWORD]
MERCHANTUSER:[SYSTEMUSER]
USERPHONE:[+905389580758]
USEREMAIL :[usertest@email.com]
TERMINALID : [100000]
				
			

				
{
	"responseCode": "00",
	"responseMsg": "Approved"
}
				
			

Verify OTP

The OTPVERIFICATION api call will be used to verify OTP

Request parameters:

ACTION:

OTPVERIFICATION, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

OTPCODE:

string, required Max length: 6 description

EMAIL:

string, required Max length: 64 description

				
ACTION:VALIDATEUSER
MERCHANTPASSWORD:[PASSWORD]
MERCHANTUSER:[SYSTEMUSER]
USERPHONE:[+905389580758]
USEREMAIL :[usertest@email.com]
OTPCODE : [OTPCode]
				
			

				
{
  	"IsOTPverified":"OK",
  	"OTPcode":"121212"
}
				
			

SMS Check OTP

The OTPSMSCHECK api call will be used to check Sms Otp

Request parameters:

ACTION:

OTPSMSCHECK, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, required Max length: 128 API User.

MERCHANTPASSWORD:

string, required Max length: 128 API User password.

USERPHONE:

string, required Max length: 64 Phone number of the Merchant user.

USEREMAIL:

string, optional Max length: 128 Email address of the merchant user.

				
ACTION:VALIDATEUSER
MERCHANTPASSWORD:[PASSWORD]
MERCHANTUSER:[SYSTEMUSER]
USERPHONE:[+905389580758]
USEREMAIL :[usertest@email.com]
				
			

				
{
  "IsOTPSent": true//false
  "SIMstatus": "CHANGED"//NOTOK//NOTCHANGED
  "responseMsg": "Template name alanı hatalıdır"
}
				
			

Add Sim Block

The ADDSIMBLOCK The API call will be used to block the user's sim card.

Request parameters:

ACTION:

ADDSIMBLOCK, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, required Max length: 128 API User.

MERCHANTPASSWORD:

string, required Max length: 128 API User password.

APPREF:

string, required Max length: 40 description

SMSNUMBER:

string, required Max length: 64 description

GSMOPERATOR:

integer, optional Max length: 1 description

FRAUDDATE:

date, conditional Max length: 16 Format: [dd-MM-yyyy] description

				
ACTION:ADDSIMBLOCK
MERCHANTPASSWORD:[PASSWORD]
MERCHANTUSER:[SYSTEMUSER]
SMSNUMBER:[+905389580758]
GSMOPERATOR :[1]
FRAUDDATE : [09-08-2023]
				
			

				
{   "responseCode": "00",
    "responseMsg": "Approved"
}
				
			

Bin Rule, Payment System Pool Association Actions

Add Bin Rule, Payment System Pool Association

The BINRULEPSPASSOCADD request can be used to add a new Bin Rule, Payment System Pool Association

Request parameters:

ACTION:

BINRULEPSPASSOCADD, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

RULENAME:

string, required Max length: 128 Bin Rule

PAYMENTSYSTEMPOOLNAME:

string, required Max length: 255 Payment system pool

PAYMENTSYSTEM:

string, required Max length: 128 Name of the payment system (bank payment gateway / vPOS account). Specified name should match the one given in ZiraatPay. If not provided, ZiraatPay smart switch feature will be used.

STATUS:

string, required Max length: 2 Status information. See all possible values (4)

				
ACTION: BINRULEPSPASSOCEDIT
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
RULENAME: [RULENAME]
PAYMENTSYSTEMPOOLNAME: [PAYMENTSYSTEMPOOLNAME]
PAYMENTSYSTEM: [PAYMENTSYSTEM]
STATUS: [STATUS]
				
			

				
{
    "responseCode": "00",
    "responseMsg": "Approved",
    "binRule": {
        "ruleName": "TEST11",
        "paymentSystemPoolName": "PSPOOL_TEST",
        "paymentSystem": "Akbank",
        "status": "OK",     
    }
}
				
		   

Edit Bin Rule, Payment System Pool Association

The BINRULEPSPASSOCEDIT request can be used to edit an existing Bin Rule, Payment System Pool Association

Request parameters:

ACTION:

BINRULEPSPASSOCADD, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

RULENAME:

string, required Max length: 128 Bin Rule

PAYMENTSYSTEMPOOLNAME:

string, required Max length: 255 Payment system pool

PAYMENTSYSTEM:

string, required Max length: 128 Name of the payment system (bank payment gateway / vPOS account). Specified name should match the one given in ZiraatPay. If not provided, ZiraatPay smart switch feature will be used.

STATUS:

string, required Max length: 2 Status information. See all possible values (4)

				
ACTION: BINRULEPSPASSOCEDIT
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
PAYMENTSYSTEMPOOLNAME: [PAYMENTSYSTEMPOOLNAME]
PAYMENTSYSTEM: [PAYMENTSYSTEM]
STATUS: [STATUS]
BINRULEPSPOOLASSOCNAME: [ASSOC-sfdsafa]
				
			

				
{
    "responseCode": "00",
    "responseMsg": "Approved",
    "binRule": {
        "ruleName": "TEST11",
        "paymentSystemPoolName": "PSPOOL_TEST",
        "paymentSystem": "Akbank",
        "status": "OK",     
    }
}
				
		   

Query Bin Rule, Payment System Pool Association

The QUERYBINRULEPSPASSOC QUERYBINRULEPSPASSOCDescription

Request parameters:

ACTION:

QUERYBINRULEPSPASSOC, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

				
ACTION: QUERYBINRULEPSPASSOC
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
				
			

				
	{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "binRulePSPoolAssoc" : [ {
    "binRuleName" : "urlChange",
    "paymentSytemPoolName" : "All Payment System In Pool",
    "paymentSystem" : "YKB",
    "status" : "OK",
    "addedDate" : 1678453875268,
    "addedBy" : "Paratika Super Admin",
    "modifiedBy" : ""
  }, {
    "binRuleName" : "testingRule",
    "paymentSytemPoolName" : "Test Pool",
    "paymentSystem" : "Finansbank",
    "status" : "OK",
    "addedDate" : 1678453725637,
    "addedBy" : "Paratika Super Admin",
    "modifiedBy" : ""
  } ]
}
				
		   

Delete Bin Rule, Payment System Pool Association

The BINRULEPSPASSOCDELETE request can be used to delete an existing Bin Rule, Payment System Pool Association

Request parameters:

ACTION:

BINRULEPSPASSOCDELETE, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

BINRULEPSPOOLASSOCNAME:

string, required Max length: 128 Association Name, unique and is autogenerated

				
ACTION: BINRULEPSPASSOCDELETE
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
RULENAME: [RULENAME]
PAYMENTSYSTEMPOOLNAME: [PAYMENTSYSTEMPOOLNAME]
PAYMENTSYSTEM: [PAYMENTSYSTEM]
				
			

				
	{
		"responseCode": "00",
		"responseMsg": "Approved"

	}
				
		   

Query Actions

Query Transaction

The Query Transaction request will return the details of successful transaction(s) for a specified order/payment (using MerchantPaymentID) or transaction (using PGTRANID) including the status of payment, the bank (payment system / vpos) that processed the transaction, number of installments and the interest rate.

Response time to transactions from bank is maximum 90 seconds. As a merchant, QUERYTRANSACTION service must be used to check the status of the transaction in the bank. If there is a late response from the bank or there is no response from the bank about transaction, it is important that you must integrate QUERYTRANSACTION service. Through this service, transaction status is acknowledged in MSU. Based on this acknowledgement you can either update your ERP or cancel the transaction.

Request parameters:

ACTION:

QUERYTRANSACTION, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, required Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, required Max length: 128 API User.

MERCHANTPASSWORD:

string, required Max length: 128 API User password.

PGTRANID:

string, optional Max length: 64 Transaction ID given by payment gateway.

TRANSACTIONSTATUS:

string, optional Max length: 18 Status of Transaction.

STARTDATE:

date, optional Max length: 16 Format: [dd-MM-yyyy HH:mm] Start date of the transaction query.

ENDDATE:

date, optional Max length: 16 Format: [dd-MM-yyyy HH:mm] End date of the transaction query.

OFFSET:

string, optional Max length: 4 Default value: '0' Specifies the number from which the transactions will start for paginated data.

LIMIT:

string, optional Max length: 4 Default value: '1000' The maximum number of transactions in response.

MERCHANTPAYMENTID:

string, optional Max length: 128 Unique Payment ID given by Merchant.

CUSTOMER:

string, optional Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

CUSTOMEREMAIL:

string, optional Max length: 64 Customer e-mail. This information should be passed correctly if the customer information services are used.

CUSTOMERNAME:

string, optional Max length: 128 Name of the Customer. This information should be passed correctly if the customer information services are used.

CUSTOMERPHONE:

string, optional Max length: 64 Customer phone / mobile number. This information should be passed correctly if the customer information services are used.

SELLERID:

string, optional Max length: 32 Unique value per seller.

FORGROUP:

string, optional Max length: 3 Default value: 'YES' Specifies the for group featured usages. Available values are 'yes' and 'no'.

					ACTION: QUERYTRANSACTION
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
PGTRANID: 18285OQZD14766
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "transactionCount" : "1",
  "totalTransactionCount" : "1",
  "transactionList" : [ {
    "pgTranTraceAudit" : "828514893296",
    "pgTranReturnCode" : "00",
    "pgOrderId" : "10000000-PaymentId-mQ15HqoF7d8f",
    "pgTranApprCode" : "294906",
    "pgTranId" : "18285OQZD14766",
    "pgTranRefId" : "828514893296",
    "timePsSent" : "2018-10-12 14:16:26.815",
    "timePsReceived" : "2018-10-12 14:16:27.967",
    "timeCreated" : "2018-10-12 14:16:26.474",
    "amount" : 80,
    "transactionStatus" : "AP",
    "currency" : "TRY",
    "paymentSystem" : "My Finans Webpos Online Account (Test)",
    "panLast4" : "4026",
    "transactionType" : "SALE",
    "installmentCount" : 1,
    "cardOwnerMasked" : "N*** G***",
    "customerId" : "Customer-GUZUbLrQ",
    "bin" : "402277",
    "sellers" : [ {
      "sellerId" : "tigran",
      "commissionAmount" : 10
    }, {
      "sellerId" : "benjamin",
      "commissionAmount" : 10
    }, {
      "sellerId" : "aurela",
      "commissionAmount" : 20
    }, {
      "sellerId" : "alfred",
      "commissionAmount" : 4.5
    }, {
      "sellerId" : "john",
      "commissionAmount" : 10
    }, {
      "sellerId" : "alketa",
      "commissionAmount" : 5.5
    }, {
      "sellerId" : "nora",
      "commissionAmount" : 10
    }, {
      "sellerId" : "kate",
      "commissionAmount" : 10
    } ]
  } ]
}                       
				

Query Installment

The QUERYINSTALLMENT request will return the available installments which can be used by card holder.

Request parameters:

ACTION:

QUERYINSTALLMENT, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

BIN:

string, optional Max length: 8 BIN value (first 8 PAN digits). Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

PAYMENTSYSTEM:

string, optional Max length: 128 Name of the payment system (bank payment gateway / vPOS account). Specified name should match the one given in ZiraatPay. If not provided, ZiraatPay smart switch feature will be used.

PAYMENTSYSTEMTYPE:

string, optional Max length: 32 description See all possible values (29)

					ACTION: QUERYINSTALLMENT
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
		           
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "paymentSystemEftCode" : "0111",
  "paymentSystemNetwork" : "CARD_FNS",
  "paymentSystemList" : [ {
    "name" : "My Finans Webpos Online Account (Test)",
    "paymentSystem" : 1,
    "installmentList" : [ {
      "count" : "NOT_ON_US",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "4",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "5",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "6",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "7",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "8",
      "customerCostCommissionRate" : 0
    } ]
  }, {
    "name" : "My Sanalakpos Account (Test)",
    "paymentSystem" : 2,
    "paymentSystemEftCode" : "0046",
    "paymentSystemNetwork" : "AXESS",
    "installmentList" : [ {
      "count" : "NOT_ON_US",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "4",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "5",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "6",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "7",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "8",
      "customerCostCommissionRate" : 0
    } ]
  }, {
    "name" : "My Halkbank Sanalpos Account (Test)",
    "paymentSystem" : 3,
    "paymentSystemEftCode" : "0012",
    "paymentSystemNetwork" : "PARAF",
    "installmentList" : [ {
      "count" : "NOT_ON_US",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "4",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "5",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "6",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "7",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "8",
      "customerCostCommissionRate" : 0
    } ]
  }, {
    "name" : "ISBANK TEST",
    "paymentSystem" : 4,
    "paymentSystemEftCode" : "0064",
    "paymentSystemNetwork" : "MAXIMUM",
    "installmentList" : [ {
      "count" : "NOT_ON_US",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "4",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "5",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "6",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "7",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "8",
      "customerCostCommissionRate" : 0
    } ]
  } ]
}                      
				

Query Card

The QUERYCARD request can be used to get all the card tokens saved for a particular cardholder (customer) or the details of the card based on the given token value.

Request parameters:

ACTION:

QUERYCARD, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CARDTOKEN:

string, optional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

CARDSAVENAME:

string, optional Max length: 64 Given name for the saved card.

CUSTOMER:

string, optional Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

FORGROUP:

string, optional Max length: 3 Default value: 'YES' Specifies the for group featured usages. Available values are 'yes' and 'no'.

OFFSET:

integer, optional Max length: 4 Default value: '0' Specifies the number from which the transactions will start for paginated data.

LIMIT:

integer, optional Max length: 4 Default value: '1000' The maximum number of transactions in response.

					ACTION: QUERYCARD
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
CUSTOMER: merchant20140920
				

					{
    "responseCode":"00",
    "responseMsg":"Approved",
    "cardCount":"1",
    "totalCardCount":"1",
    "cardList":[{
         "cardToken":"YGQHGWH4L3V3T6M2W6HHZ6FGJCZ5EKI5SBFGHHZORD55P6YV", 
         "cardOwner":"NAME SURNAME", 
         "panLast4":"0520", 
         "customer":"merchant20140920", 
         "cardBin":"540667", 
         "cardbrand":"MC", 
         "cardType":"CREDIT", 
         "cardLevel":"CLASSIC", 
         "cardNetwork":"MAXIMUM", 
         "cardIssuer":"T. IS BANKASI A.S.", 
         "cardVirtual":"NO", 
         "cardCountryIso":"TUR", 
         "cardPaymentSystem":"ISBANK TEST", 
         "cardExpiry":"01.2023", 
         "cardName":"ISBANKASI", 
         "pan":"540667***0520" 
    }]
}                       
				

Query Card Expiry

The QUERYCARDEXPIRY request can be used to get all the cards that will be expired in this and the next month.

Request parameters:

ACTION:

QUERYCARDEXPIRY, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, required Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, required Max length: 128 API User.

MERCHANTPASSWORD:

string, required Max length: 128 API User password.

CUSTOMER:

string, required Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

OFFSET:

string, optional Max length: 4 Default value: '0' Specifies the number from which the transactions will start for paginated data.

LIMIT:

string, optional Max length: 4 Default value: '1000' The maximum number of transactions in response.

FORGROUP:

string, optional Max length: 3 Default value: 'YES' Specifies the for group featured usages. Available values are 'yes' and 'no'.

					ACTION: QUERYCARDEXPIRY
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
CUSTOMER: merchant20140920
				

					{
    "responseCode":"00",
    "responseMsg":"Approved",
    "cardCount":"1",
    "totalCardCount":"1",
    "cardList":[{
        "cardToken" : "YGQHGWH4L3V3T6M2W6HHZ6FGJCZ5EKI5SBFGHHZORD55P6YV",
        "cardOwner" : "NAME SURNAME",
        "panLast4" : "0520",
        "customer" : "merchant20140920",
        "cardBin" : "540667",
        "cardExpiry" : "04.2015",
        "pan" : "540667***0520"
    }]
}                       
				

Query Session

The QUERYSESSION request can be used to get merchant, customer and session information of a valid session.

Request parameters:

ACTION:

QUERYSESSION, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, required Max length: 48 Session token.

					ACTION: QUERYSESSION
SESSIONTOKEN: [SESSIONTOKEN]	
			
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "session" : {
    "token" : "EMEVAXFGO7G4UWRTJD3R5QJ5ZOQJLY4YWLAOQJRKE7A2Z36L",
    "apiAction" : "SESSIONTOKEN",
    "merchantPaymentId" : "PaymentId-bl94pcHQ1mpO",
    "firstAmount" : 18.63,
    "amount" : 18.63,
    "currency" : "TRY",
    "returnUrl" : "https://neon-app.local.payten.com.tr/msu.merchant/index.jsp",
    "language" : "tr",
    "redirectWaitingTime" : 0,
    "itemTotalAmount" : 18.63, 
    "shippingContact" : {
      "address" : "Road",
      "city" : "Ankara",
      "country" : "Turkey",
      "postalCode" : "1105",
      "phone" : "987654321"
    },
    "billingContact" : {
      "address" : "Road",
      "city" : "Istanbul",
      "country" : "Turkey",
      "postalCode" : "1103",
      "phone" : "123456789"
    },
    "fastShipping" : false,
    "extra" : "{\"IframeDomainUrl\":\"https://www.google.com/\"}",
    "allowedUrl" : "https://www.google.com/"
  },
  "merchant" : {
    "businessId" : "***",
    "name" : "MSU Test Merchant",
    "tradingName" : "Trading name",
    "address" : "İTÜ Ayazağa Kampüsü Teknokent ARI 1 Binası No: 12 34469 Maslak",
    "phone" : "+902123650505",
    "fax" : "+902123650555",
    "webAddress" : "http://www.asseco-see.com.tr/",
    "additionalDetails" : "Asseco SEE",
    "secretKey" : "***",
    "paymentPolicy" : "THD_ALL",
    "domains" : "www.domain.com,https://www.google.com/,alketa.com",
    "preInformationText" : "
NA
",
    "remoteSalesAgreement" : "
NA
",
    "useHpp" : true,
    "integrationModel" : "API"
  },
  "customer" : {
    "id" : "Customer-CVnUJCST",
    "email" : "CVnUJCST@email.com",
    "phone" : "+906613328056",
    "name" : "Name CVnUJCST",
    "birthday" : "2001-01-01",
    "lastLogin" : "16.10.2017 14:24"
  },
  "orderItems" : [ {
    "code" : "u91f4",
    "name" : "seat belt",
    "description" : "seat belt description ...",
    "amount" : 9.01,
    "quantity" : 1
  }, {
    "code" : "1rnxq8",
    "name" : "lace",
    "description" : "lace description ...",
    "amount" : 3.39,
    "quantity" : 1
  }, {
    "code" : "bdvhiv",
    "name" : "television",
    "description" : "television description ...",
    "amount" : 4.5,
    "quantity" : 1
  }, {
    "code" : "5cwai",
    "name" : "mp3 player",
    "description" : "mp3 player description ...",
    "amount" : 1.6,
    "quantity" : 1
  }, {
    "code" : "vhlt5d",
    "name" : "bookmark",
    "description" : "bookmark description ...",
    "amount" : 0.13,
    "quantity" : 1
  } ]
}

				

Query Bin

The QUERYBIN Request can be used to get BIN information

Request parameters:

ACTION:

QUERYBIN, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

BIN:

string, conditional Max length: 8 BIN value (first 8 PAN digits). Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CARDTOKEN:

string, conditional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

					ACTION: QUERYPAYMENTSYSTEMS
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
BIN: 511452
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "bin" : {
    "bin" : "450803",
    "cardBrand" : "VISA",
    "cardType" : "CREDIT",
    "cardLevel" : "BUSINESS",
    "cardNetwork" : "MAXIMUM",
    "issuer" : "T. IS BANKASI A.S.",
    "virtual" : "NO",
    "countryIsoA3" : "TUR",
    "issuerType": "ISBANK",
    "is6Digit": "YES",
    "is8Digit": "NO"
  }
} 	
				

Payment Systems

Payment Systems QUERYPAYMENTSYSTEMS Request can be used to get all available payment systems

Request parameters:

ACTION:

QUERYPAYMENTSYSTEMS, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

BIN:

string, conditional Max length: 8 BIN value (first 8 PAN digits). Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CARDTOKEN:

string, conditional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

					ACTION: QUERYPAYMENTSYSTEMS
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
BIN: 511452
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "installmentPaymentSystem" : {
    "name" : "ISBANK TEST",
    "paymentSystem" : 1,
    "paymentSystemEftCode": "0064",
    "installmentList" : [ {
      "count" : "2",
      "customerCostCommissionRate" : 0.5
    }, {
      "count" : "3",
      "customerCostCommissionRate" : 0.5
    }, {
      "count" : "4",
      "customerCostCommissionRate" : 0.5
    }, {
      "count" : "5",
      "customerCostCommissionRate" : 0.5
    }, {
      "count" : "6",
      "customerCostCommissionRate" : 0.5
    } ]
  },
  "oneShotPaymentSystem" : {
    "name" : "My Sanalakpos Account (Test)",
    "paymentSystem" : 1,
    "paymentSystemEftCode" : "0046",
    "installmentList" : [ {
      "count" : "1",
      "customerCostCommissionRate" : 0.3
    } ]
  }
} 	
				

Query Pay By Link Payment

The Query Pay By Link Payment The request will return pay by link payments according to request filters. Date attributes in response are returned in merchant's timezone and formatted in ISO_8601

Request parameters:

ACTION:

QUERYPAYBYLINKPAYMENT, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

PAYBYLINKTOKEN:

string, conditional Max length: 48 description

STARTDATE:

date, conditional Max length: 32 Format: [dd-MM-yyyy HH:mm] Start date of the transaction query.

ENDDATE:

date, conditional Max length: 32 Format: [dd-MM-yyyy HH:mm] End date of the transaction query.

DUEDATE:

date, optional Max length: 16 Format: [dd-MM-yyyy HH:mm] description

CUSTOMEREMAIL:

string, optional Max length: 64 Customer e-mail. This information should be passed correctly if the customer information services are used.

PAYBYLINKSTATUS:

string, optional Max length: 2 description See all possible values (5)

					
ACTION: QUERYPAYBYLINKPAYMENT
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
PAYBYLINKTOKEN: [TF7MPD55XU656FPW7ZJOGYVJ2X2AOKMNMDTXHECEQPYGO2RS]
PAYBYLINKSTATUS: []
CREATEDTS: []
DUEDATE: []
CUSTOMEREMAIL: []
				

					
{  
   "payByLinkPaymentList":[  
      {  
         "amount":10,
         "dueDate":"2016-06-27T21:10:41",
         "currency":"TRY",
         "cardHolderEmail":"testcustomer@email.com",
         "createdTs":"2016-06-20T14:46:41",
         "token":"3LQ74ANRG6RSAA32KYFELZX2VKPD22SN7KPWHYOOWQSXGBLE",
         "status":"SD"
      },
      {  
         "amount":10,
         "dueDate":"2016-06-27T15:00:42",
         "currency":"TRY",
         "cardHolderEmail":"testcustomer@email.com",
         "createdTs":"2016-06-20T14:46:42",
         "token":"HKLON7HKRJGEZGHOY3WE3GHLIY7TG4ZRGIGU4XFETJLJSRWV",
         "status":"SD"
      }
   ],
   "responseCode":"00",
   "responseMsg":"Approved"
}
 					
				

Query PAN

The QUERYPAN request can be used to get BIN information for the specified card pan.

Request parameters:

ACTION:

QUERYPAN, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CARDPAN:

string, required Max length: 19 PAN (Primary account number), card number. Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

					ACTION: QUERYPAN
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
CARDPAN: 5406670000000009
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "bin" : {
    "bin" : "540667",
    "cardBrand" : "MC",
    "cardType" : "CREDIT",
    "cardLevel" : "CLASSIC",
    "cardNetwork" : "MAXIMUM",
    "issuer" : "T. IS BANKASI A.S.",
    "virtual" : "NO",
    "countryIsoA3" : "TUR"
  }
} 	
				

					ACTION: QUERYPAN
SESSIONTOKEN: [SESSIONTOKEN]
CARDPAN: 5406670000000009
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "bin" : {
    "bin" : "540667",
    "cardBrand" : "MC",
    "cardType" : "CREDIT",
    "cardLevel" : "CLASSIC",
    "cardNetwork" : "MAXIMUM",
    "issuer" : "T. IS BANKASI A.S.",
    "virtual" : "NO",
    "countryIsoA3" : "TUR"
  }
} 	
			
		
	

Query Merchant Content

The QUERYMERCHANTCONTENT request can be used to get MERCHANT CONTENTS.

Request parameters:

ACTION:

QUERYMERCHANTCONTENT, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTCONTENTID:

string, optional Max length: 16 Unique Merchant Content ID given by Merchant.

					ACTION: QUERYMERCHANTCONTENT
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANTCONTENTID: 00AXVTSiHX99Z
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "merchantContentList" : [ {
    "merchantContentType" : "tac",
    "language" : "tr",
    "merchant" : "009testID001",
    "displayed" : "true",
    "content" : "test"
  } ]
}	
				

Query Points

The QUERYPOINTS request can be used to get MERCHANT's points. Query made from bank side and a financial transaction.

Request parameters:

ACTION:

QUERYPOINTS, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANTPAYMENTID:

string, conditional Max length: 128 Unique Payment ID given by Merchant.

AMOUNT:

decimal, conditional Max length: 30 Amount of payment / transaction. Please note that, this amount is tax included, ZiraatPay doesn't consider any other tax calculation.

CUSTOMER:

string, conditional Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

CURRENCY:

string, conditional Max length: 3 ISO Alpha transaction currency code like TRY, EUR, USD, GBP. Please check https://en.wikipedia.org/wiki/ISO_4217#Position_of_ISO_4217_code_in_amounts for details. See all possible values (33)

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CARDTOKEN:

string, conditional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

CARDPAN:

string, conditional Max length: 19 PAN (Primary account number), card number. Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CARDEXPIRY:

string, conditional Max length: 7 Expiry date of the card. Format should be [mm.yy].

NAMEONCARD:

string, conditional Max length: 64 Name on the card.

CARDCVV:

string, optional Max length: 4 Security number of the card, CVV value.

INSTALLMENTS:

integer, optional Max length: 2 Default value: '1' Number of installments. Specified number should exist in the payment system as defined.

PAYMENTSYSTEM:

string, optional Max length: 128 Name of the payment system (bank payment gateway / vPOS account). Specified name should match the one given in ZiraatPay. If not provided, ZiraatPay smart switch feature will be used.

FORGROUP:

string, optional Max length: 3 Default value: 'YES' Specifies the for group featured usages. Available values are 'yes' and 'no'.

					
   ACTION: QUERYPOINTS
   MERCHANTUSER: [MERCHANTUSER]
   MERCHANT: [MERCHANT]  
   MERCHANTPAYMENTID: session-vMMSSxDCxL9o
   MERCHANTPASSWORD: [MERCHANTPASSWORD]
   AMOUNT: 15.25   
   CURRENCY: TRY   
   CUSTOMER: merchant-7CtRNVbX   
   CARDEXPIRY: 12.2020   
   NAMEONCARD: NameOnCard
   CARDCVV: 000   
   CARDPAN: 4355084355084358
   PAYMENTSYSTEM: GarantiPOS 
				
				

					
						{
  "action" : "QUERYPOINTS",
  "merchant" : "testmerchant",
  "amount" : 15.25,
  "currency" : "TRY",
  "apiMerchantId" : "100100000",
  "paymentSystem" : "My Sanalakpos Account (Test)",
  "pgTranDate" : "",
  "merchantPaymentId" : "session-vMMSSxDCxL9o",
  "pgTranId" : "15182NCJB01021266",
  "pgTranRefId" : "",
  "pgOrderId" : "session-vMMSSxDCxL9o",
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "points" : [ {
    "name" : "PCBCHIPPARABAKIYE",
    "value" : "000000009856"
  }, {
    "name" : "CCBCHIPPARABAKIYE",
    "value" : "000000083118"
  }, {
    "name" : "XCBCHIPPARABAKIYE",
    "value" : "000000029196"
  }, {
    "name" : "CCBCHIPPARAACIKLAMA",
    "value" : "ccb chip para aciklama"
  }, {
    "name" : "PCBCHIPPARAACIKLAMA",
    "value" : "pcb chip para aciklama"
  }, {
    "name" : "XCBCHIPPARAACIKLAMA",
    "value" : "xcb chip para aciklama"
  }, {
    "name" : "ERRORCODE",
    "value" : ""
  } ]
}
					
				

					
						{
  "action" : "QUERYPOINTS",
  "merchant" : "testmerchant",
  "amount" : 12.58,
  "currency" : "TRY",
  "apiMerchantId" : "700100000",
  "paymentSystem" : "My İşbank VPOS Account (Test)",
  "pgTranDate" : "",
  "merchantPaymentId" : "session-nmR4PEmEihOO",
  "pgTranId" : "15182PonE07021429",
  "pgTranRefId" : "",
  "pgOrderId" : "session-nmR4PEmEihOO",
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "points" : [ {
    "name" : "NUMCODE",
    "value" : "00"
  }, {
    "name" : "HOSTMSG",
    "value" : "TOPLAMMAXIPUAN: 50.00 TL"
  }, {
    "name" : "HOSTDATE",
    "value" : "0701-154039"
  }, {
    "name" : "MAXIPUAN",
    "value" : "50.00"
  }, {
    "name" : "ERRORCODE",
    "value" : ""
  } ]
}
					
				

					
						{
  "action" : "QUERYPOINTS",
  "merchant" : "testmerchant",
  "amount" : 17.31,
  "currency" : "TRY",
  "apiMerchantId" : "600100000",
  "paymentSystem" : "My Finans Webpos Online Account (Test)",
  "pgTranDate" : "",
  "merchantPaymentId" : "session-GHmNvtjCKMos",
  "pgTranId" : "15182PrjH00128947",
  "pgTranRefId" : "",
  "pgOrderId" : "session-GHmNvtjCKMos",
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "points" : [ {
    "name" : "NUMCODE",
    "value" : "00"
  }, {
    "name" : "PARAPUANTRL",
    "value" : "000000002631"
  }, {
    "name" : "SEYAHATAVANSPUANTRL",
    "value" : ""
  }, {
    "name" : "SEYAHATAVANSPUANVADETARIHI",
    "value" : ""
  }, {
    "name" : "PARAPUAN",
    "value" : "000000002631"
  }, {
    "name" : "CAVVRESULTCODE",
    "value" : "3"
  }, {
    "name" : "ERRORCODE",
    "value" : ""
  } ]
}
					
				

					
{
  "action" : "QUERYPOINTS",
  "merchant" : "testmerchant",
  "amount" : 17.27,
  "currency" : "TRY",
  "apiMerchantId" : "000100000012656",
  "paymentSystem" : "Vakifbank",
  "paymentSystemType" : "VAKIFBANK",
  "paymentSystemEftCode" : "0015",
  "merchantPaymentId" : "PaymentId-YwOuiloCfCHK",
  "pgTranId" : "bf2a7eef537a4e1bad0ca5be00f07519",
  "pgTranRefId" : "000075283460",
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "points" : [ {
    "name" : "PUAN",
    "value" : "283567.72"
  } ]
}
					
		

					
{
  "action" : "QUERYPOINTS",
  "merchant" : "10000000",
  "amount" : 11.22,
  "currency" : "TRY",
  "apiMerchantId" : "9916570",
  "paymentSystem" : "HSBC",
  "paymentSystemType" : "HSBC",
  "paymentSystemEftCode" : "0123",
  "pgTranDate" : "",
  "merchantPaymentId" : "PaymentId-7Yx5s2QSMRvP",
  "pgTranId" : "",
  "pgTranRefId" : "",
  "pgOrderId" : "",
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "points" : [ {
    "name" : "ODUL",
    "value" : "5612.47"
  } ]
}
					
		

Query Recurring Plan

The QUERYRECURRINGPLAN request will return the details of recurring plan(s) for a specified recurring plan by using RECURRINGPLANCODE or by time range (STARTDATE and ENDDATE).

Request parameters:

ACTION:

QUERYRECURRINGPLAN, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, optional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, optional Max length: 128 API User.

MERCHANTPASSWORD:

string, optional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

STARTDATE:

date, conditional Max length: 16 Format: [dd-MM-yyyy] Start date of the transaction query.

ENDDATE:

date, conditional Max length: 16 Format: [dd-MM-yyyy] End date of the transaction query.

RECURRINGPLANCODE:

string, conditional Max length: 16 Unique code of a recurring plan.

CARDPAN:

string, optional Max length: 19 PAN (Primary account number), card number. Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CUSTOMER:

string, optional Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

					ACTION: QUERYRECURRINGPLAN
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
RECURRINGPLANCODE: Code-JSjAuDXf
				

					{
  "action" : "QUERYRECURRINGPLAN",
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "recurringPlan" : {
    "recurringPlanCode" : "Code-wAasdfMW",
    "firstAmount" : 0,
    "recurringAmount" : 100,
    "startDate" : "01-10-2015 00:00",
    "scheduledEndDate" : "04-10-2015 00:00",
    "recurrenceCount" : 2,
    "completedRecurrence" : 0,
    "frequency" : "3D",
    "currency" : "TRY",
    "paymentSytem" : "My Finans Webpos Online Account",
    "status" : "ACTIVE"
  },
  "recurringPaymentList" : [ {
    "startDate" : "01-10-2015 00:00",
    "status" : "PENDING",
    "executionDate" : "",
    "recurrence" : 1,
    "amount" : 100,
    "tryCount" : 0
  }, {
    "startDate" : "04-10-2015 00:00",
    "status" : "PENDING",
    "executionDate" : "",
    "recurrence" : 2,
    "amount" : 100,
    "tryCount" : 0
  } ],
   "merchant" : {
    "businessId" : "[MERCHANT_BUSINESS_ID]",
    "name" : "[MERCHANTNAME]",
    "address" : "[MERCHANTADDRESS]",
    "phone" : "[MERCHANTPHONE]",
    "fax" : "[MERCHANTFAX]",
    "webAddress" : "http://www.asseco-see.com.tr/",
    "additionalDetails" : "Asseco South Eastern Europe",
    "secretKey" : "[SECRETKEY]",
    "referrer" : "https://www.example.com"
  },
  "customer" : {
    "id" : "MRCH_CUST_ID_123",
    "email" : "customerEmail-DA1y5O0U",
    "phone" : "11111111111111",
    "name" : "CustomerNameDA1y5O0U",
    "lastLogin" : "30.01.2015 16:11"
  },
  "card" : {
    "cardToken" : "CBCANDT5NRAJK2DCKYWZ2LZ6XIPCXXMPOBEKXEXSCD4YZN6O",
    "cardOwner" : "Name oa9iDQNM",
    "panLast4" : "5454",
    "customer" : "Customer-oa9iDQNM",
    "cardBin" : "545616",
    "cardExpiry" : "12.2020"
  }
}                       
				

Query Recurring Plan Card

The QUERYRECURRINGPLANCARD request will return the details of cards for a specified recurring plan by using RECURRINGPLANCODE.

Request parameters:

ACTION:

QUERYRECURRINGPLANCARD, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

RECURRINGPLANCODE:

string, required Max length: 16 Unique code of a recurring plan.

					ACTION: QUERYRECURRINGPLANCARD
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
RECURRINGPLANCODE: [Code-UPAG0PzB]
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "cardList" : [ {
    "cardToken" : "BKSJWIERRJQFODRQ27AEI3JLLNLVDZ64Z74I6D2Q6GJ73YBN",
    "cardOwnerMasked" : "N*** A*******",
    "panLast4" : "5454",
    "customer" : "Customer-AtdW4XGx",
    "cardBin" : "545616",
    "cardExpiry" : "12.2020",
    "pan" : "545616***5454"
  }, {
    "cardToken" : "T45FWSAXNHZPC4NYCGVQSYY4INTCCPB3GC5MJ2HGD2YKLCG6",
    "cardOwnerMasked" : "N*** V*******",
    "panLast4" : "5454",
    "customer" : "Customer-Vdsj1bTN",
    "cardBin" : "545616",
    "cardExpiry" : "12.2020",
    "pan" : "545616***5454"
  }, {
    "cardToken" : "RF4DIKGLC65GLBTJWUJJDJAERGKTZ27NN7PPEE7NEPWBJGVP",
    "cardOwnerMasked" : "N*** f*******",
    "panLast4" : "5454",
    "customer" : "Customer-f2EWrLZE",
    "cardBin" : "545616",
    "cardExpiry" : "12.2020",
    "pan" : "545616***5454"
  }, {
    "cardToken" : "Z6VJJMIYBNWDVIXUC3547D356FX5DZZT5KVIZBA4Z3GYAVN5",
    "cardOwnerMasked" : "d***",
    "panLast4" : "9159",
    "customer" : "Customer-f2EWrLZE",
    "cardBin" : "409070",
    "cardExpiry" : "12.2020",
    "pan" : "409070***9159"
  } ]
}                       
				

Query Campaign

The QUERYCAMPAIGN request can be used to get campaigns.

Request parameters:

ACTION:

QUERYCAMPAIGN, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

BIN:

string, conditional Max length: 8 BIN value (first 8 PAN digits). Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CARDTOKEN:

string, conditional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

					ACTION: QUERYCAMPAIGN
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
BIN: 511452
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "campaignCodeList" : [ {
    "campaignName" : "Test1",
    "campaignCode" : "123",
    "installment" : "4",
    "minInstallment" : 3,
    "maxInstallment" : 4,
    "installmentAmount" : "3",
    "currency" : "TRY",
    "paymentSystemType" : "FINANS",
    "campaignType" : "ADDITIONALINSTALLMENT",
    "forCreditCards" : true,
    "forBusinessCards" : false,
    "details" : "Test details"
  }, {
    "campaignName" : "Test2",
    "campaignCode" : "456",
    "installment" : "4",
    "minInstallment" : 2,
    "maxInstallment" : 2,
    "installmentAmount" : "3",
    "currency" : "TRY",
    "paymentSystemType" : "FINANS",
    "campaignType" : "POSTPONE",
    "forCreditCards" : false,
    "forBusinessCards" : true,
    "details" : "Test details 2"
  } ]
}	
				

Query Campaign Online

The QUERYCAMPAIGNONLINE request can be used to get card holders' campaigns if they are available to merchants. Query made from bank side and a financial transaction.

Request parameters:

ACTION:

QUERYCAMPAIGNONLINE, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANTPAYMENTID:

string, conditional Max length: 128 Unique Payment ID given by Merchant.

AMOUNT:

decimal, conditional Max length: 30 Amount of payment / transaction. Please note that, this amount is tax included, ZiraatPay doesn't consider any other tax calculation.

INSTALLMENTS:

integer, required Max length: 2 Number of installments. Specified number should exist in the payment system as defined.

CURRENCY:

string, conditional Max length: 3 ISO Alpha transaction currency code like TRY, EUR, USD, GBP. Please check https://en.wikipedia.org/wiki/ISO_4217#Position_of_ISO_4217_code_in_amounts for details. See all possible values (33)

CUSTOMER:

string, conditional Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

CARDTOKEN:

string, conditional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

CARDCVV:

string, optional Max length: 4 Security number of the card, CVV value.

CARDPAN:

string, conditional Max length: 19 PAN (Primary account number), card number. Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CARDEXPIRY:

string, conditional Max length: 7 Expiry date of the card. Format should be [mm.yy].

NAMEONCARD:

string, conditional Max length: 64 Name on the card.

CUSTOMERIP:

string, optional Max length: 39 Customer IP Address

CUSTOMERUSERAGENT:

string, optional Max length: 512 Customer User Agent

EXTRA:

string, optional Max length: 4000 Extra Parameter is a custom parameter that is used to pass additional parameters to session token. This parameter is expected to be in JSON(URL-ENCODED) format. If they are mispelled, they will be ignored! Supported parameters are: CardHolderAgreementMode(value: NONE/SHOW/SHOWCHECKED/SHOWCHECKEDDISABLED), AlwaysSaveCard(value: true/false), BuyerType (value: L for logged in customer; A for anonymous, F for the first shopping with memebership. OR it can be 0, 1, 2 for those cases), IsbankBolumKodu(string), IframeDomainUrl indicates from which URL address payment will be proceesed., PREAUTH=YES parameter indicates that payment will be processed as pre-authorization even if is started as sale., IGNORECUSTOMERCOMMISSION(values : YES/NO).
EXTRA: {"AlwaysSaveCard": "true", "BuyerType": "L", "IsbankBolumKodu": 12, "CardHolderAgreementMode": "SHOWCHECKED", "IGNORECUSTOMERCOMMISSION" : "YES"}

Other bank parameters

• MAXIMUMMOBIL - include Maximum Mobil payment system name like below to have Maximum Mobil tab on Default HPP
  {"MaximumMobilPaymentSystem":"PaymentSystemName"}
• GIROGATE payment methods. If one of payment methods is sent as "Yes", authentication will be done using GiroGate payment methods. Possible values: YES/NO.
  • SOFORT: {"SOFORT": "YES"}
  • SAFETYPAY: {"SAFETYPAY": "YES"}
  • QIWI: {"QIWI": "YES"}
  • GIROPAY: {"GIROPAY": "YES"}
  • IDEAL: {"IDEAL": "YES"}
  • FINNISHONLINEBANKING: {"FINNISHONLINEBANKING": "YES"}
  • BANCONTACT: {"BANCONTACT": "YES"}
  • ALIPAY: {"ALIPAY": "YES"}
  • MULTIBANCO: {"MULTIBANCO": "YES"}
  • TRUSTPAY: {"TRUSTPAY": "YES"}
  • EPS: {"EPS": "YES"}
  • MYBANK: {"MYBANK": "YES"}
  • P24: {"P24": "YES"}
  • BOLETO: {"BOLETO": "YES"}
  • ELO: {"ELO": "YES"}
  • SEPA: {"SEPA": "YES"}
  • UPOP: {"UPOP": "YES"}
• ISBANK - include in extra like below to send agriculture template info to Isbank when doing imece card operations.
  {"IMCKOD":"imckod", "FDONEM":"fdonem"}

PAYMENTSYSTEMTYPENAME:

string, optional Max length: 100 description

FORGROUP:

string, optional Max length: 3 Default value: 'YES' Specifies the for group featured usages. Available values are 'yes' and 'no'.

					
 ACTION: QUERYCAMPAIGNONLINE
 MERCHANTUSER: [MERCHANTUSER]
 MERCHANT: [MERCHANT]  
 MERCHANTPAYMENTID: PaymentId-pqkzBsVhLD3K
 MERCHANTPASSWORD: [MERCHANTPASSWORD]
 AMOUNT: 15.92
 INSTALLMENTS : 3   
 CURRENCY: TRY   
 CUSTOMER: merchant-7CtRNVbX   
 CARDEXPIRY: 12.2020   
 NAMEONCARD: NameOnCard
 CARDCVV: 000   
 CARDPAN: 5406670000000009 
				
				

					
{
  "action" : "QUERYCAMPAIGNONLINE",
  "merchant" : "testmerchant",
  "amount" : 15.92,
  "installment" : "1",
  "currency" : "TRY",
  "apiMerchantId" : "700658785",
  "paymentSystem" : "Türkiye İş Bankası Sanal POS",
  "paymentSystemType" : "ISBANK",
  "paymentSystemEftCode" : "0064",
  "pgTranDate" : "",
  "merchantPaymentId" : "PaymentId-pqkzBsVhLD3K",
  "pgTranId" : "16180OzcC07010161",
  "pgTranRefId" : "",
  "pgOrderId" : "PaymentId-pqkzBsVhLD3K",
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "campaigns" : [ {
    "campaignCode" : "000001",
    "campaignName" : "kampanya1",
    "campaignExtra" : ""
  }, {
    "campaignCode" : "000002",
    "campaignName" : "kampanya2",
    "campaignExtra" : ""
  }, {
    "campaignCode" : "000003",
    "campaignName" : "kampanya3",
    "campaignExtra" : ""
  } ]
}
					
				

Query Payment System Data

The Query Payment System Data QueryPSData

Request parameters:

ACTION:

QUERYPAYMENTSYSTEMDATA, required Max length: 128 Core parameter which specifies the main action for the API call.

INSTALLMENTS:

integer, required Max length: 2 Default value: '1' Number of installments. Specified number should exist in the payment system as defined.

EFTCODE:

string, optional Max length: 4 description

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

BIN:

string, conditional Max length: 8 BIN value (first 8 PAN digits). Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

PAYMENTSYSTEMTYPE:

string, conditional Max length: 32 description See all possible values (29)

CURRENCY:

string, optional Max length: 3 ISO Alpha transaction currency code like TRY, EUR, USD, GBP. Please check https://en.wikipedia.org/wiki/ISO_4217#Position_of_ISO_4217_code_in_amounts for details. See all possible values (33)

					ACTION: QUERYPAYMENTSYSTEMDATA
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
INSTALLMENTS: 1   
PAYMENTSYSTEMTYPE: FINANS
				

					
{
  "paymentSystemType" : "FINANS",
  "responseCode" : "00",
  "responseMsg" : "Approved"
} 					
				

Query Merchant Commission

The QUERYMERCHANTCOMMISSION request can be used to get transaction hosting commission

Request parameters:

ACTION:

QUERYMERCHANTCOMMISSION, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, optional Max length: 128 Merchant business code defined in the system.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

					ACTION: QUERYMERCHANTCOMMISSION
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
SESSIONTOKEN: [SESSIONTOKEN]
				

					{
    "responseCode": "00",
    "responseMsg": "Approved",
    "paymentDueInDays": "30",
    "merchantPaymentDayIndexes": "0;3;4",
    "paymentSystemBased": "YES",
    "defaultCommission": {
        "installmentList": [
            {
                "count": "1",
                "merchantCostCommissionRate": 1
            },
            {
                "count": "2",
                "merchantCostCommissionRate": 2
            },
            {
                "count": "3",
                "merchantCostCommissionRate": 3
            },
            {
                "count": "4",
                "merchantCostCommissionRate": 0
            },
            {
                "count": "5",
                "merchantCostCommissionRate": 0
            },
            {
                "count": "6",
                "merchantCostCommissionRate": 0
            },
            {
                "count": "7",
                "merchantCostCommissionRate": 0
            },
            {
                "count": "8",
                "merchantCostCommissionRate": 0
            },
            {
                "count": "9",
                "merchantCostCommissionRate": 0
            },
            {
                "count": "10",
                "merchantCostCommissionRate": 0
            },
            {
                "count": "11",
                "merchantCostCommissionRate": 0
            },
            {
                "count": "12",
                "merchantCostCommissionRate": 50
            },
            {
                "count": "crNotOnUs",
                "merchantCostCommissionRate": 0
            },
            {
                "count": "crOnNetwork",
                "merchantCostCommissionRate": 0
            }
        ]
    },
    "paymentSystemBasedCommissionList": [
        {
            "paymentSystemName": "My Sanalakpos Account (Test)",
            "installmentList": [
                {
                    "count": "1",
                    "merchantCostCommissionRate": 0.4
                },
                {
                    "count": "2",
                    "merchantCostCommissionRate": 0
                },
                {
                    "count": "3",
                    "merchantCostCommissionRate": 0
                },
                {
                    "count": "4",
                    "merchantCostCommissionRate": 0
                },
                {
                    "count": "5",
                    "merchantCostCommissionRate": 0.29
                },
                {
                    "count": "6",
                    "merchantCostCommissionRate": 0.29
                },
                {
                    "count": "7",
                    "merchantCostCommissionRate": 0
                },
                {
                    "count": "8",
                    "merchantCostCommissionRate": 0.38
                },
                {
                    "count": "9",
                    "merchantCostCommissionRate": 0
                },
                {
                    "count": "10",
                    "merchantCostCommissionRate": 0.39
                },
                {
                    "count": "11",
                    "merchantCostCommissionRate": 0.39
                },
                {
                    "count": "12",
                    "merchantCostCommissionRate": 0
                },
                {
                    "count": "crNotOnUs",
                    "merchantCostCommissionRate": 0
                },
                {
                    "count": "crOnNetwork",
                    "merchantCostCommissionRate": 0
                }
            ]
        }
    ],
    "distinctPaymentSystemId": [
        "your-payment-system-id",
        "DEFAULT"
    ],
    "paymentSystemNames": {
        "your-payment-system-id": "My Sanalakpos Account (Test)",
        "DEFAULT": "DEFAULT"
    },
         "classifiedCommissionList": [
        {
            "currency": "EUR",
            "currencyCommissions": [
                {
                    "id": "00BYLHh9UyDE",
                    "commissionKey": "CR8",
                    "commissionValue": 0,
                    "currency": "EUR",
                    "dueDate": 0,
                    "paymentSystemCurrencyCommissions": [
                        {
                            "id": "00BYLHh9Uxzm",
                            "paymentSystemId": "your-payment-system-id",
                            "commissionValue": 0,
                            "dueDate": 0,
                            "validated": false,
                            "version": 0
                        },
                        {
                            "id": "00BYLHh9Uxzl",
                            "paymentSystemId": "DEFAULT",
                            "commissionValue": 0,
                            "dueDate": 0,
                            "validated": false,
                            "version": 0
                        }
                    ],
                    "active": true,
                    "validated": false,
                    "version": 0
                },
                {
                    "id": "00BYLHh9UyCG",
                    "commissionKey": "CR2",
                    "commissionValue": 0,
                    "currency": "EUR",
                    "dueDate": 0,
                    "paymentSystemCurrencyCommissions": [
                        {
                            "id": "00BYLHh9UyE0",
                            "paymentSystemId": "DEFAULT",
                            "commissionValue": 0,
                            "dueDate": 0,
                            "validated": false,
                            "version": 0
                        },
                        {
                            "id": "00BYLHh9UyDz",
                            "paymentSystemId": "your-payment-system-id",
                            "commissionValue": 0,
                            "dueDate": 0,
                            "validated": false,
                            "version": 0
                        }
                    ],
                    "active": true,
                    "validated": false,
                    "version": 0
                },
                {
                    "id": "00BYLHh9UyC3",
                    "commissionKey": "CR1",
                    "commissionValue": 0,
                    "currency": "EUR",
                    "dueDate": 0,
                    "paymentSystemCurrencyCommissions": [
                        {
                            "id": "00BYLHh9UyDZ",
                            "paymentSystemId": "your-payment-system-id",
                            "commissionValue": 0,
                            "dueDate": 0,
                            "validated": false,
                            "version": 0
                        },
                        {
                            "id": "00BYLHh9UyDa",
                            "paymentSystemId": "DEFAULT",
                            "commissionValue": 0,
                            "dueDate": 0,
                            "validated": false,
                            "version": 0
                        }
                    ],
                    "active": true,
                    "validated": false,
                    "version": 0
                },
                ...
            ]
        }
}	
				

Query Customer Commission

The QUERYCUSTOMERCOMMISSION request can be used to get customer commission schema.

Request parameters:

ACTION:

QUERYCUSTOMERCOMMISSION, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

ACTIVATIONDATE:

date, optional Max length: 32 Format: [dd-MM-yyyy HH:mm] Activation date in Coordinated Universal Time (UTC) standard

ACTIVATIONDATEINMILLISECONDS:

string, optional Max length: 19 description

			ACTION: QUERYCUSTOMERCOMMISSION
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
SESSIONTOKEN: [SESSIONTOKEN]
ACTIVATIONDATE: [dd-MM-yyyy HH:mm] 
			
		

			
				{
  "activationDate" : "25-03-2019 18:20",
  "paymentSystemBased" : "YES",
  "defaultCommission" : {
    "installmentList" : [ {
      "count" : "2",
      "customerCostCommissionRate" : 2.55
    }, {
      "count" : "3",
      "customerCostCommissionRate" : 3.2
    }, {
      "count" : "4",
      "customerCostCommissionRate" : 4.5
    }, {
      "count" : "5",
      "customerCostCommissionRate" : 5.1
    }, {
      "count" : "6",
      "customerCostCommissionRate" : 5.99
    }, {
      "count" : "7",
      "customerCostCommissionRate" : 6.12
    }, {
      "count" : "8",
      "customerCostCommissionRate" : 6.77
    }, {
      "count" : "9",
      "customerCostCommissionRate" : 6.89
    }, {
      "count" : "10",
      "customerCostCommissionRate" : 6.99
    }, {
      "count" : "11",
      "customerCostCommissionRate" : 7.99
    }, {
      "count" : "12",
      "customerCostCommissionRate" : 8.22
    } ]
  },
  "paymentSystemBasedCommissionList" : [ {
    "paymentSystemName" : "Test Payment System Name",
    "installmentList" : [ {
      "count" : "2",
      "customerCostCommissionRate" : 0
    }, {
      "count" : "3",
      "customerCostCommissionRate" : 0.51
    }, {
      "count" : "4",
      "customerCostCommissionRate" : 6.35
    }, {
      "count" : "5",
      "customerCostCommissionRate" : 8.76
    }, {
      "count" : "6",
      "customerCostCommissionRate" : 10.11
    }, {
      "count" : "7",
      "customerCostCommissionRate" : 12.33
    }, {
      "count" : "8",
      "customerCostCommissionRate" : 14.05
    }, {
      "count" : "9",
      "customerCostCommissionRate" : 16.23
    }, {
      "count" : "10",
      "customerCostCommissionRate" : 18.22
    }, {
      "count" : "11",
      "customerCostCommissionRate" : 19.33
    }, {
      "count" : "12",
      "customerCostCommissionRate" : 19.97
    } ]
  } ]
}
			
		

Query Order Item

The QUERYORDERITEM request return the order item list for a specific Merchant Payment Id.

Request parameters:

ACTION:

QUERYORDERITEM, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

PGTRANID:

string, conditional Max length: 64 Transaction ID given by payment gateway.

MERCHANTPAYMENTID:

string, conditional Max length: 128 Unique Payment ID given by Merchant.

					ACTION: QUERYORDERITEM
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
MERCHANTPAYMENTID : [MERCHANTPAYMENTID]
SESSIONTOKEN: [SESSIONTOKEN]

				

					
					{
    "responseCode": "00",
    "responseMsg": "Approved",
    "orderItemList": [
        {
            "code": "ljwsd",
            "name": "keyboard",
            "description": "keyboard description ...",
            "sellerId": "MySeller",
            "quantity": 1,
            "productCategoryCode": 4722,
            "amount": 100,
            "sellerPaymentAmount": 10
        },
        {
            "code": "ljwsd",
            "name": "keyboard",
            "description": "keyboard description ...",
            "sellerId": "MySeller",
            "quantity": 1,
            "productCategoryCode": 4722,
            "amount": 100,
            "sellerPaymentAmount": 10
        },
        {
            "code": "ljwsd",
            "name": "keyboard",
            "description": "keyboard description ...",
            "sellerId": "MySeller",
            "quantity": 1,
            "productCategoryCode": 4722,
            "amount": 100,
            "sellerPaymentAmount": 10
        }
    ]
}                      
	
	

Query Seller

The QUERYSELLER request can be used to get all the sellers saved for a particular merchant or the details of specific seller based on the given sellerId value.

Request parameters:

ACTION:

QUERYSELLER, required Max length: 128 Core parameter which specifies the main action for the API call.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SELLERID:

string, optional Max length: 32 Unique value per seller.

ONBEHALFOFMERCHANT:

string, optional Max length: 64 description

STATUS:

string, optional Max length: 2 Status information.

					ACTION: QUERYSELLER
SESSIONTOKEN: [SESSIONTOKEN]
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
SELLERID: seller-id
				

					{
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "sellers" : [ {
    "sellerId" : "seller-id",
    "name" : "seller-name",
    "lastName" : "seller-lastname",
    "email" : "seller@email.com",
    "mobileNumber" : "+902123650505",
    "status" : "OK",
    "merchant" : {
      "businessId" : "10000000",
      "name" : "ZiraatPay",
      "address" : "İTÜ Ayazağa Kampüsü Teknokent ARI 1 Binası No: 12 34469 Maslak",
      "phone" : "+902123650505",
      "webAddress" : "http://www.asseco-see.com.tr/"
    },
    "iban" : "TR330006100519786457841326",
    "ibanUsd" : "TR330006100519786457841326",
    "ibanEur" : "TR330006100519786457841326",
    "ibanGbp" : "TR330006100519786457841326",
    "accountOwnerName" : "seller-owner-name",
    "accountOwnerLastName" : "seller-owner-lastname"
  } ]
}                      
				

Query Recon Transaction

The Query Recon Transaction request can be used to get transaction details for reconciliation purposes.

Request parameters:

ACTION:

RECONTRANSACTION, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, required Max length: 128 API User.

MERCHANTPASSWORD:

string, required Max length: 128 API User password.

MERCHANT:

string, optional Max length: 128 Merchant business code defined in the system.

PAYMENTSYSTEMTYPE:

string, optional Max length: 32 description See all possible values (29)

PGORDERID:

string, optional Max length: 64 description

PGTRANID:

string, optional Max length: 64 Transaction ID given by payment gateway.

PGTRANAPPRCODE:

string, optional Max length: 64 description

STARTDATE:

date, conditional Max length: 16 Format: [dd-MM-yyyy HH:mm] Start date of the transaction query.

ENDDATE:

date, conditional Max length: 16 Format: [dd-MM-yyyy HH:mm] End date of the transaction query.

OFFSET:

string, optional Max length: 6 Default value: '0' Specifies the number from which the transactions will start for paginated data.

LIMIT:

string, optional Max length: 4 Default value: '1000' The maximum number of transactions in response.

MERCHANTPAYMENTID:

string, optional Max length: 128 Unique Payment ID given by Merchant.

TRANSACTIONTYPE:

string, optional Max length: 32 description See all possible values (11)

ENDOFDAYDATE:

string, optional Max length: 3 description See all possible values (2)

					ACTION: RECONTRANSACTION
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
PAYMENTSYSTEMTYPE: [FINANS]
PGORDERID : [PGORDERID]

				

					
{
  "action" : "RECONTRANSACTION",
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "transactionCount" : "1",
  "totalTransactionCount" : "1",
  "transactionList" : [ {
    "pgTranTraceAudit" : "128613979044",
    "pgTranReturnCode" : "00",
    "pgOrderId" : "10000000-PaymentId-hg0vbZCu5U7R",
    "pgTranApprCode" : "267222",
    "pgTranId" : "21286NzFJ10201",
    "pgTranRefId" : "128613979044",
    "timePsSent" : "2021-10-13 12:49:28.167",
    "timePsReceived" : "2021-10-13 12:49:29.705",
    "timeCreated" : "2021-10-13 12:49:27.880",
    "amount" : 13.43,
    "transactionStatus" : "AP",
    "currency" : "TRY",
    "paymentSystem" : "Finansbank",
    "panLast4" : "5454",
    "transactionType" : "SALE",
    "installmentCount" : 1,
    "cardOwnerMasked" : "N*** s***",
    "customerId" : "Customer-sNFwPkY8",
    "bankCommissionRate" : 0.94,
    "bankCommissionAmount" : -0.1262,
    "bankAmount" : 13.3038,
    "posId" : "11111111111111111111111111111",
    "merchantBusinessId" : "10000000",
    "pgTranDate" : "20211013 13:51:05",
    "merchantPaymentId" : "PaymentId-hg0vbZCu5U7R",
    "paymentSystemType" : "FINANS",
    "bin" : {
      "bin" : "545616",
      "cardBrand" : "VISA",
      "cardType" : "CREDIT",
      "cardLevel" : "GOLD",
      "cardNetwork" : "CARD_FNS",
      "issuer" : "FINANS",
      "virtual" : "NO",
      "countryIsoA3" : "UGA"
    },
    "schemaValue" : {
      "commissionKey" : "CR1",
      "commissionValue" : 0.94,
      "currency" : "TRY",
      "schemaName" : "PSCS_ZERO_COMMISSION",
      "dueDate" : 0
    }
  } ]
}		
				

Query Payment System Pool

The QUERYPAYMENTSYSTEMPOOL Request can be used to get payment system pools

Request parameters:

ACTION:

QUERYPAYMENTSYSTEMPOOL, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, required Max length: 128 API User.

MERCHANTPASSWORD:

string, required Max length: 128 API User password.

STATUS:

string, optional Max length: 2 Status information. See all possible values (4)

					ACTION: QUERYPAYMENTSYSTEMPOOL
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
STATUS: OK
				

					{
    "responseCode": "00",
    "responseMsg": "Approved",
    "PsPools": [
        {
            "name": "All Payment System In Pool",
            "status": "OK"
        },
        {
            "name": "Halkbank",
            "status": "OK"
        },
        {
            "name": "YKB Pool",
            "status": "OK"
        },
        {
            "name": "Akbank Pool",
            "status": "OK"
        },
        {
            "name": "Isbank Pool",
            "status": "OK"
        },
        {
            "name": "Vakifbank Pool",
            "status": "OK"
        },
        {
            "name": "HSBC Pool",
            "status": "OK"
        },
        {
            "name": "Teb Pool",
            "status": "OK"
        },
        {
            "name": "Finans Pool",
            "status": "OK"
        }
    ]
} 	
				

Query Agriculture Template

The QUERYAGRICULTURETEMPLATE request can be used to get agriculture template information from bank side.

Request parameters:

ACTION:

QUERYAGRICULTURETEMPLATE, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, conditional Max length: 128 Merchant business code defined in the system.

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

CURRENCY:

string, conditional Max length: 3 ISO Alpha transaction currency code like TRY, EUR, USD, GBP. Please check https://en.wikipedia.org/wiki/ISO_4217#Position_of_ISO_4217_code_in_amounts for details. See all possible values (33)

PAYMENTSYSTEM:

string, optional Max length: 128 Name of the payment system (bank payment gateway / vPOS account). Specified name should match the one given in ZiraatPay. If not provided, ZiraatPay smart switch feature will be used.

INSTALLMENTS:

integer, optional Max length: 2 Default value: '1' Number of installments. Specified number should exist in the payment system as defined.

CUSTOMER:

string, conditional Max length: 128 The Merchant System ID for customer. It must be unique within a Merchant.

CUSTOMEREMAIL:

string, optional Max length: 64 Customer e-mail. This information should be passed correctly if the customer information services are used.

CUSTOMERNAME:

string, optional Max length: 128 Name of the Customer. This information should be passed correctly if the customer information services are used.

CARDTOKEN:

string, conditional Max length: 64 Secure alphanumeric value replacing card number & expiry date. Required when none of the other card information are provided.

CARDPAN:

string, conditional Max length: 19 PAN (Primary account number), card number. Please check https://en.wikipedia.org/wiki/Bank_card_number for details.

CARDEXPIRY:

string, conditional Max length: 7 Expiry date of the card. Format should be [mm.yy].

NAMEONCARD:

string, conditional Max length: 64 Name on the card.

FORGROUP:

string, optional Max length: 3 Default value: 'YES' Specifies the for group featured usages. Available values are 'yes' and 'no'.

					ACTION: QUERYAGRICULTURETEMPLATE   
MERCHANTUSER: [MERCHANTUSER] 
MERCHANTPASSWORD: [MERCHANTPASSWORD]   
MERCHANT: [MERCHANT]     
CURRENCY: TRY      
MERCHANTPAYMENTID: PaymentId-xKYNX3KFWwfi   
CARDPAN: 5456165456165454   
CARDEXPIRY: 12.2025   
CUSTOMER: Customer-nLRiOspV   
CUSTOMERNAME: Name nLRiOspV   
CUSTOMEREMAIL: nLRiOspV@email.com   
CUSTOMERIP: 127.0.0.1   
CUSTOMERUSERAGENT: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.81 Safari/537.36   
NAMEONCARD: Name nLRiOspV   
CUSTOMERPHONE: +904196113535   
CUSTOMERBIRTHDAY: 01-01-2001   


				

					 {
  "apiMerchantId" : "3123",
  "paymentSystem" : "AgricultureVPOS",
  "paymentSystemType" : "DENIZBANKINTERTECH",
  "paymentSystemEftCode" : "0134",
  "merchantPaymentId" : "PaymentId-xUASUZrAczOj",
  "pgTranId" : "117312***0043",
  "pgTranRefId" : "hostid",
  "pgOrderId" : "10000000-PaymentId-xUASUZrAczOj",
  "pgTranReturnCode" : "00",
  "pgTranApprCode" : "949377",
  "pgTranTraceAudit" : "Success",
  "responseCode" : "00",
  "responseMsg" : "Approved",
  "agricultureTemplate" : [ {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 4,
    "paymentFrequency" : 4,
    "commissionRate" : 1.23
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 5,
    "paymentFrequency" : 5,
    "commissionRate" : 1.71
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 6,
    "paymentFrequency" : 3,
    "commissionRate" : 1.00
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 6,
    "paymentFrequency" : 6,
    "commissionRate" : 3.13
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 8,
    "paymentFrequency" : 1,
    "commissionRate" : 1.00
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 9,
    "paymentFrequency" : 9,
    "commissionRate" : 1.65
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 9,
    "paymentFrequency" : 3,
    "commissionRate" : 3.08
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 10,
    "paymentFrequency" : 1,
    "commissionRate" : 2.35
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 11,
    "paymentFrequency" : 1,
    "commissionRate" : 3.04
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 12,
    "paymentFrequency" : 1,
    "commissionRate" : 3.73
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 12,
    "paymentFrequency" : 3,
    "commissionRate" : 5.12
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 12,
    "paymentFrequency" : 6,
    "commissionRate" : 7.18
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 4,
    "paymentFrequency" : 4,
    "commissionRate" : 1.23
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 11,
    "paymentFrequency" : 1,
    "commissionRate" : 3.04
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 10,
    "paymentFrequency" : 1,
    "commissionRate" : 2.35
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 12,
    "paymentFrequency" : 1,
    "commissionRate" : 3.73
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 12,
    "paymentFrequency" : 3,
    "commissionRate" : 5.12
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 5,
    "paymentFrequency" : 5,
    "commissionRate" : 1.71
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 6,
    "paymentFrequency" : 3,
    "commissionRate" : 1.00
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 9,
    "paymentFrequency" : 9,
    "commissionRate" : 1.65
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 6,
    "paymentFrequency" : 6,
    "commissionRate" : 3.13
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 12,
    "paymentFrequency" : 6,
    "commissionRate" : 7.18
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 9,
    "paymentFrequency" : 3,
    "commissionRate" : 3.08
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 8,
    "paymentFrequency" : 1,
    "commissionRate" : 1.00
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 3,
    "paymentFrequency" : 1,
    "commissionRate" : 2.00
  }, {
    "templateName" : "12 AY VADE 120 BLK A",
    "maturityPeriod" : 3,
    "paymentFrequency" : 3,
    "commissionRate" : 2.00
  } ]
}	
				

Query Application Document

The QUERYAPPLICATIONDOCUMENT request can be used to get application documents

Request parameters:

ACTION:

QUERYAPPLICATIONDOCUMENT, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

APPLICATIONCODE:

string, required Max length: 64 Application code

APPLICATIONDOCUMENTTYPE:

string, optional Max length: 64 Application document type See all possible values (16)

SESSIONTOKEN:

string, conditional Max length: 48 Session token.

			
ACTION: QUERYAPPLICATIONDOCUMENT
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
APPLICATIONCODE: [APPLICATIONCODE]
APPLICATIONDOCUMENTTYPE: [APPLICATIONDOCUMENTTYPE]
			
		

			
{
	"responseCode": "00",
	"responseMsg": "Approved",
	"applicationDocuments": [
		{
			"fileType": "PNG",
			"fileContent": "iVBORw0KGgoAAAANSUhEUgAAAKoAAABVCAYAAADZsn9OAAAMy0lEQVR42u1dD5RUVRm/i4AoQvgvDoW2uIM7b6IV2D/z3pusYXfn/SlFQGZntuwcy+PJP0VaekiKQu0YHkEwTpZUlmigZmaZUSpJ4p9UtPiTAYYKyh+h3ZlZFnYXF7bvu292d968++bPMntmlr7fOffMMvPeffd+93e/+33f/e6DMQKBQCAQCAQCgUAgEAgEAoFAIBBOIhycec6YWHjy1ESTJCfCFZ6eIBtOUiGUDHrCbGSi6cLr41HpSKLZ12MVqScW8W5IXH7B5B7GhpGUCEXWopVjgKCrgJjH+knaX2JRKXEo4p0DZC0jaRGKhniTNF9E0NQCRP5322zv2SQtQlEQm1U+Lt4src9GVE7WSGWYJEYoCo7M8UyMR327cyFqIiI9SBIjFIeo0YrzYFnfkxNRo9LDJDFCUXBodsVHgaibc1r6o94FJDFCUYBx0kTUuzIHZ6q9M+KpIIkRiobW2RVTgIjvZ1jyj8cj3qVbw2wkSYtQVLwTHDcuFpV2CEkalVb2hNkpJCVCSaDF9IxNNHm/HotIy2MR74q2qPcOKCpJhkAgEAgEAoFQLCTCE8+Kz/FMb2+WQu1NlXqsqXJGfJan4i3TcypJh1ACHn/5qLaI99vg3W/C1D5b/LRZ6gDPf01b2KOQpAhFA6bugea8DcNQmYP+0s4PZk4aTxIjFAVIPtCkW3JLSvHeShIjFAX5JKXEopWUlEIoDuKfP//MOB43yUpUqRuIehVJjFA0xKLeIGjVjsxJ09IjPdr40SQtQpE9fzYKyPp4vNm3G0orkDMG/z4Qi0rbW5u8t5CECCVG2PJRrZdXVsXnSNNj0fJyOn1KIBAIBMJJi/bmSeNj4clXxiLe+8HBWg226ZKW2R4F7VeSDqGowIToeLiyPhaR9mbM8I96f4Lnq0hihKLg4BxpAhBxW27n+qVlJDFCUYAZU4lm77rsh/t8h1ubKq8hiRGKBlj6JyWivnmw/K8B7RqHvz+Epb67rVnqiqG2jXoXtUa8l9Cb/QilY7MyVpZeSCoEAoEwqJgaHMcU/QGmGjuSZSvzhz5HgiGUFvymxgJmj62oxvOcwATCYKIl7PGBZ38FlMVYYk3eRYm5F5p7LplwOhGVMNgoY+XBUYwFhR77gbDvDPD2/wDefrZ3T3XG53o0Iiqh8JC1a5mq38tU8zEo90NZzgJGpYOoTdKN8aj3nxmSpo/GIt6HWkC7ElEJhYeqb3GQSdG/kOmW5xgbvrGajcAj0hsZG/Eoc3nnFBGVUECibs6XqORMEYio/xeYFvoYq2m4gH+m75ZUN36EqdpnmGLovKAQ/Q0+lm92uhUbrGNqSOurS4W6VK2eqfUVOdY3jCn1H+dtrdLs2UbTzHOhvvpk3Q2sOniOuApwfBTNy6/pbQeWgBZiakOt5RxlAMrjU58+E4j6poNMsn41/y2XgvLw+UYWhKiVgTFMNsqtMbz43KwOYM2MSmhro63/OC7+RpnXVaKa4U4QwiYW0LfzT1m7kROiunoEkOg78N1LUNqBBMd4CZjd8PkudO5xdzKkoBYGXzUehfIylP8m7z/WX5/RyYPaivF7Jof8Wdq62NJkvK2vA+Fu4N/XNYKgjVehvq5kvV1Q34a0wR8LE2UZ3P8XuPadlGt72/EhfH8Qynq47ntCwir6XbwfAfPv8HlEQKb/8N9yLarxLKsL1ZwAUWHiGnfDby9C2cblEjA2Qjt/7agzAARUjB/CdWvhmrfh82ha/7uhtELZwOt0m0TFI6rxil0g6MGCtpKNNfBbj0Ng9mt3gnatctU8iv5kxvudg3EcyHcTC4rDPdaEsi21q5g/hIPaKqyvV0v79cvg3niebXmdaz7784/nVUdOz9FXDpiosnEln3DOa1+2kVnWIsLrMvf/peQKW7JEfQ0I8EpWkvYL+m9M5L2q5lyuPfMfvBgQa0aORH3G0iQudSn6Wcn79gyMRMZDTFFO69dKBSYpb6Px8wERdVr9J5IaPP26t5jcKKUojPMzysi971h+VrpEddN0mX6XjXmCZfJraRPAqocvNfpOy5xwqddNQOlEzVZ67W1Rf7j2BlNEQTPAtR37mdI4LcX02FUiRB0B970rWOHaoL16Wl0+WM53CfuvGi0wTvvdxxfIinZvyRNVAXtHNW5nteBMyXoT/PtpYadUEBou9faAuGmR0jgE5Zd8+a2uPt3mrNU1nA11PuLQ3lhfvkRVjQQQ6WH4vA/KX2HyPJVy33vJa56Fa+aDuYIvJOs3L9Ae94eu4APnGFBtbv914PSh/RYwlyXt7fQ2rOW/uRXF2HvCRPWYp8JYLBGQtAu+v8bhDAdg+VbNNy3fAOSimLdxx8vRf/1LSR8kfcX8VmkTFZ2RWu0827WWt7tTIMR2HhlIRZU2mnv5OCNREK47PEaQG/bpBGGCRGI3oqrgCNU1KHwQ0Sbz+8dy56kX6OXWhqZyh8IN6Dyp+m8Ecri5YOEpxXjhhImKZpFqHnba9vr1TJzfOgzGZgqT66dzuWSMqBjP5NS+EiLqTq49hKET0IzO68Fj1q8e0PNxMgTMTkedfnNiTkRFTYrhlcLI4kfO+rWlJUNUWZ8Ozzgo0Hr32mzpgULWvi/o05OlS9RM6p6HrYyDgg4tHNDzUUsHjI4BE1U2flywUIpq3CMg0t0lQtRtUP9GwTMfcJhdA+6/du0QI6p2XZZ7XhXYSEuESw+SSDUrLJtVf4I7JGjfYbiot4iW85w1qv7NnPuKmwXoHMk8dryVO0up7RCFcEqHqJZDav/ugzycnTJWrU9gtfonoZ23QdnO71fNWIoMjpxsRP2zQOD3OXaX6vSL4fvVeccwC01U1NqyvoCHbtCezc8rLxWidognkr4WlrkRGZ+L9res3Z7cTcsvZDjEifpHgSCX2jSq36jiGmugYZvCEbUMyPCrnOPCpUvUF+GZ61ycyXmuz0QHUzWeGnj4bGgT9Q0BYX5g209X9dcE5kEr3Ls6aQvelSwruDM2WERFe1tEUuy3CvYtmiy9bVHNN0qYqM+zGjBbVGO3MMjvD00WP1P7isNZtWLIG5L5tP39D4i8/qFLVHSmutIIeAw69I1+QYc08cZA6NKk41NWMGcqE1ExRBUQ7Mooxqrk9uiwIeRMWeEp2bzUEe/EiajovxA/U39a6IAJ+z/UnClFf5s7QOIZerNgB6ODKaHZKcJZKBiQFwbF689EVNxKVM19aYN6lJWXjxoUr9+vf3nw46j+sfD3E8LdNtzTd7Zzv6P/SmPDyeH19yY2oJdsEyDanYI4HiaFpBJb0W8VDMhvxYMX+qwj4F8ooqoY5DcOpPUrLoxOTFRO4xlhuRN1i6Atd7JML5UoBFF57NmodRmzHQ4TwBl37XTJUsOA/9qhR1RLU+6FTs3kZ4EUTRXmYFqd+ZNdOOYNgro6k5sIZX1hKwxguyVMFIKoddokmEDvC/NGrV0sy9nCLVVZu0e4PexKVMGgYvJLnVbP5eXXQjytzpPyP/MViqjWBL9FYAIc56mI9nbuEphpC20HErH/ivHToedMpXdMNQ4L94Et4RxiNdoUu6AbfC4e9L+SOaGLeWZSprBVIYjKY7g8f9Q5adCpk6Edirkc+vYP16iAO1EXuUzubr7FaeV57mPVmndQiIohp4DxnHA8alO2s1XjQcGYJridihOJ57Nyx7d7KBK1O/f8UZcdKUwQyT0MMnhef29yTK79SdeqbkTlK0yW+DDu4KUmRheSqLxv4JwKg/RGS18uLa8LyJtzel+arEqaqH7tu9ymzBQct0i6gmdAuS67xvosQrESlDHRYjAD/tZJhWykOgLku4OHbXIiKti0mAeQuc73bIk9hSYqbmejZhSRDY9z95lYvP8dWUjaxmRwJlX9saEVnsLsJ1n7IgiyXbiEyw2NWffYUbCqcR2PnzoF38UnxJSG8clB3JRCvs0g4ZECZ+Qmvmz317EP6qjO2kc8MYDngRRB/Nd63jqYWBfxgZdDC/q0Ci7hdaFwxmB6nTarL40w3bxQjKtsISCUJybR9Lf/AKvR6xz14rYobnGmZofh8RjRiy6qqkYnzaijtkQdTB7qQ/gUrtnTJ2HqaQbuYEH9sj6/b0VVwYypM746NOKomEOKg8iPc2BeKuYyBvN7lyfWgQfq8CAf1oNhI1/wDIfXOQGum5CWs+pk3XA+ONkO4bntUuHxCiQ3tgOX74t4ZMMeT0QHCJ/Bckx2weunBst5VIQTHpxG9/al9jPzgUZsA29HDgcfUWngtVbOr3v/sb9IStmYybe4q4ITHfLG8B1/brCE3tk6kJ0pAoGISiAQUQlEVAKBiEogouq/EyRXXEaCIZQWMHY4HbOMDIUX6ygt/W8dBAKBQCAQCAQCgUAgEAgEAuFkwP8ATX9UIiXmF98AAAAASUVORK5CYII=",
			"documentType": "IDENTITY",
			"fileName": "image.png",
			"filePath" : "/application-files/ZCKZAPMGG3LZYTAU7KMWV2IRBAFXBSGXNAYDEIQVUWGMK4IB/IDENTITY"
		}
	]
}
			
		

Query Transaction Hosting Commission

The QUERYTRANSACTIONHOSTINGCOMMISSION request can be used to get transaction hosting commission

Request parameters:

ACTION:

QUERYTRANSACTIONHOSTINGCOMMISSION, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

MERCHANT:

string, optional Max length: 128 Merchant business code defined in the system.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

			ACTION: QUERYTRANSACTIONHOSTINGCOMMISSION
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
SESSIONTOKEN: [SESSIONTOKEN]
			
		

			
				{
    "responseCode": "00",
    "responseMsg": "Approved",
    "transactionHostingCommissionSchemaList": [
        {
            "name": "TEST_THCS"
        },
        {
            "name": "THCS_ZERO_COMMISSION"
        },
        {
            "name": "thcDev"
        }
    ]
}
			
		

Query OTP(One time password)

The QUERYOTP request can be used to get OTP(One time password).

Request parameters:

ACTION:

QUERYOTP, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANTUSER:

string, conditional Max length: 128 API User.

MERCHANTPASSWORD:

string, conditional Max length: 128 API User password.

SESSIONTOKEN:

string, optional Max length: 48 Session token.

OTPCODE:

string, required Max length: 6 description

EMAIL:

string, required Max length: 64 description

				
ACTION: QUERYOTP
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
OTPCODE: [OTPCODE]
				
			

				
{
	"responseCode": "00",
	"responseMsg": "Approved",
	"otpCode": "107038",
	"createdTs": "2022-08-18 16:08:43.578",
	"status": "OK"
}
				
			

Query Merchant Information

The QUERYMERCHANTINFORMATION request can be used to query merchant users

Request parameters:

ACTION:

QUERYMERCHANTINFORMATION, required Max length: 128 Core parameter which specifies the main action for the API call.

MERCHANT:

string, required Max length: 128 Merchant business code defined in the system.

MERCHANTUSER:

string, required Max length: 128 API User.

MERCHANTPASSWORD:

string, required Max length: 128 API User password.

			
ACTION: QUERYMERCHANTINFORMATION
MERCHANT: [MERCHANT]
MERCHANTUSER: [MERCHANTUSER]
MERCHANTPASSWORD: [MERCHANTPASSWORD]
			
		

			
{
  "responseCode": "00",
  "responseMsg": "Approved",
  "merchantInformationList": [
  {
    "merchantName": "Test Merchant",
	"merchantUserInformation": [
	{
	  "merchantUser": "Test User",
	  "merchantPhone": "+902123456789",
	  "merchantEmail": "merchantuser@testmerchant.com"
	 }
	]
   }
 ]
}