-
Multi Bank Virtual POS
Multi Bank Virtual POS
Transaction Inquiry General Concepts
This service is utilized to retrieve the most up-to-date status of transactions conducted via Tami. By transmitting 'true', the transaction's order number and transaction details can be queried. This service is designed to exhibit the latest transaction status and provide details on all transactions associated with the specified order. The information output is presented in the English language.
Tami Test/Prod Portal Information
Before going live with your integration, you can use the Tami Test Portal to test without creating any real money movement.
Test Portal address: https://sandbox-portal.tami.com.tr
If you would like to log in to the test portal to view your transactions and perform cancellations/refunds when needed, a dedicated test portal user must be defined for you. You can reach our support team for this at TeknikDestek@tami.com.tr.
Prod Portal address: https://portal.tami.com.tr
For your production environment credentials, you can register via this address or contact our ecommerce support team.
Tami Test / Prod API Users
Two different environments are used when integrating with Tami’s APIs: Sandbox (Test) and Prod (Production).
- Test (Sandbox) Environment
This lets you test your integration without creating any real money movement. Your requests are sent to the test endpoints and can be tracked via the Tami Test Portal above.
Below are the credentials you can use to send a test request via the API in the sandbox environment:
| Field | Value |
|---|---|
| Merchant Number | 77006950 |
| Terminal Number | 84006953 |
| Secret Key | 0edad05a-7ea7-40f1-a80c-d600121ca51b |
- Prod (Production) Environment
This is the environment where live transactions take place and real payments are collected.
For your production environment credentials, you can register via https://portal.tami.com.tr or contact our e-commerce support team.
Generating the PG Auth Token
For requests sent to Virtual POS services, the PG-Auth-Token field must be included in the header.
The PG-Auth-Token is generated in the following format:
MerchantNumber:TerminalNumber:Hash
The Hash value is generated by concatenating your Merchant Number, Terminal Number, and Secret Key (in that order), hashing the result with the SHA-256 algorithm, and converting the result to Base64 format.
Below is a sample Java code block demonstrating this calculation:
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}\n
You can generate the PG-Auth-Token header value by combining the Hash value you generated with your Merchant Number and Terminal Number in the format above.
Inquiry Transaction API Information
The endpoint information to be used for the transaction inquiry is below:
| Environment | Endpoint |
|---|---|
| Test (Sandbox) | https://sandbox-paymentapi.tami.com.tr/api/v0/payment/orderQuery |
| Production (Prod) | https://paymentapi.tami.com.tr/api/v0/payment/orderQuery |
You must send your requests using the POST method to the endpoint appropriate for the environment you are working in (test/production).
How the Inquiry Request Is Sent
For transaction inquiry requests, the values in the body of the request sent are not expected to be transmitted in plain form; instead, a single signed and encrypted value is expected. This value is sent in the signedRequest field.
The response returned by Tami is likewise signed and encrypted, and is delivered in the signedResponse field. Detailed information on how to decode the signedResponse value is provided in the headings below.
In addition, the following information must also be sent in the header:
- PG-Auth-Token: How this is calculated is explained above under “Generating the PG Auth Token.”
- CorrelationId: A variable value that must be unique for each request.
- PG-Api-Version: Must be sent as v4.
Parameters to Be Signed and Encrypted, with Descriptions
For the transaction inquiry request, the values in the request body are not sent in plain form; the encrypted value is sent in the signedRequest field.
The signedRequest value is obtained by encrypting a request constructed from the fields listed in the table below.
The fields to be included in signedRequest, along with their rules, are specified in the table below. Abbreviations: (O) Optional, (M) Mandatory, (C) Conditional.
| Field | Format | O/M/C | Description |
|---|---|---|---|
| orderId | String | C | The order number information of the sales transaction to be queried. Mandatory if the startDate and endDate fields are not sent. |
| isTransactionDetail | Boolean | O | If true is sent, all transactions that have occurred on the order from the beginning are shared. If false, blank, or not sent at all, only information about the order’s current status is delivered. |
| startDate | String | C | Mandatory if the inquiry is to be made based on a date range rather than an order number. Example format: "DD-MM-YYYY HH:MM:SS". A maximum range of 30 days can be given between the start and end dates. |
| endDate | String | C | Mandatory if the inquiry is to be made based on a date range rather than an order number. Example format: "DD-MM-YYYY HH:MM:SS". |
| page | Integer | O | Sent if the transactions within the queried date range are to be retrieved page by page. 0 must be sent for the first page. |
| size | Integer | O | Indicates the number of transactions to be shown per page when pagination is used. |
| sortField | String | O | Allows the inquiry results to be returned sorted by a specific field. Example: "orderDate". |
| sortDirection | Enum | O | Determines whether the sort order is ascending or descending. Possible values: ASC, DESC. |
Generating the Request Token (signedRequest)
For security purposes, information in requests sent by merchants is not sent in plain form. Instead, the request body is expected to contain the signedRequest value, which is generated by signing and encrypting a request built according to the fields requested by Tami.
For a detailed explanation of the signedRequest generation steps and code samples, please see the Generating the Request Token (signedRequest) page.
API Request Example
{\n \"signedRequest\": \"eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU4R0NNIiwiYWxnIjoiZGlyIn0..7NrZMmVDSawFXiuawbuf.3zkmpc-anpDVQ_R4wJbzqmecZJxEz1YZQuoiezoOi-z5VvU-MmFi1RhlDOmgrqGBi6Ts0ncbSK3pldAzxGWcgE41LbHw9rqxjjcXppdDyU2MtrsaY1yltpdcuugDClki...\"\n}
The signedRequest value above has been shortened for example/test purposes. A real request contains a much longer JWE (encrypted token) value. If you would like to see what the pre-encryption (plain) body looks like, the fields to be encrypted are listed in the “Parameters to Be Signed and Encrypted” table above.
API Response Example
Response for a successful transaction:
{\n \"signedResponse\": \"eyJraWQiOiI2NzA2ZTkwNSe5MDY0ZXl1YmxxbmNqWoUoWpJjp7InM1Y5Y5VpYjZ7YWVNiOiIzInZ2IiwiYWxnIjoiZGly...\"\n}
Response Parameters and Descriptions
When the transaction is successful, the response delivered by Tami contains only the signedResponse field. All other fields listed in the table below (success, systemTime, correlationId, content, pageInfo, etc.) are not present in plain form in this case; all of them are carried in encrypted form inside the signedResponse field. You can only access these fields once the signedResponse value has been decoded. The decoding steps are described in the next heading.
When the transaction is unsuccessful, signedResponse is not returned at all; in this case success, systemTime, correlationId, errorCode, and errorMessage fields are returned directly in plain form.
Main fields
| Parameter Name | Format | Where It Appears | Description |
|---|---|---|---|
| success | String | Inside signedResponse (plain if transaction unsuccessful) | The result of the inquiry request. If true, data for the queried transaction is returned. |
| systemTime | DateTime | Inside signedResponse (plain if transaction unsuccessful) | Indicates the date and time the response was generated by Tami. |
| correlationId | String | Inside signedResponse (plain if transaction unsuccessful) | The transaction number sent by the merchant in the inquiry request. |
| errorCode | String | Plain (only when success:false) | Present in the response if the success field is false; this is the code of the error received. |
| errorMessage | String | Plain (only when success:false) | Present in the response if the success field is false; this is the description of the error received. |
| content | List | Inside signedResponse | The list of details for the queried transaction(s). Each element represents the result for a single order. |
| pageInfo | Object | Inside signedResponse | Contains information related to the pagination of the transactions in the returned response. |
content
| Parameter Name | Format | Where It Appears | Description |
|---|---|---|---|
| content/orderId | String | Inside signedResponse | The number of the queried order. |
| content/amount | Number | Inside signedResponse | The current, actionable amount information of the transaction. For example, if a refund of 20 TRY was made after a sales transaction of 100 TRY, this field shows 80 TRY. |
| content/orderDate | DateTime | Inside signedResponse | The date the order was created. |
| content/currency | String | Inside signedResponse | The currency code of the transaction. |
| content/installmentCount | Number | Inside signedResponse | The number of installments for the transaction. |
| content/orderStatus | String | Inside signedResponse | Indicates the final transaction type of the order. Can take the values AUTH, REVERSE, REFUND, PARTIAL_REFUND, PRE_AUTH, POST_AUTH, CHARGEBACK. |
| content/paymentStatus | String | Inside signedResponse | Indicates the final status of the transaction. Can take the values NOT_COMPLETED, SUCCESS, FAIL, TIME_OUT. |
| content/commissionRate | BigDecimal | Inside signedResponse | The commission rate information for the transaction. |
| content/commissionAmount | BigDecimal | Inside signedResponse | Indicates the calculated commission amount for the transaction. |
| content/transactionFee | BigDecimal | Inside signedResponse | The transaction fee information. |
| content/holdPeriod | Integer | Inside signedResponse | Indicates the number of hold days for the transaction. |
| content/card | Object | Inside signedResponse | Contains information about the card used in the transaction. |
| content/transactions | List | Inside signedResponse | If isTransactionDetail: true is sent, the data for all transactions performed on the relevant order is returned in this field. |
content/card
| Parameter Name | Format | Where It Appears | Description |
|---|---|---|---|
| content/card/binNumber | String | Inside signedResponse | The first 8 digits of the card used in the transaction. |
| content/card/cardBrand | String | Inside signedResponse | Indicates the bank of the card used in the transaction. |
| content/card/cardOrganization | String | Inside signedResponse | The card organization information. AMEX, TROY, MASTERCARD, VISA, etc. |
| content/card/cardType | String | Inside signedResponse | The card type. CREDIT, DEBIT |
content/transactions
| Parameter Name | Format | Where It Appears | Description |
|---|---|---|---|
| content/transactions/amount | Number | Inside signedResponse | Indicates the amount of the relevant transaction. |
| content/transactions/transactionType | String | Inside signedResponse | The transaction type of the relevant record. |
| content/transactions/transactionStatus | String | Inside signedResponse | The success status of the relevant record. |
| content/transactions/transactionDate | DateTime | Inside signedResponse | The date the relevant record took place. |
| content/transactions/reason | String | Inside signedResponse | If a reason field was sent when the transaction was refunded/cancelled, this field is also returned in the inquiry. |
| content/transactions/bankAuthCode | String | Inside signedResponse | Bank authorization code. |
| content/transactions/bankReferenceNumber | String | Inside signedResponse | Retrieval reference number (RetRef) for the transaction. |
| content/transactions/fraudStatus | Boolean | Inside signedResponse | Indicates the status following fraud checks. |
pageInfo
| Parameter Name | Format | Where It Appears | Description |
|---|---|---|---|
| pageInfo/page | Integer | Inside signedResponse | Indicates the page number of the returned data. |
| pageInfo/size | Integer | Inside signedResponse | Indicates the number of transactions on the page in the returned response. |
| pageInfo/totalElements | Integer | Inside signedResponse | If page-by-page return was requested in the request, this indicates the total number of transactions in the queried date range. Each distinct order number is counted as 1 transaction; sub-transactions belonging to an order, such as cancellations/refunds, are not included in this count. |
| pageInfo/totalPages | Integer | Inside signedResponse | If page-by-page return was requested in the request, this indicates, based on the size value entered, the total number of pages in the queried date range. |
| pageInfo/isFirst | Boolean | Inside signedResponse | Shown as true if the returned page is the first page. |
| pageInfo/isLast | Boolean | Inside signedResponse | Shown as true if the returned page is the last page. |
| pageInfo/hasNext | Boolean | Inside signedResponse | Shown as true if a next page exists. |
| pageInfo/hasPrevious | Boolean | Inside signedResponse | Shown as true if a previous page exists. |
Decoding the Response Token (signedResponse)
The steps required to decode the value delivered in the signedResponse field in order to access the parameters above will be provided in this section.
For a detailed explanation of the decoding steps and code samples, please see the Decoding the Response Token (signedResponse) page.
Code Examples
Below are links to code samples written in various programming languages. Through the link for your preferred programming language, you can examine in detail code written with pre-defined example values.
These samples contain code covering the relevant transaction type, and since they are written in different languages, it is also possible to observe various approaches and practices. This gives you the opportunity to work with clearer and more authentic examples suited to your preferred programming language.
- For C# Code Samples, click here.
- For VB.Net Code Samples, click here.
- For Java Code Samples, click here.
- For PHP Code Samples, click here.
- For NodeJS Code Samples, click here.
Please note that these samples are written with pre-defined values, and the necessary adaptation and security measures may need to be taken for their use in real projects.
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.
