-
Multi Bank Virtual POS
Multi Bank Virtual POS
Point Sale General Description
When transmitting a single withdrawal or installment sales transaction via Tami, the point information to be used is also sent. The point type returned in the point inquiry response and the point amount desired to be used are sent in the request of the sales transaction.
In the sales request, the total transaction amount is sent in the amount field. You must send the amount of the amount you want to use as points in the amount below the rewardToBeUserd field.
Test/Prod Envirenement API User Information
For Virtual POS transactions, merchants can use the merchant information given in the table below for the controls they want to perform in the test environment.
For Virtual POS transactions to be realized from the prod environment via Tami, the merchant number is obtained by making an application.
You can access the Sandbox test portal at https://sandbox-portal.tami.com.tr. When you log in to the test portal with the users provided below, the transactions made by the workplace connected to this user can be viewed. Transactions can be canceled/refunded.
| User Phone Number | User Password | Sms / Email Otp | Workplace Number | Terminal Number | Secret Key |
|---|---|---|---|---|---|
| 5346484700 | 147850 | 147852 | 77006950 | 84006953 | 0edad05a-7ea7-40f1-a80c-d600121ca51b |
| 5346484709 | 147850 | 147852 | 77006951 | 84006954 | c8581bb6-a4b2-4925-8c94-529fc651399e |
| 5346484803 | 147850 | 147852 | 77006952 | 84006955 | ff7d4895-0c32-4f48-86ab-fb9ecca9f3d7 |
| 5346484807 | 147850 | 147852 | 77006953 | 84006956 | 33124ff0-0b19-4cf9-b002-13a35eae865b |
| 5346484800 | 147850 | 147852 | 77006954 | 84006957 | 7daf9631-e136-4164-9ddb-dd1c02df851d |
| 5346484808 | 147850 | 147852 | 77006956 | 84006959 | fe6f3fff-0434-4932-a27d-bb3dac9de49d |
Hash Calculation
The request sent for many transaction types should include the PG-Auth-Token in the header information. The PG-Auth-Token consists of the values "MerchantNumber:TerminalNumber:Hash".
When calculating the hash here, the merchantNumber, terminalNumber, and secretKey information belonging to the merchant are hashed with sha256 and converted to a string.
public class SHA256Example {\n public static String sha256(Long merchantNumber, Long terminalNumber, String secretKey) {\n String text = merchantNumber.toString() + terminalNumber.toString() + secretKey;\n try {\n MessageDigest digest = MessageDigest.getInstance(\"SHA-256\");\n byte[] hash = digest.digest(text.getBytes(StandardCharsets.UTF_8));\n String sha256Hex = DatatypeConverter.printBase64Binary(hash);\n return sha256Hex;\n } catch (NoSuchAlgorithmException e) {\n e.printStackTrace();\n return null;\n }\n }\n}
TAMİ Test Portal Information
You can access the Tami test portal at https://sandbox-portal.tami.com.tr. From this address, you can view the portal screen with the users specified above.
For your production environment information you can become a member at https://portal.tami.com.tr or You can apply to the e-commerce support unit.
Sale Transaction API Information
In test environment, the "https://sandbox-paymentapi.tami.com.tr/payment/auth" URL will be used.
In production environment, the "https://paymentapi.tami.com.tr/payment/auth" URL will be used.
Request Parameters and Descriptions
| Field | Format | Maximum Size | (O)ptional / (C)onditional / (M)andatory | Description |
|---|---|---|---|---|
| orderId | String | (2-36) | M | The payment request is a singular communication information used in the interaction between Tami-customer. For the merchant and POS pair, this value must be singular. |
| amount | Decimal | M | The amount is the transaction. The fractional separator must be a period (.). | |
| rewardToBeUsed altındaki (type) | Char | M | This is the desired Point type to be used. Values it can take (BNS, TotalPoint, Chippara, ParaPuan, KullanPuan) | |
| rewardToBeUsed altındaki (amount) | Decimal | M | It is the amount of Points desired to be used. The odd separator must be made with a period (.) | |
| currency | String | 3 | M | Specifies the currency code of the transaction. Example: TRY should be sent for TL. |
| installmentCount | Number | M | This is the installment information of the desired transaction. For cash transactions, 1 must be sent. Sending 0 is not accepted. | |
| paymentGroup | String | M | Payment group, default PRODUCT should be forwarded | |
| paymentChannel | enum | O | Payment channel. Valid values are provided in the enum: WEB, MOBILE, MOBILE_WEB, MOBILE_IOS, MOBILE_ANDROID, MOBILE_WINDOWS, MOBILE_TABLET, MOBILE_PHONE | |
| callbackUrl | String | C | If a transaction is desired to be carried out in 3D, it must be sent. The address to which the 3D verification result will be returned is the address associated with the merchant. | |
| card | Object | M | ||
| cvv | String | M | The security code of the card from which the payment will be taken. | |
| expireMonth | Number | (1-12) | M | Expiration date and month of the card from which the payment will be taken. |
| expireYear | Number | 4 | M | The expiration date and year of the card from which the payment will be taken. |
| holderName | String | 30 | M | Name and surname of the cardholder from whom the payment will be received. |
| number | String | (5-35) | M | The card number from which the payment will be received. |
| billingAddress | Object | O | ||
| address | String | 400 | O | Billing address information on the merchant side. |
| emailAddress | String | O | E-mail information of the merchant | |
| city | String | 30 | O | Billing address city information on the merchant side. |
| companyName | String | 100 | O | Trade name information of the merchant. |
| country | String | 50 | O | Country of the billing address on the merchant side. |
| contactName | String | 30 | O | Billing address, name and surname information on the merchant side. |
| phone | String | O | GSM number of the buyer on the merchant side. | |
| zipCode | String | 15 | O | Postal code of the billing address on the merchant side. |
| district | String | 50 | O | Neighborhood information of the billing address on the merchant side. |
| shippingAddress | Object | O | ||
| address | String | 400 | O | Delivery address information on the merchant side. |
| emailAddress | String | O | E-mail information of the merchant | |
| city | String | 30 | O | Delivery address city information on the merchant side. |
| country | String | 50 | O | Delivery address country information on the merchant side. |
| contactName | String | 30 | O | Delivery address, name and surname information on the merchant side. |
| zipCode | String | 15 | O | Postal code information of the delivery address on the merchant side. |
| district | String | 50 | O | Delivery address neighborhood information on the merchant side. |
| buyer | Object | M | Contains information about the buyer on the merchant side | |
| ipAddress | String | M | It is the IP address of the buyer on the merchant side. The real IP address of the recipient must be transmitted. | |
| buyerId | String | 50 | C | The buyer's id on the merchant side. |
| name | String | C | Name of the buyer on the merchant side. | |
| surName | String | C | Last name of the buyer on the merchant side. Buyer object is an optional field, but if any field from the buyer object is sent, surname is required. | |
| identityNumber | String | 11 | O | Identification number of the buyer on the merchant side. |
| city | String | 50 | O | City information of the recipient on the merchant side. |
| country | String | 50 | O | Country information of the buyer on the merchant side. |
| emailAddress | String | M | The e-mail information of the recipient on the merchant side. The e-mail address must be a valid and accessible address of the recipient. | |
| phoneNumber | String | M | The GSM number of the buyer on the merchant side. | |
| registrationAddress | String | 400 | O | Recipient's registration address on the merchant side. |
| zipCode | String | 15 | O | Postal code of the recipient on the merchant side. |
| registrationDate | O | Recording date of the buyer on the merchant side. The date format should be 2015-09-17 23:45:06. | ||
| lastLoginDate | O | Last receipt date for the merchant-side buyer. The date format should be 2015-09-17 23:45:06. | ||
| basket | O | |||
| basketId | String | C | The id of the basket on the merchant side. If an item is sent in the basket, it is mandatory to send basketId. | |
| basket/basketItems | List | O | ||
| itemId | String | C | The id of the product in the basket on the merchant side. If the item is transmitted in the basket, it is mandatory to send itemId. | |
| itemType | String | C | The type of the product in the cart at the merchant. Valid enum values: PHYSICAL and VIRTUAL. If an item is sent in the basket, the itemType must be sent. | |
| name | String | C | The name of the product in the basket on the merchant side. If the item is sent in the basket, it is mandatory to send the name. | |
| category | String | O | The category of the product in the cart on the merchant side. | |
| subCategory | String | O | Subcategory of the product in the cart on the merchant side. | |
| unitPrice | Decimal | min 0.0 | O | The single amount of the product in the basket on the merchant side. |
| totalPrice | Decimal | min 0.0 | C | The total amount of the product in the basket on the merchant side. It cannot be 0 and less than 0, the sum of the amounts must be equal to the basket amount. If an item is sent in the basket, totalPrice must be sent. Unitprice * numberOfProducts = totalPrice |
| numberOfProducts | Number | 1-99999 | O | The number of products in the basket on the merchant side. |
| securityHash | String | M | It is the value expected to be calculated and transmitted according in the document. If it is missing or incorrect, the transaction is not routed to the bank, an error is given. |
API Request Example
{\n \"amount\": 20,\n \"orderId\": \"7707670050778\",\n \"currency\": \"TRY\",\n \"installmentCount\": 1,\n \"card\": {\n \"holderName\": \"Ad Soyad\",\n \"cvv\": \"\",\n \"expireMonth\": 12,\n \"expireYear\": 2026,\n \"number\": \"5406675406675403\"\n },\n \"isRewardToBeUsed\": true,\n \"rewardToBeUsed\": {\n \"list\": [\n {\n \"type\": \"BNS\",\n \"amount\": 20\n }\n ]\n },\n \"billingAddress\": {\n \"emailAddress\": \"esrasevinc@gmail.com\",\n \"address\": \"İnşirah sok. No:70 Etiler/Beşiktaş\",\n \"city\": \"İstanbul\",\n \"companyName\": \"Yılmazlar A.Ş\",\n \"country\": \"Türkiye\",\n \"district\": \"Bebek Mah.\",\n \"contactName\": \"Esra Sevinç\",\n \"phoneNumber\": \"05364604016\",\n \"zipCode\": \"343400\"\n },\n \"shippingAddress\": {\n \"emailAddress\": \"yilmaz@gmail.com\",\n \"address\": \"Levent Mah. Nispetiye Cad. No:8 Beşiktaş\",\n \"city\": \"İstanbul\",\n \"companyName\": \"Yılmazlar Şirketi\",\n \"country\": \"Türkiye\",\n \"district\": \"Levent\",\n \"contactName\": \"Nilüfer\",\n \"phoneNumber\": \"05346484777\",\n \"zipCode\": \"3434221\"\n },\n \"buyer\": {\n \"ipAddress\": \"192.168.1.70\",\n \"buyerId\": \"678654\",\n \"name\": \"Yeşim\",\n \"surName\": \"Çınar\",\n \"identityNumber\": 28629160374,\n \"city\": \"İstanbul\",\n \"country\": \"Türkiye\",\n \"zipCode\": \"348222\",\n \"emailAddress\": \"yesim.cinar@gmail.com\",\n \"phoneNumber\": \"0536460996\",\n \"registrationAddress\": \"Ortaköy Mah. Ulus Sok. Beşiktaş\",\n \"lastLoginDate\": \"2022-11-05T13:39:11.332\",\n \"registrationDate\": \"2022-10-11T12:59:11.332\"\n },\n \"basket\": {\n \"basketId\": \"736735353u3ye\",\n \"basketItems\": [\n {\n \"itemId\": \"786543r453\",\n \"name\": \"Lego Duplo\",\n \"itemType\": \"PHYSICAL\",\n \"category\": \"oyuncak\",\n \"subCategory\": \"alt oyuncak\",\n \"numberOfProducts\": 1,\n \"totalPrice\": 20,\n \"unitPrice\": 1\n }\n ]\n },\n \"paymentGroup\": \"PRODUCT\",\n \"securityHash\":\"7SuvE7r26oM83j91VKgLjDmfo62Dv2JFfN3jMvSdrYU=\"\n }\n
API Request Response Example
{\n \"success\": true,\n \"systemTime\": \"2024-01-18T14:43:34.42569587\",\n \"correlationId\": \"correlation1691\",\n \"securityHash\": \"53673839djf93klw00llr==\",\n \"orderId\": \"onurqx1dtwzqsaada2\",\n \"amount\": 5,\n \"currency\": \"TRY\",\n \"installmentCount\": 1,\n \"card\": {\n \"binNumber\": \"48249105\",\n \"maskedNumber\": \"4824-9105-xxxx-xx14\",\n \"cardBrand\": \"Garanti\",\n \"cardOrganization\": \"VISA\",\n \"cardType\": \"CREDIT\"\n },\n \"rewardAmount\": 2\n}
Request Parameters and Descriptions
| Field | Format | Description |
|---|---|---|
| success | String | If it returns true, the sale is successful; if it returns false, an error is received. Error details will be shared in the error code and error message fields. |
| systemTime | dateTime | transaction date |
| correlationId | String | transaction number |
| orderId | String | order number |
| amount | Number | transaction amount |
| currency | String | transaction currency |
| card/binNumber | String | first 8 digits of credit card |
| card/maskedNumber | String | masked card no. |
| card/cardBrand | String | card brand |
| card/cardOrganization | String | card organization |
| card/cardType | String | card type |
| errorCode | String | error code |
| errorMessage | String | error message |
| rewardAmount | String | Amount of Points Used |
| securityHash | String | The value to be used to determine that the result of the operation came from the correct source. The documentation specifies how it should be calculated. |
Security Hash Calculation
You can use the documentation here to calculate the securityHash field in service requests and incoming service responses.
Error Codes
You can access the list of error codees on this page.
Test Cards
You can access the list of test cards on this page.
