-
Multi Bank Virtual POS
Multi Bank Virtual POS
Generating the Request Token General Description
This page explains, step by step, how to generate the signedRequest token used when sending requests to Tami Virtual POS APIs (pre-authorization, sales, etc.).
What is it, what is it for?
Requests sent to Tami are not sent as plain JSON. Instead, the request body is first signed (HS512 → JWS), and then encrypted (dir + A256GCM → JWE). The resulting token is delivered to the API as follows:
{ "signedRequest": "<generated-token>" }
Because the token is encrypted, it cannot be opened on jwt.io. This is not an error, it is expected behavior.
What do you need?
The table below uses Test (Sandbox) Environment credentials as an example. When performing transactions in the production (prod) environment, you must use your own merchant’s Merchant and Terminal numbers.
| Information | Example |
|---|---|
| Merchant number | 77006950 |
| Terminal number | 84006953 |
| JWK JSON (merchant-specific key file) | Below |
json
{
"kty": "oct",
"kid": "40e74b0c-75d4-4962-9792-c21464f8111b",
"k": "UXchS35U-_CfusZpw1U3LAqVVB7dcUwiettOPYulXHeBLbdjQBTsy42SF8bEyf4Zo-rJKckIU8o7WO6IqDbpzg",
"alg": "HS512"
}
- kid → The key identifier; it is written into the token header, and the server uses it to match you to the correct merchant.
- k → The Base64URL-encoded secret key; signing and encryption are derived from this value.
If you do not have a JWK, it should be requested from your merchant representative. The k value must not be shared with any person or system, and must not be committed to a source code repository (git).
Generating the token in 5 steps
A ready-made code example for your preferred language is available in the Code Samples section below. The steps below show the logic; the same flow can be built with any JOSE/JWT library (Java, Node, Python, etc.).
Step 1: Loading the JWK
The JWK JSON is given to the library as is. Your signing key is the decoded form of the k value.
signingKey = JWK.parse(jwkJson)
Step 2: Deriving the encryption key
The SHA-256 digest of the signing key is the encryption key (32 bytes → A256GCM):
encryptionKey = SHA-256( base64UrlDecode(k) )
Step 3: Preparing the claims
| Claim | Value |
|---|---|
| iss | “77006950:84006953” (merchant:terminal) |
| aud | “tami” (fixed) |
| jti | a new UUID generated for each token |
| iat / nbf | the moment of generation |
| exp | 10 minutes after the moment of generation |
| tami:body | the request body (the JSON defined in the service contract) |
| tami:apiVersion | “v4” (fixed) |
Step 4: Signing (JWS)
The claims are signed with HS512. The header must include kid and typ: JWT:
header = { alg: "HS512", kid: "<kid>", typ: "JWT" }
Step 5: Encrypting (JWE)
The signed JWT is encrypted with the following header and serialized:
header = { alg: "dir", enc: "A256GCM", cty: "JWT" }
Result: a compact token made up of 5 parts separated by dots is obtained. This is your signedRequest value.
Sending to the API
POST /api/v0/payment/auth
Content-Type: application/json
{ "signedRequest": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..q8rM..." }
Rules
- The token is valid for 10 minutes; a new token must be generated before each transaction.
- The same token can be used only once (checked by jti).
- The token must consist of 5 parts; if not, this indicates a problem in the generation process.
- Your server clock must be correct (synchronized via NTP).
Code Samples
Below are links to dedicated 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 5 steps of the signedRequest token generation flow, 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 Java Code Samples, click here.
- For PHP Code Samples, click here.
- For C# Code Samples, click here.
- For VB.Net 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.
The k and kid values are unique values specific to each merchant. In the production (prod) environment, merchants can view them on the Merchant Settings > POS Management page of the Merchant Portal. Updating this information at regular intervals for transaction security is the merchant's responsibility.
When testing transactions in the Test (Sandbox) environment, the k and kid values can be viewed in the same way through the test portal. If you need any support, you can reach our support team at TeknikDestek@tami.com.tr.
