TNS Payments Developer Portal

## Sections
• [Home](https://developer.pay.tnsi.com/api/supported-libraries.md): Welcome to the TNS developer portal. You'll find comprehensive guides and documentation to help you start working with TNS as quickly as possible, as well as support if you get stuck. Let's jump right in!
• [HMAC Authentication](https://developer.pay.tnsi.com/api/hmac-authentication.md): Every request to TNS Gateway API is to be authenticated by HMAC by creating a signature of the request payload using API Key and Secret provided by TNS. How to generate hmac APIKey (Provided by TNS) Secret (Provided by TNS) Take the timestamp at the time of signing Get data/ payload (which will be sent as request body) as string Concatenate APIKey “:” timestamp “:” payload Generate HMAC by using Secret provided by TNS HMAC should be generated by using SHA512 algorithm. Here's a simple example of HMAC calculation using JavaScript: To use CryptoJS.HmacSHA512 , you need to ensure that you have the necessary prerequisites set up, including the proper installation and importation of the crypto-js library. Include the CryptoJS library in your HTML file: Add the following <script> tag to your HTML file to load CryptoJS from a CDN. Javascript <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js"></script> Javascript function generateHMAC(apiKey, secret, requestBody) { var time = new Date().getTime(); var rawSignature = apiKey + ":" + time + ":" + requestBody; var signature = signHMAC(rawSignature, secret); return signature; } function signHMAC(rawSignature, secret) { const signature = CryptoJS.HmacSHA512(rawSignature, secret); const hexSignature = CryptoJS.enc.Hex.stringify(signature); return hexSignature; } After generating the HMAC hash, the following headers need to be included in the REST API Request. Title Description Title Field Description Required Example Value apikey The API Key provided by TNS. Yes ba81c80ad011cd918b946f7e957b1b70cc25f14405d1e7801e892e1561295493 timestamp The time stamp taken at the time of signing. Yes 1715322040 hmac Generated HMAC Hash value. Yes e24e1bfe76b1c846c10c3079ea47202913ad04d66a1434b26470010427dda2d9 User-Agent Identifies the client application making the request. Must include the application name and version (for example, MyPOS/2.1.0 ). This value is not validated but is used for identification and troubleshooting purposes. Yes MyPOS/2.1.0 Important: The User-Agent header is mandatory for all API requests. Requests without a valid User-Agent will be rejected. This header helps TNS identify your integration for support and troubleshooting purposes.
• [Hosted Checkout](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout.md): Hosted Checkout integration involves two parts: server-side integration and client-side integration. In the client-side integration, you specify non-editable <div> elements for payment information in your checkout flow, maintaining your UI's look and feel. Our SDK then replaces these with a secure iframe that captures card data. When our SDK is called from your client, the card data is sent to our servers, transactions are processed and transient tokens are issued.
  • [Mandatory and Optional Content](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/mandatory-and-optional-content.md): Mandatory fields for Create Session Request Schema JSON { "sessionMode": "PERFORM_TRANSACTION", "transactionType": "PAYMENT", "transactionInitiator": "CARDHOLDER", "transactionMode": "ECOMMERCE", "merchantId": "M11000000000148", "order": { "lineItemList": [ { "lineItem": "4409", "lineItemDescription": "Sun Glasses", "quantity": 2, "lineItemCost": "10.00" } ], "metadata": [ { "name": "exampleKey1", "value": "exampleValue1" }, { "name": "exampleKey2", "value": "exampleValue2" } ] "country": "US", "currency": "USD", "subtotal": "20.00" }, "cardBrands": [ { "card": "VISA" }, { "card": "MASTERCARD" }, { "card": "AMEX" }, { "card": "DISCOVER" } ] } Mandatory Fields Note: The User-Agent header is required when calling the session creation endpoint from your server. Title Description Session Mode Specifies the purpose of the session request. Field: sessionMode PERFORM_TRANSACTION : Perform a payment transaction and generate a token for the card number. CREATE_TOKEN : Generate a token for the card number without running a payment transaction. UPDATE_TOKEN : Update the token information. GENERATE_CARDHASH : Allows a UI to be presented for card number and expiry entry, this will generate a one-way cardhash of the details Transaction Type Specifies what transaction to be performed. Field: transactionType PAYMENT : A sale transaction involves both authorization and capture of funds simultaneously, commonly utilized by merchants who provide goods instantly, such as retail stores where customers receive their purchases immediately. PRE_AUTH : An authorization transaction involves verifying the card's validity and ensuring sufficient funds in the cardholder's account without transferring funds. To complete the transfer from the cardholder to the merchant, the approved transaction must be captured. Merchants commonly use authorization transactions when goods are delivered post-purchase. ACCOUNT_VERIFICATION : Zero-value account verification enables merchants to check the status of an account and its validity without impacting their open-to-buy limit. Transaction Mode Specifies the payment channel. Field: transactionMode ECOMMERCE : The Hosted Checkout page is being request for online transaction in the checkout process of the merchant's website or application. MOTO : The Hosted Checkout page is being request to process a Mail-Order-Telephone-Order transaction. The default value is ECOMMERCE. Transaction Initiator Specifies who initiated the transaction. Field: transactionInitiator CARDHOLDER : The cardholder is accessing the checkout page to request the establishment of a session for using Hosted Checkout. MERCHANT : The merchant is requesting this session to process a transaction on behalf of the cardholder. When using Merchant, prior consent need to have been provided by the cardholder with an Stored Credential Agreemement Type according to VISA & Mastercard Scheme rules for the MIT Framework. The default value is CARDHOLDER. Merchant ID TNS provided unique merchant identifier Field: merchantId Merchant Identifier merchantId : This is the provided unique merchant identifier from TNS. This is not to be confused with the Financial Institutions Merchant ID as provided from the Acquirer. Order Information about the order items. At least one item should be provided. Field: order For more information on the order item list, please refer to Hosted Checkout Session Request section. There are optional order configuration to include tax and surcharges. Please refer to below Optional Fields and Configuration section of this page. Card Brand Field: cardBrand This is list of card brands to be displayed in the iframe & surcharge amount or percentage. It is essential to indicate the accepted card brands during the checkout process. Failure to include at least one brand will result in no cards being accepted. Card card : Card brand to be displayed in the checkout page. Optional Fields and Configurations JSON /*Optional Fields*/ { "order": { "cardBrands": [ { "card": "VISA", "surchargeAmount": "0.00" }, { "card": "MASTERCARD", "surchargeAmount": "0.00" }, { "card": "AMEX", "surchargePercentage": "0.00" }, { "card": "DISCOVER", "surchargePercentage": "0.00" }, { "card": "JCB", "surchargePercentage": "0.00" } ], "metadata": [ { "name":"meta1", "value":"value1" }, { "name":"meta2", "value":"value2" } ] }, "tax": "2.00" }, "displayConfig": { "theme": "light", "headerText": "The shades you need", "pageTitle": "Buy Sunglasses", "footerText": "Need receipt for returns", "logoUrl": "https://tnsi.com/wp-content/uploads/2022/09/brand.svg", "logoAltText": "TNS", "showCart":false, "showAmounts":true, "showHeaderBar":”false, "showFooterBar":false, }, "billingAddress": { "firstName": "John", "lastName": "Doe", "addressLine1": "123 Market Street", "city": "San Francisco", "state": "CA", "phone": "4155551234", "email": "john.doe@example.com", "zipCode": "94105", "country":"US" }, "shippingAddress": { "firstName": "John", "lastName": "Doe", "addressLine1": "123 Market Street", "city": "San Francisco", "state": "CA", "phone": "4155551234", "email": "john.doe@example.com", "zipCode": "94105", "country":"US" }, "storedCredentialAgreementType": "UNSCHEDULED", "cardAuthenticationMode": "AVS_OPTIONAL", "createCardHash": true, "hashTypes": [ "TRUNCATED_SALTED_SHA1_DECIMAL", "TRUNCATED_SALTED_SHA1_HEX", "TRUNCATED_SALTED_SHA1_DECIMAL_CREDIT", "SHA1_OF_SHA256" ] } The following table shows the different configuration options to customize the Hosted Checkout Iframe. All the fields are optional. Group Description Card Authentication Mode Card verification used for 3DS2 or AVSField: cardAuthenticationMode Default Value: NONE This field is to specify whether we need to perform card validation using AVS (Address Verification Service) or 3DS2 (3DSecure2). Note: AVS has limited acquirer support, predominantly within the United States. AVS_OPTIONAL : This value displays the address fields in the Hosted Checkout Iframe. The address fields will be optional for user to input. AVS_REQUIRED : This value displays the address fields in the Hosted Checkout Iframe. The address fields will be marked as mandatory. Without user enters the value in the address fields, the iframe will not allow to process the transaction. NONE : No card validation needs to performed. No address fields will be displayed in the iframe. Save Card Whether the card will be saved for future use. Field: allowToSaveCard This field is to specify whether the card will be saved for future usage using tokenization. The cardholder can select previously stored cards. Is is important that the user provides consent to store the card. allowToSaveCard : Hosted Checkout will display a checkbox allowing the user to save their card for future usage. Tokens Field: tokens This allows the merchant to provide a list of Token ID's which are to be displayed to the cardholder when presented with the hosted checkout page. The Token needs to have been provided in a prior transaction and stored within the same token vault for the customer. Up to 5 tokens can be be supplied. tokens : ["456445111111114564",""5432111111116432"] Stored Credential Agreement Type Field: storedCredentialAgreementType When choosing to store a card, concent needs to be obtained form the cardholder, including the reason for storing the card. A separate agreement will be required for each type of agreement. storedCredentialAgreementType : The following options are available: Unscheduled - For the purpose of a variable amount and variable frequency. Recurring - For the purpose of a fixed amount and frequency. A Merchant Initiated Transaction can be performed using the Online REST API. Instalment - For the purpose of splitting a transaction into instalments. Confirm with your TNS Account Manager if Instalments are supported with your acquirer of choice. Meta Data Field: metadata metadata metadata : This allows for transactional Meta Data allows for tagging additional information against a transaction. This can later be used for reporting or smart routing. The format is a name:value pair. A name should be unique and of a length no longer than 50. The value should not exceed a length of 100. A maximum of 50 name/value pairs can be included on a single transaction. key name : The name of the column key/column. value value : the value for the associated name Tax Additional amounts configuration Field: tax Tax tax : The absolute amount of tax computed. The tax is computed on the subtotal of the order. key pageTitle : This is the text to be displayed at the top of the iframe. Logo Image logoUrl : This is the url address of an image to displayed as the logo. The logo will be displayed at the top of the page, near the page title. Card Brand Field: cardBrand Surcharge amount and surcharge percentage are optional fields provided under each card brands. User may provide fixed surchargeAmount or surchargePercentage for specific card brands. Surcharge Amount surchargeAmount : Fixed surcharge amount for each card brand. Surcharge Percentage surchargePercentage : Applicable surcharged percentage for each card brand. Display Configuration Field: displayConfig The following are the fields to configure the appearance of the Hosted Checkout Iframe. Theme theme : Specifies whether to use dark theme or light theme. Allowed values are ‘dark’ and ‘light’. Default value is light. Page Title pageTitle : This is the text to be displayed at the top of the iframe. Logo Image logoUrl : This is the url address of an image to displayed as the logo. The logo will be displayed at the top of the page, near the page title. Logo Text logoAltText : This is the text to be displayed when the user hovers the mouse pointer over the logo image. Header headerText : This is the text to be displayed just below the page title. Header Bar showHeaderBar : Whether a bar is shown between the header text and the payment form within the iFrame. Footer footerText : This is the text to be displayed at the bottom of the iframe. Footer Bar showFooterBar : Whether a bar is shown between the footer text and the payment form within the iframe show amount showAmounts : true/false - Whether the transaciton amount and breakdown is displayed to the cardholder within the hosted checkout form. Use case for not displaying is if the amount is shown to the user outside of the payment form show cart showCart : Whether the items included in the cart are displayed to the user as part of the hosted checkout form Basket Icon showBasketIcon : true/false - Whether a basket icon is displayed when the cart functionality is enabled. Back to cart showbackToCartButton : true/false - Whether a back to cart option is displayed to the cardholder Back to cart label backToCartButtonLabel : The button label to show to the cardholder Save card label allowToSaveCardLabel : The label displayed to the cardholder when they check whether the card will be saved for future transactions Wait for ready state waitForReadyState - When true, the checkout page will not allow payment submission until the merchant signals readiness via callback readyForPay(true). Use this when the merchant page has its own form fields that must be validated before payment can proceed. Enable Pay After Ready - enablePayAfterReady Works with waitForReadyState only. When true, all pay buttons within the checkout iFrame are disabled until readyForPay(true) is called. Local local : This field is required for Apple Pay and Google Pay and is also used to set the language that Hosted Checkout will use for field labels and messaging to the end user. Billing Address Field: billingAddress This billing address will be used for the purposes of 3DS2 Authentication or Address Verification Services (AVS) if enabled. firstName : Customer’s first name. This name must be the same as the name on the card. lastName : Customer’s last name. This name must be the same as the name on the card. addressLine1 : The billing address in which the cardholder is located. addressLine2 : Used for additional address information. addressLine3 : Used for additional address information. city : Locality or city in the billing address state : The state or administrative area code for the country (in ISO 3166-2 format). e.g. CA phone : The email : The email address of the billing contact zipCode : The zip code/post code of the billing contact. country : The country code for the billing address (in ISO 3166-1 alpha-2 code) e.g. US Shipping Address Field: shippingAddress This billing address will be used for the purposes of 3DS2 Authentication or Address Verification Services (AVS) if enabled. firstName : Customer’s first name of the recipeint of the goods. lastName : Customer’s last name of the recipient of the goods addressLine1 : The shipping address of the goods addressLine2 : Used for additional address information. addressLine3 : Used for additional address information. city : Locality or city of the shipping address state : The state or administrative area code for the country (in ISO 3166-2 format). e.g. CA phone : The phone number associated with the shipping address email : The email address of the recipient of the goods zipCode : The zip code/post code associated with the shipping address. country : The country code of the goods (in ISO 3166-1 alpha-2 code) e.g. US Card Hash Field: createCardHash A cardhash (one way hash) of the PAN/Expiry Date to uniquely identify a card createCardHash : true/false Cardhash Types Field: hashTypes Please contact TNS for more information on different card hash types.
  • [Perform Transaction](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/perform-transaction.md): This API request is designed to perform a transaction and have optionally have a token returned which can be used when the cardholder returns to perform a transcation. The session mode is PERFORM_TRANSACTION The token can be used instead of having to have the cardholder re-enter their actual card number each time they return to purchase an item. The value of the token should be specified in the tokens array. This request uses our test credentials running in our demo environment. Use our language box to see sample code in popular programming languages. Run in API Explorer When you use this payload in the API Explorer, the timestamp and HMAC will be automatically assigned by the API Explorer. You will need to provide the secret for this API Key in the API Explorer.
  • [Status](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/status.md): This API request is designed to allow you to check the status/outcome of a transaction. In the event that a customer has closed their browser, of a network issue occured, you can check if the session is completed or not. It would be best practice to set a checkoutSessionTimeout when creating sessions for hosted checkout. If no response is received within the Session Timeout window, then you can query this endpoint to find the outcome.
  • [Create Token](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/create-token.md): This operation allows a Hosted Checkout form to be generated, where the cardholder will enter their cards details, allowing a token to be generated and returned to the merchant. A common use-case is where the token will be used when creating an account on your website/app, but not purchase any goods. Please note that no transaction is being placed during this operation. It's also not guaranteed that the card number entered is a valid card. This request uses our test credentials running in our demo environment. Use our language box to see sample code in popular programming languages. Run in API Explorer When you use this payload in the API Explorer, the timestamp and HMAC will be automatically assigned by the API Explorer. You will need to provide the secret for this API Key in the API Explorer. Following is a sample request to create a token.
  • [Update Token](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/update-token.md): This operation allows a user to update information associated with their token. A tokenId needs to be provided when the mode sessionMode is UPDATE_TOKEN . This request requires test credentials running in our demo environment. Use our language box to see sample code in popular programming languages. Run in API Explorer When you use this payload in the API Explorer, the timestamp and HMAC will be automatically assigned by the API Explorer. You will need to provide the secret for this API Key in the API Explorer. Following is a sample request to update an existing token.
  • [Card Hash](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/card-hash.md): This request uses our test credentials running in our demo environment. Use our language box to see sample code in popular programming languages. Run in API Explorer When you use this payload in the API Explorer, the timestamp and HMAC will be automatically assigned by the API Explorer. You will need to provide the secret for this API Key in the API Explorer. Following is a sample request to generate Card Hash in Hosted Fields.
  • [Parameters and Callbacks](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/parameters-and-callbacks.md): The hosted checkout system uses a post Message-based communication pattern between the iframe (hosted checkout) and the parent window (merchant's website). Here's how the callback system operates: Communication Flow SDK Initialization : The merchant initializes the SDK with callback functions Iframe Creation : SDK creates an iframe pointing to the hosted checkout Event Listening : SDK listens for message events from the iframe Callback Triggering : Hosted checkout triggers callbacks by posting messages to the parent window Callback Execution : SDK receives messages and executes the corresponding callback functions Javascript var hostedCheckoutSdk = new exports.HostedCheckoutSDK(); hostedCheckoutSdk.initialize({ containerId: "hosted-checkout", sessionId: [YOUR SESSION ID], environment: "uat", onApprove: function (response) { console.log(JSON.stringify(response)); //use the response object for subsequent actions }, onError: function (error) { console.log(JSON.stringify(error)); //use the error object for subsequent actions }, onSessionExpired: function (response) { console.log(JSON.stringify(response)); //use the response object for subsequent actions }, onSessionError: function (response) { console.log(JSON.stringify(response)); //use the response object for subsequent actions }, onInvalidData: function (response) { console.log(JSON.stringify(response)); //use the response object for subsequent actions }, onGooglePayAuthorized: function (response) { console.log(JSON.stringify(response)); //use the response object for subsequent actions }, onGooglePayCanceled: function () { //onGooglePayCanceled should not send back any response object. This section should be utilized for subsequent actions }, onGooglePayError: function (error) { console.log(JSON.stringify(error)); //use the error object for subsequent actions }, onPaypalAuthorized: function (response) { console.log(JSON.stringify(response)); //use the response object for subsequent actions }, onPaypalCaptured: function (response) { console.log(JSON.stringify(response)); //use the response object for subsequent actions }, onPaypalCanceled: function () { //onPaypalCanceled should not send back any response object. This section should be utilized for subsequent actions }, onApplePayAuthorized: function (response) { console.log(JSON.stringify(response)); //use the response object for subsequent actions }, onApplePayCanceled: function () { //onApplePayCanceled should not send back any response object. This section should be utilized for subsequent actions }, onApplePayError: function (error) { console.log(JSON.stringify(error)); //use the error object for subsequent actions } }); Parameters for Hosted Checkout SDK Initialization containerId : The id of the in the html page where the iframe to be displayed. sessionId : The sessionId from the response of Create Session request environment : This field is required only when we are doing tests or development. In Production/Live, this field should not be passed. Supported Callbacks: All callbacks Core transaction callbacks onApprove: handlePaymentApproval onSuccess: handlePaymentSuccess onDecline: handlePaymentDecline onCancel: handlePaymentCancel onError: handlePaymentError Session management callbacks onSessionExpired: handleSessionExpired onSessionTimedOut: handleSessionTimeout onSessionError: handleSessionError onServerUnavailable: handleServerUnavailable onInvalidData: handleInvalidData 3D Secure callbacks on3DS2Challenge: handle3DS2Challenge on3DS2Frictionless: handle3DS2Frictionless on3DS2Error: handle3DS2Error Apple Pay callbacks onApplePayAuthorized: handleApplePayAuthorized onApplePayCanceled: handleApplePayCanceled onApplePayError: handleApplePayError onApplePayValidation: handleApplePayValidation Google Pay callbacks onGooglePayAuthorized: handleGooglePayAuthorized onGooglePayCanceled: handleGooglePayCanceled onGooglePayError: handleGooglePayError onGooglePayValidation: handleGooglePayValidation PayPal callbacks onPaypalAuthorized: handlePayPalAuthorized onPaypalCaptured: handlePayPalCaptured onPaypalCanceled: handlePayPalCanceled onPaypalError: handlePayPalError onPaypalValidation: handlePayPalValidation UI/UX callbacks onBackToCart: handleBackToCart onStartInitialization: handleStartInitialization onEndInitialization: handleEndInitialization onPaySubmit: handlePaySubmit Callbacks supported General: onApprove : Callback for Approved card transaction, APM's (excluding ApplePay,GooglePay & PayPal), Token Transactions. onSuccess: Callback for successful operations such as Token Creation, Token Update, Card Hash operations. onDecline : When transactions are declined onCancel : When transaction has been cancelled (e.g. user has cancelled the 3DS2 challenge, or when an APM page has been cancelled) onError : Callback for error scenarios when attempting to process the request Session specific: onSessionExpired : Callback for when session is expired or invalid onSessionTimedOut : Callback to notify the checkout session timed out after configured timeout period. onServerUnavailable : Callback for when server becomes unavailable while precessing the transaction. onSessionError: Callback for when an error occurs within the checkout session itself onServerUnavailable : The payment server is temporarily unavailable. onInvalidData: Invalid or malformed data is submitted. 3DS2 specific: on3DS2Challenge : Handle 3DS2 challenge flow and display challenge interface to user on3DS2Frictionless: Handle frictionless 3DS2 authentication completion. on3DS2Error : An error occurs during 3D Secure 2.0 authentication. ApplePay, GooglePay & PayPal: onApplePayAuthorized : Callback for Approved Apple Pay transaction. onApplePayCanceled : Callback for when the user cancels an Apple Pay transaction. onApplePayError : Callback for error in processing an Apple Pay transaction. onApplePayValidation : Callback for validation response from Apple Pay. onGooglePayAuthorized : Callback for Approved Google Pay transaction. onGooglePayCanceled : Callback for when the user cancels a Google Pay transaction. onGooglePayError : Callback for error in processing a Goole Pay transaction. onGooglePayValidation : Callback for validation response from Google Pay. onPaypalAuthorized : Callback for Approved PayPal transaction. onPaypalCaptured : Callback for when Capture is completed for a PayPal transaction. onPaypalCanceled : Callback for when the user cancels a PayPal transaction. onPaypalError : Callback for error in processing a PayPal transaction. onPaypalValidation : Callback for validation response from PayPal. Hosted Checkout specific: onStartInitialization : Checkout initialization begins. onEndInitialization : Checkout initialization completes. UI/UX Callbacks: onBackToCart: User clicks "Back to Cart" or similar navigation. onPaySubmit: User submits payment and custom validation is required (only if callbackPaySubmit is enabled in session). Special Events Hosted checkout supports special events which allow merchants to have greater flexibility of the user experience. readyForPay(state) Signals to the checkout whether the merchant's page is ready for payment. true = merchant form is valid, payment can proceed. false = merchant form is invalid, payment should be blocked. Requires: waitForReadyState = true in the hosted checkout session configuration. How it works: Initially the ready state is false. As the user fills in merchant-side form fields, the merchant should validate and call readyForPay(true) once all fields are valid. If the user subsequently invalidates a field (e.g. clears a required input), the merchant should call readyForPay(false) to re-block payment. The merchant can call this method multiple times — the checkout respects the latest value. onPayNotReady(response) Triggered when waitForReadyState = true, the ready state is still false, and the user clicks any pay button (credit card or APM) within the checkout. Use case: Inform the user that the merchant-side form is incomplete, or highlight invalid fields. Pay Now: Purpose: Triggers payment processing from the parent window/merchant site for card payments. Triggered from: Merchant calls sdk.payNow() method How it works: When payNow() is called on the SDK, it posts a PAY_NOW message to the iframe. The iframe listens for this message and triggers the payment submission flow. This is useful when the pay button is hidden in the iframe and controlled from the parent page. This is required only if " showPayButon " is false within the hosted checkout session Pay Submit Validated Purpose: Sends validation result back to iframe after onPaySubmit callback How it works: After the onPaySubmit callback completes, the SDK posts this message back to the iframe with the validation result. The iframe then either proceeds with payment (if "SUCCESS") or cancels (for any other value). This is required only when "callbackPaySubmit" is true. Approved Response JSON { "type": "APPROVE", "data": { "authCode": "OK1249", "approvedAmount": "58.53", "accountFirst6": "499977", "accountLast4": "9004", "hostNetwork": "1", "expiryMonth": "12", "expiryYear": "2034", "cardHolderName": "sivam k", "avs": { "avsResult": "Y" }, "clientTransactionId": "88af81f2-6b37-4e6a-8105-46180b713c39", "transactionDateUtc": "2024-07-12T06:13:51.522Z", "tnsResponseCode": "00", "tnsResponseText": "TRANSACTION_APPROVED", "hostResponseCode": "00", "hostResponseText": "APPROVAL", "token": "6485251555209004", "status": "00: APPROVAL", "stan": "458045", "transactionId": "d75f422e-ec8a-44b2-84a2-7b5a94d9a1df", "subtotalAmount": "32", "totalAmount": "58.53", "surchargeAmount": "12.00", "taxAmount": "14.53", "requestId": "742ba5fd-679a-92d0-a275-30c3d79ba4f8", "successful": true } }
  • [Google Pay](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/alternative-payment-methods/google-pay.md): To support the Google Pay payment method in Hosted Checkout, it must be enabled for the merchant in the TNS Merchant Configuration. This can be activated through the Merchant Portal. Additionally, the client-side script must implement the Google Pay callback methods as part of the Hosted Checkout initialization. How It Works The Hosted Checkout will display Google Pay buttons within the iframe. When the customer clicks on the Google Pay button, the Google Pay checkout page appears. The customer chooses a card from his/her Google Wallet for this payment transaction. After the payment is completed at the Google Pay checkout, the onGooglePayAuthorized callback is specified in the hostedCheckoutSdk.initialize method will trigger the transaction response. If the transaction type is PAYMENT , The TNS system immediately captures the authorization. If the transaction type is PRE_AUTH , the TNS system will not capture the payment immediately. Instead, the merchant can capture the transaction later through the Merchant Portal. The callback methods are onGooglePayAuthorized onGooglePayError onGooglePayCanceled onGooglePayAuthorized This callback is invoked on successful Google Pay transaction Plain text { "type": "GOOGLE_PAY_AUTHORIZED", "data": { "authCode": "OK5250", "approvedAmount": "250.00", "accountFirst6": "411111", "accountLast4": "1111", "hostNetwork": "1", "expiryMonth": "12", "expiryYear": "2027", "cardHolderName": "GooglePay", "clientTransactionId": "9f7de94b-8734-45ff-9831-352c92b64a33", "transactionDateUtc": "2025-06-30T11:04:03", "tnsResponseCode": "00", "tnsResponseText": "TRANSACTION_APPROVED", "hostResponseCode": "000", "hostResponseText": "APPROVAL", "token": "4111116558031111", "status": "success", "stan": "327197", "transactionId": "b34c56d5-85fe-4562-ad54-3bbef5c77727", "requestId": "43136627-263d-9f4a-b0cb-5770b885a33f", "responseType": "GooglePay", "successful": true } } onGooglePayError This callback is invoked when the there is an error in process the Google Pay transaction. The error object is passed as a parameter in the callback. Plain text { "type": "GOOGLE_PAY_ERROR", "data": { "approvedAmount": "0.00", "accountFirst6": "411111", "accountLast4": "1111", "hostNetwork": "1", "expiryMonth": "12", "expiryYear": "2026", "cardHolderName": "GooglePay", "clientTransactionId": "0af08b31-abc8-462e-b84c-7b7ad96b6645", "transactionDateUtc": "2024-07-31T15:21:18.644Z", "tnsResponseCode": "AV234", "tnsResponseText": "PRE-AUTHORISATION FAILED", "hostResponseCode": "A1", "hostResponseText": "DBT T.O. RETRY", "status": "failure", "stan": "907293", "transactionId": "4c292eef-6797-4018-be24-ea27bb66e7b2", "requestId": "bfd2a70a-ae82-9f6d-ab04-310b55a3070d", "responseType": "GooglePay", "successful": false } } onGooglePayCanceled This callback is invoked when user cancels the transaction in the Google Pay checkout page. There is no parameters for this callback method. Google Pay Test Cards Enabling Google Pay TEST environment integrations with realistic test card data requires joining the googlepay-test-mode-stub-data Google Group. This grants access to the built-in test card suite when your frontend is configured with environment: 'TEST'. Prerequisites A Google account (either personal or test-specific) logged into your browser. Your integration targets the TEST environment using PaymentsClient or equivalent with: environment: 'TEST' Basic familiarity with your platform's Google Pay setup (Web, Android, iOS, etc.). Step-by-Step Guide Visit the following link and join the group: Group Link Verify Access: With the same Google account, initiate a payment with your app or a Google Pay sample page. In the payment sheet, you should now see test cards (AMEX, VISA, MasterCard, DISCOVER) and U.S.-based billing/shipping addresses. For more details or demo visit: https://developers.google.com/pay/api/web/guides/resources/demos Leaving the Group (Optional): To revert to your live card data for TEST environment, go back to the group page My membership settings Leave group. Once removed, the test suite is disabled and your real cards reappear, though still in the TEST environment. Integration Checklist - Why This Matters The test card suite is critical to complete Google's integration checklist, verifying flows without using real cards. Mock cards are typically limited to PAN_ONLY and U.S.-style addresses. Troubleshooting If no test cards show up: Confirm your app is using environment: 'TEST'. Make sure you're logged in with the correct Google account. Try leaving and rejoining the group or re-logging into the Google Play services/app.
  • [Apple Pay](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/alternative-payment-methods/apple-pay.md): To support the Apple Pay payment method in Hosted Checkout, it must be enabled for the merchant in the TNS Merchant Configuration. This can be activated through the Merchant Portal. Additionally, the client-side script must implement the Apple Pay callback methods as part of the Hosted Checkout initialization. How It Works The Hosted Checkout will display Apple Pay buttons within the iframe. When the customer clicks on the Apple Pay button, the Apple Pay checkout page appears. The customer chooses a card from his/her Apple Wallet to use for this payment transaction. After the payment is completed at the Apple Pay checkout, the onApplePayAuthorized callback is specified in the hostedCheckoutSdk.initialize method will trigger the transaction response. If the transaction type is PAYMENT , The TNS system immediately captures the authorization. If the transaction type is PRE_AUTH , the TNS system will not capture the payment immediately. Instead, the merchant can capture the transaction later through the Merchant Portal. The callback methods are onApplePayAuthorized onApplePayError onApplePayCanceled onApplePayAuthorized This callback is invoked on a successful Apple Pay transaction Plain text { "type": "APPLE_PAY_AUTHORIZED", "data": { "authCode": "OK3099", "approvedAmount": "39.13", "accountFirst6": "481436", "accountLast4": "5999", "hostNetwork": "1", "expiryMonth": "08", "expiryYear": "2030", "cardHolderName": "ApplePay", "clientTransactionId": "5cd4359c-a5eb-4151-a838-19e0fabefde8", "transactionDateUtc": "2024-08-02T16:19:56.173Z", "tnsResponseCode": "00", "tnsResponseText": "TRANSACTION_APPROVED", "hostResponseCode": "00", "hostResponseText": "APPROVAL", "token": "8773771191205999", "status": "success", "stan": "503470", "transactionId": "2e0ad975-54d5-4a41-8234-9beca177f26f", "requestId": "dacd153e-7c71-956a-8f38-ff01ba3810b9", "successful": true } } onApplePayError This callback is invoked when the there is an error in process the Apple Pay transaction. The error object is passed as a parameter in the callback. onApplePayCanceled This callback is invoked when user cancels the transaction in the Apple Pay checkout page. There is no parameters for this callback method.
  • [PayPal](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/alternative-payment-methods/paypal.md): To support the PayPal payment method in Hosted Checkout, it must be enabled for the merchant in the TNS Merchant Configuration. This can be activated through the Merchant Portal. Additionally, the client-side script must implement the PayPal callback methods as part of the Hosted Checkout initialization. How It Works The Hosted Checkout will display PayPal buttons within the iframe. When the customer clicks on the PayPal button, the PayPal checkout page appears. The customer must log into their PayPal account to complete the payment. Once the payment is finalized at the PayPal checkout, depending on the transaction type specified in the session creation request, the appropriate PayPal callbacks will be triggered with the transaction response. In the session creation request, if the transaction type is specified as PAYMENT , the authorized PayPal transaction will be captured. Upon successful capture, the onPaypalCaptured callback, as outlined in the hostedCheckoutSdk.initialize method will be invoked with the PayPal response. If the transaction type is PRE_AUTH , the TNS system will not capture the payment immediately, the onPaypalAuthorized callback specified in the hostedCheckoutSdk.initialize method will trigger with the PayPal response. The merchant can capture the PayPal transaction later through the Merchant Portal. The callback methods are onPaypalAuthorized onPaypalCaptured onPaypalCanceled onPaypalAuthorized This callback is called when the transactions is authorized by PayPal. Plain text { "orderId": "7D6165341G568664S", "merchantId": "M11000000000148", "paypalResponse": { "status": "Payment successful", "orderId": "37B83453PG742964R", "transactionId": "6f4d8d23-32b5-425d-b80f-a90cab02562d", "tnsResponseText": "TRANSACTION_APPROVED", "hostResponseText": "COMPLETED", "receiptData": "5KIDUJ", "requestId": "31aed4a5-8732-9868-9816-6bc89d68684e" } } onPaypalCaptured This callback is called, when the authorized PayPal transaction is captured by TNS system. Plain text { "orderId": "7D6165341G568664S", "merchantId": "M11000000000148", "paypalResponse": { "status": "Payment successful", "orderId": "5T586626AG526770E", "transactionId": "77c5111e-d106-4fb3-81c6-d7e498a27ede", "tnsResponseText": "TRANSACTION_APPROVED", "hostResponseText": "COMPLETED", "receiptData": "YR753W", "requestId": "7c0853a0-5883-9373-8d50-e03def95fefb" } } onPaypalCanceled This callback is invoked when user cancels the transaction in the PayPal checkout page. There is no parameters for this callback method.
  • [Custom CSS](https://developer.pay.tnsi.com/api/ecomm/hosted-checkout/custom-css.md): Through the use of an App-custom.css file, merchants can tailor the look and feel of the hosted checkout to better align with the website which the hosted checkout would be embedded. This includes styling of colors, borders, input fields, buttons, dividers, and section. By offering controlled CSS overrides without exposing sensitive payment logic, Hosted Checkout strikes a balance between security and flexibility—enabling merchants to deliver a branded checkout journey that feels seamlessly integrated with their site while preserving the integrity of the payment flow. Guide All the changes listed below can be implemented in the App-custom.css file. Background Color & Text Color The background-color property sets the background color of the body, and the color property sets the text color for all content on the page. CSS body{background-color: #BED9C4;color: #000;} Outline Border The outer border color of this section can be changed through above CSS. CSS .tnsi-payment-options-div {border: 1px solid #aaa;} Input Fields The background-color property sets the background color of the input fields, the color property sets the text color of the user’s input, and the border-color property sets the border color of the input fields. These styles apply to all input fields in the hosted checkout. CSS .tnsi-input-box { border: 1px solid #A1BDA7 !important; background-color: #DFF0E3 !important; color: #000000 !important; } Input Fields - Placeholder text color The color property sets the placholder color of the user’s input CSS .tnsi-input-box::placeholder{ color: #959595; } Input Fields - on focus This CSS applies when the input is focused—that is, when the user clicks on the input to type, the input’s style changes accordingly. CSS .tnsi-input-box:focus { border-color: #557e5d !important; box-shadow: none !important; background-color: #DFF0E3 !important; } Button Colors - General This color is applied to the text that appears with the horizontal bar. The button’s background color and text color can be customized here to any color desired. CSS .tnsi-button button.pay-button:hover { background-color: #fff; color: #000; } Button Colors - Hover When we hover over the button them from above css background color and color will change CSS .tnsi-button button.pay-button:hover { background-color: #fff; color: #000; } Saved Card Logo This CSS applies to the icon, allowing us to change the image background color and adjust the border radius CSS .tnsi-saved-card-div .tnsi-saved-card-image{ background-color: #fff; border-radius: 24px; } Express Checkout Styling - Text This color is applied to the text that appears with the horizontal bar. CSS .horizontal-ruler-with-text span { color:#000 } Express Checkout Styling - Border The border color can be managed using the CSS defined above. CSS .horizontal-ruler-with-text hr { border-color: #aaa; } Footer - Border This property sets the color of the top border. CSS .footer { border-top: 1px solid #3b3c3c; } Main Title The border of the title section can be customized from this css. CSS .tnsi-page-title { border-bottom: 1px solid #3b3c3c; } Shopping Cart - Background & border This section allows customization of both the background color and the border. CSS .tnsi-shopping-item-list { border: 1px solid #aaa; background-color: #DFF0E3; } Shopping Cart -Divider This section allows you to control the color of all borders. CSS .section-hr { border-top: 1px solid #aaa; }
• [Payment & Token APIs](https://developer.pay.tnsi.com/api/ecomm/online-rest-api.md): The TNS PayOrch platform provides a range of APIs specifically created for handling online card-not-present transactions across multiple channels such as websites, mobile applications, shopping cart checkout pages, and telephone transactions. Through TNS's APIs, users can effectively oversee the complete lifecycle of online transactions and produce detailed reports for customers via our PayOrch Merchant Portal. For a list of supported transaction types, see our Online REST API documentation. Additionally, you have the opportunity to explore each transaction type using our API Explorer.
  • [Account Verification](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/primary-transactions/account-verification.md): Account Verification (sometimes referred to as Zero-Authorization) is a transaction which is best practice to confirm that a payment card is valid and can be used for future transactions without placing a financial charge on the cardholder. Typically performed as a zero-authorization (Account Verification) transaction, it validates key card details such as the card number, expiry date, and security checks with the issuer while verifying that the account is active and available for use. Merchants commonly use Account Verification to: Store card credentials for future use in compliance with card scheme requirements. Register a card on a customer account before future billing, such as subscriptions, delayed charges, or trial periods. Verify card validity and customer intent without requiring an immediate payment, helping reduce fraud and failed future transactions. Because no funds are captured and typically no hold is placed on the cardholder's account, Account Verification provides a secure, low-friction method for confirming card details before subsequent merchant-initiated or customer-initiated transactions occur. All REST API calls are authenticated using HMAC. See Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Authorization](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/primary-transactions/authorization.md): An authorization transaction is conducted to validate a card with the cardholder's issuing bank and confirm the card's validity and available funds. This process does not instantly transfer funds but temporarily reserves the funds in the cardholder's account if sufficient fund is available. To complete the transfer from the cardholder's account to the merchant's account, the authorized transaction must be captured . The captured amount may be equal or lower than the authorized sum. TNS only supports a single Capture transaction for an Authorization. If the merchant wishes to capture an amount higher than the authorized sum, they have the option to conduct an Incremental Authorization transaction using the authorized amount as a base and then proceed to capture the total amount comprising the authorized sum and the incremental value. Authorization transactions are commonly used by merchants in situations where goods are dispatched post-purchase, or where the final amount is unknown when the initial authorization takes place. There is limited availability of Incremental Authorizations depending on the merchants industry, card type and acquirer used. Please contact TNS if you require further information. The provided transaction sample outlines the necessary mandatory fields for approval. For more information on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Sale](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/primary-transactions/sale.md): A sale transaction can be explained as authorization and capture of funds at the same time. The sale transactions are usually used by merchants who deliver the goods almost immediately like retail stores where the customer receives the goods immediately. In ecommerce scenario, the user or the cardholder directly enters the card data during the checkout process. In the payment information section of the request, the card details are provided in the respective fields. The sample transaction here lists the required mandatory fields to get the transaction approved. The provided transaction sample outlines the necessary mandatory fields for approval. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Refund](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/primary-transactions/refund.md): A refund transaction is where the merchant has to return the money to the customer. It allows merchants to reimburse customers for returned merchandise, canceled services, or other situations where a refund is warranted. An unlinked refund, also known as a standalone refund or independent refund or credit transaction, is a type of refund transaction where the refund amount is not directly associated with a specific previous transaction. Instead, it is processed as a separate, standalone refund transaction without any direct reference to a previous purchase. Unlinked refunds are commonly used in situations where the refund amount is not tied to a specific previous transaction or where the merchant prefers to process refunds independently of the original transaction. For example, if a customer requests a refund for a subscription fee or membership dues, the merchant may issue an unlinked refund without referencing a specific purchase transaction. The provided transaction sample outlines the necessary mandatory fields for approval. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Capture](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/secondary-transactions/capture.md): A capture or otherwise known as completion transaction, is to finalize the original authorization transaction. The original authorization transaction identifier and the authorized amount are mandatory to process a capture transaction. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request. To test this sample capture request, start by initiating an authorize transaction. Upon approval of the authorize transaction, retrieve the transactionId & approvedAmount from the response. Use the transactionId as the originalTransactionId and approvedAmount as the originalTransactionAmount before proceeding with the transaction. Use transactionAmount to capture the desired transaction value. Entry mode is optional for capture transactions. The system will utilize the entry mode of the original transaction unless specifically overwritten in the request.
  • [Linked Refund](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/secondary-transactions/linked-refund.md): A refund transaction is where the merchant has to return the money to the customer. It allows merchants to reimburse customers for returned merchandise, canceled services, or other situations where a refund is warranted. In the linked refund original transaction identifier has to be provided. A linked refund can be a partial or full amount of the original transaction. There can be multiple partially linked refunds for a single transaction. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request. To test this sample linked refund request, start by initiating a sale transaction. Upon approval of the sale transaction, retrieve the transactionId & approvedAmount from the response. Use the transactionId as the originalTransactionId and approvedAmount as optionally the originalTransactionAmount before proceeding with the transaction. You can also optionally provide the token for the transaction. Not including the token will fall back to retrieving the payment details from the original transaction. Entry mode is optional for linked-refund transactions. The system will utilize the entry mode of the original transaction unless specifically overwritten in the request.
  • [Reversal](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/secondary-transactions/reversal.md): Reversal, also known as authorization reversal, occurs when an authorization is initially granted but subsequently reversed, either in full or in part, due to factors such as product/service unavailability, fraudulent transactions, or customer change of mind. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request. To test this sample reversal request, start by initiating an authorize transaction. Upon approval of the authorize transaction, retrieve the transactionId & approvedAmount from the response. Use the transactionId as the originalTransactionId and approvedAmount as the originalTransactionAmount before proceeding with the transaction. Entry mode is optional for reversal transactions. The system will utilize the entry mode of the original transaction unless specifically overwritten in the request.
  • [Void](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/secondary-transactions/void.md): Void transactions are conducted on a sale transaction. To reverse a sale transaction before settlement takes place, the merchant must initiate a void transaction, referencing the original sale transaction. The void transaction amount should exactly match the original transaction amount. Partial void is not supported by the system. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request. To test this sample void request, start by initiating a sale transaction. Upon approval of the sale transaction, retrieve the transactionId & approvedAmount from the response. Use the transactionId as the originalTransactionId and approvedAmount as the originalTransactionAmount before proceeding with the transaction. Entry mode is optional for void transactions. The system will utilize the entry mode of the original transaction unless specifically overwritten in the request.
  • [Incremental](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/secondary-transactions/incremental.md): An Incremental transaction adjusts the original authorization amount when there is a change in the total transaction amount. This type of transaction is typically used in scenarios where the final cost of goods or services cannot be accurately predicted at the time of the initial authorization. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request. To test this sample incremental request, start by initiating an authorize transaction. Upon approval of the authorize transaction, retrieve the transactionId & approvedAmount from the response. Use the transactionId as the originalTransactionId and approvedAmount as the originalTransactionAmount before proceeding with the transaction. transactionAmount should be used as the incremented amount. Entry mode is optional for void transactions. The system will utilize the entry mode of the original transaction unless specifically overwritten in the request.
  • [Token-Based Authorization](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/token-transactions/token-based-authorization.md): An authorization transaction is conducted to validate a card with the cardholder's issuing bank and confirm the card's validity and available funds. This process does not instantly transfer funds but temporarily reserves the funds in the cardholder's account if sufficient fund is available. To complete the transfer from the cardholder's account to the merchant's account, the authorized transaction must be captured. The captured amount may be lower than the authorized sum, and merchants can choose to capture portions of the authorized amount on multiple occasions. Also, if the merchant wishes to capture an amount higher than the authorized sum, they have the option to conduct an incremental transaction using the authorized amount as a base and then proceed to capture the total amount comprising the authorized sum and the incremental value. Authorization transactions are commonly employed by merchants in situations where goods are dispatched post-purchase. In token-based authorization, card information is not required. Instead, a token value must be provided, which can be acquired from any previous transactions. The provided transaction sample outlines the necessary mandatory fields for approval. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Token-Based Sale](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/token-transactions/token-based-sale.md): A sale transaction can be explained as authorization and capture of funds at the same time. The sale transactions are usually used by merchants who deliver the goods almost immediately like retail stores where the customer receives the goods immediately. In token-based sale transactions, card information is not required. Instead, a token value must be provided, which can be acquired from any previous transactions. The provided transaction sample outlines the necessary mandatory fields for approval. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Token-Based Merchant Initiated Sale](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/token-transactions/token-based-merchant-initiated-sale.md): This is a Merchant Initiated Transaction, where the merchant has obtained prior agreement to perform transactions on behalf of the customer. In token-based sale transactions, card information is not required. Instead, a token value must be provided, which can be acquired from any previous transactions. The provided transaction sample outlines the necessary mandatory fields for approval. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Token-Based Refund](https://developer.pay.tnsi.com/api/ecomm/online-rest-api/token-transactions/token-based-refund.md): A refund transaction is where the merchant has to return the money to the customer. It allows merchants to reimburse customers for returned merchandise, canceled services, or other situations where a refund is warranted. When perforing a refund when linked to an original transaction, you will need to provide the originalTransaction group with the originalTransactionId as returned from the original transaction where payment was performed. An unlinked refund, also known as a standalone refund, is a type of refund transaction where the refund is not directly associated with a specific previous transaction. Instead, it is processed as a separate, standalone refund transaction without any direct reference to a previous purchase. Unlinked refunds are commonly used in situations where the refund amount is not tied to a specific previous transaction or where the merchant prefers to process refunds independently of the original transaction. For example, if a customer requests a refund for a subscription fee or membership dues, the merchant may issue an unlinked refund without referencing a specific purchase transaction. In token-based refund transactions, card information is not required. Instead, a token value must be provided, which can be acquired from any previous transactions. The provided transaction sample outlines the necessary mandatory fields for approval. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
• [Pay By Link](https://developer.pay.tnsi.com/api/ecomm/pay-by-link.md): Create and send secure, customizable payment links that allow merchants to collect payments from customers via email or SMS. These links direct customers to a hosted payment page where they can complete transactions using their preferred payment methods, with options to tailor messaging, redirect URLs, and link validity for a seamless payment experience. Overview Pay By Link enables merchants to collect payments from customers by sending a secure payment link via email or SMS. The customer clicks the link, which opens a hosted payment page where they can complete the transaction using their preferred payment method. The transaction amount, message displayed to the user and optional redirects can be customized to tailor the customer experience. This eliminates the need for merchants to build and maintain their own checkout pages or process sensitive card data, reducing PCI scope and operational complexity. 1 Merchant creates PayByLink session (via Portal or API) A PayByLink session can be generated either manually via the TNS Merchant Portal, or via an API Integration for those with a software development team. The below is an example of how a Pay By Link - 2 Customer Receives Link via Email, SMS or Both The link will be received near real-time via the delivery method selected. The text included within the email and SMS can be customized. 3 Customer clicks link → TNS Hosted Payment Page opens TNS Hosted Payment Page will be presented with your specific branding and logos. 4 Customer selects payment method and enters details The customer will enter their credit card details to perform payment. Alternatively they can select one of the Alternative Payment Methods that TNS supports. Here is an example where Credit Card & GooglePay have been enabled: 5 3DS2 Secure authentication (if applicable) For Credit Card Transactions, 3DS2 Authentication can be enabled if required. 6 Payment processed The payment will be processed according to the payment method the cardholder selected. 7 Customer will see the result message OR is redirected to merchant URL Once completed, there are two options available depending on your preference. Redirect the user to your webpage. A different landing page should be made available for Approved, Declined or Error Transaction results. The TNS Hosted Payment Page can show a customized message to the customer. For example - Thank you for your payment. Here is a sample of the transaction result page: 8 Merchant receives payment confirmation The merchant can monitor transaction reports which TNS makes available for all merchants. Alternatively, you can have webhook events enabled, this delivers transaction results in near real-time to your backend server. An example of the PayByLink Report can be seen below. You can also Resend the link if it has expired. Key Features Benefit Description No Website Required Accept payments without having to writing code to integrate your website to perform payments Reduced PCI Scope Card data is handled entirely by the hosted payment page Multi-Channel Delivery Send links via email, SMS, or retrieve the URL directly. This can be also be turned into a QR Code Customisable Branding Control over logos, branding, and basic text/colors Flexible Expiry Links can be configured to expire after minutes or days Digital Wallet Support Google Pay, Apple Pay, and PayPal available on the payment page 3DS2 for secure fraud protection Optional built into the form to provide strong customer authentication to combat fraud Optional Card Storage Optional tokenization for future transactions Use Cases Call Centre / Phone Orders Send a payment link during or after a phone call instead of taking card details verbally (MOTO). Reduces fraud risk and PCI compliance burden. Email Invoicing Embed a payment link directly in digital invoices for immediate payment collection. Social Media / Messaging Share links via WhatsApp, Facebook Messenger, or any messaging platform to enable conversational commerce. In-Store Hybrid Accept a deposit in-store, then follow up with a Pay By Link for the remaining balance. Recurring Payment Setup Use the initial Pay By Link transaction to tokenize a card, then process future recurring payments using the stored token. Ad-hoc Charges Quickly generate a link which can be shared to your customers for any purpose your business requires Supported Features Delivery Methods Email Link sent via email to the customer's email address SMS Link sent via SMS to the customer's phone number QR Turn the link into a QR code to accept payments from a users mobile device Digital Wallets ApplePay & GooglePay Ability to enable ApplePay & GooglePay eCommere methonds to the customer PayPal PayPal can be enabled on the page, allowing seamless integration and acceptance Additional APM's TNS has access to hundreds of APM's globally. If there is a specific APM which within your region that you would like to accept, please contact the TNS Sales team. Link Expiry PayByLink sessions can have a specific expiry duration, depending on your business needs. Title Description Unit Description Minute Link expires after specified number of minutes (e.g., 20 minutes) Day Link expires after specified number of days Display & Branding Configuration The payment page appearance is fully customisable: Title Description Element Description Header Text Custom text displayed at the top of the page Logo URL Merchant logo displayed on the payment page Page Title Browser tab/page title Footer Text Custom text in the footer area Pay Button Label Custom label for the payment button Cancel Button Label Custom label for the cancel/back button Result Messages Custom messages displayed to the customer after payment completion. These will only be displayed if you do not support Redirect URL's to your own website. Title Description Scenario Configurable Message (examples) Approved "Transaction is Approved. Contact Merchant for more details" Declined "Transaction is Declined. Contact Merchant for more details" Error "Transaction Error. Contact Merchant for more details" Link Expired "Link Expired. Contact Customer Care" Redirect URLs After payment completion, customers can optionally be redirected to merchant-controlled URLs: Title Purpose approvedUrl Customer redirected here on successful payment declinedUrl Customer redirected here if payment is declined errorUrl Customer redirected here on payment error cancelUrl Customer redirected here if they cancel the payment When a redirect occurs to your website after a user had attempted to pay, additional parameters will be included in the redirect url. The parameters included in the URL redirect include: Parameter Description status The status of the transaction. e.g. approved, declined event The callback event that occured after processing the transaction sessionId The session id for the PayByLink Session transactionId The transactionId returned for the transaction dateTime The date/time in which the transaction was performed referenceId merchantReference passed while creating pay by link session It's important that the parameters included on a redirect url are not used for assessing the approval/decline of the transaction as these are client side and can be manipulated by users. instead you should rely on the Webhook Notification directly to your server, status check call, or reports from our merchant portal Note: URLs can be configured by TNS as part of your setup which will take precedance over those supplied in your PayByLink Session Metadata Merchants can optionally attach custom key-value metadata to each payment link for reconciliation and tracking purposes. This information can then be enabled in the Merchant Portal for reporting purposes. One or more custom key-value pairs can be associated with a transaction. JSON "metadata": [ { "name": "Order", "value": "product" } ] API Specification API Endpoint Description https://checkoutvirg.uat.paymentgateway.tnsi.com/hostedcheckout/session/create/paybylink UAT Pre-production https://checkout.ap.paymentgateway.tnsi.com/hostedcheckout/session/create/paybylink LIVE - Production Asia Pacific https://checkout.eu.paymentgateway.tnsi.com/hostedcheckout/session/create/paybylink LIVE - Production Europe https://checkout.us.paymentgateway.tnsi.com/hostedcheckout/session/create/paybylink LIVE - Production North America
• [Recurring Payments](https://developer.pay.tnsi.com/api/ecomm/recurring-payments.md): The TNS Recurring Payments API empowers businesses to seamlessly manage subscription-based and repeat billing models with secure, automated transactions. Designed for scalability and compliance, this API enables merchants to store customer payment credentials securely using tokenization, and initiate recurring charges without requiring repeated customer input. By integrating with the Recurring Payments API, businesses can streamline their payment workflows, reduce friction in the customer experience, and ensure consistent revenue collection—all while maintaining PCI DSS compliance and leveraging robust authentication protocols.
  • [Credit Card Recurring Payment](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/credit-card-recurring-payment.md): This request creates a Recurring Payment Schedule using a credit card. The given payment method must be specified as CREDITCARD. The credit card number will be tokenized and a recurring schedule will be created. All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Token Recurring Payment](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/token-recurring-payment.md): This request is to create a Recurring Payment Schedule using a token instead of real card data. The given payment method must be specified as CREDITCARD. All REST API calls are authenticated using HMAC. Please refer to the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Update Recurring Payment](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/update-recurring-payment.md): This request updated a Recurring Payment schedule. Please see the following sample request for all the possible fields that can be updated. All REST API calls are authenticated using HMAC. Please refer to the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Update Recurring Payment](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/update-recurring-payments.md): This request updated a Recurring Payment schedule. Please see the following sample request for all the possible fields that can be updated. All REST API calls are authenticated using HMAC. Please refer to the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Search Recurring Payment](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/search-recurring-payment.md): Recurring payment search allows users to identify existing recurring payment plans based on various criteria. For more information regarding the available search filters, please refer to the API documentation section below. All REST API calls are authenticated using HMAC. Please refer to the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Get Recurring Payment](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/get-recurring-payment.md): This request is to retrieve an existing Recurring Payment schedule from our system. All REST API calls are authenticated using HMAC. Please refer to the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Create Daily Recurring Payment](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/create-daily-recurring-payment.md): This request sets up a Daily Recurring Payment Schedule using a credit card. The payment method must be designated as CREDITCARD. The provided credit card number will be tokenized, and a Recurring Payment Schedule will be created based on this tokenization. This example request establishes a Daily Recurring Payment Schedule to charge the specified card every day, starting from 15th June 2024 and continuing until 15th September 2024. All REST API calls are authenticated using HMAC. Please refer to the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Create Weekly Recurring Payment](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/create-weekly-recurring-payment.md): This request sets up a Weekly Recurring Payment Schedule using a credit card. The payment method must be designated as CREDITCARD. The provided credit card number will be tokenized, and a Recurring Payment Schedule will be created based on this tokenization. This example request sets up a Weekly Recurring Payment Schedule to charge the specified card every Monday, starting from 17th June 2024 and continuing until 12th December 2024. All REST API calls are authenticated using HMAC. Please refer to the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Create Monthly Recurring Payment](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/create-monthly-recurring-payment.md): This request sets up a Monthly Recurring Payment Schedule using a credit card. The payment method must be specified as CREDITCARD. The provided credit card number is tokenized, and a Recurring Payment Schedule is established. This example request schedules a recurring charge on the 5th of each month, starting from 15th June 2024 and continuing until 15th June 2025. All REST API calls are authenticated using HMAC. Please refer to the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Create Yearly Recurring Payment](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/create-yearly-recurring-payment.md): This request creates a Yearly Recurring Payment Schedule using a credit card. The payment method must be specified as CREDITCARD. The provided credit card number is tokenized, and a Recurring Payment Schedule is established based on this token. This example request sets up a Recurring Payment Schedule to charge the specified card annually on the 1st of July, starting from the 23rd of May 2024. The payment will recur five times, concluding effectively on the 1st of July 2028. In this request, instead of specifying an ending date, we have indicated the number of times the payment should recur using the field frequency . All REST API calls are authenticated using HMAC. Please refer to the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Request Format](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/request-format.md): Field Name Type Required(R), Optional(O), Conditional(C) Description merchantId string O This the unique identifier of the merchant in our system. startDate string R This is the effective start date of the Recurring Payment Schedule in UTC, formatted as YYYY-MM-DD. endDate string O This is the effective date on which this Recurring Payment Schedule becomes invalid. This value is in UTC, formatted as YYYY-MM-DD. frequencyType Enum values: DAILY Charge the card Daily. WEEKLY Charge the card every week on the given day of the week. MONTHLY Charge the card every month on the given day of the month. YEARLY Charge the card annually on the given month and day of the year. string R This indicates frequency of the schedule for this Recurring Payment Schedule. frequency number R This indicates the frequency of the Recurring Payment Schedule. For example, if the value is 2 and the frequency type is 'Weekly', then the card will be charged every 2 weeks. dateOfMonth number C This indicates the specific day of the month when the card will be charged. This field is mandatory when frequesncy type selected as YEARLY or MONTHLY . monthOfYear Enum values: JANUARY FEBRUARY MARCH APRIL MAY JUNE JULY AUGUST SEPTEMBER OCTOBER NOVEMBER DECEMBER string C This specifies the month of the year to charge the card, applicable when the frequency type is 'YEARLY'. This field is mandatory when frequesncy type selected as YEARLY . dayOfWeek Enum values: SUNDAY MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY string C This specifies the day of the week on which to charge the card, applicable when the frequency type is 'WEEKLY'. This field is mandatory when frequesncy type selected as WEEKLY . weekDays boolean C This indicates the system to perform this Recurring Payment Schedule only on the week days. Applicable when the frequencyType is 'DAILY'. This field is mandatory when frequesncy type selected as DAILY timezone string O Based on the timezone, the execution time of the recurring payment is calculated. The value of this field aligns with the geographic area's standard time and daylight saving adjustments. It is formatted as "Country/Region" and defaults to the merchant's timezone. paymentMethod Enum values: CREDITCARD TOKEN string R The type of tender used for the transaction. currencyCode string R This is the ISO 4217 currency code. Use "036" for Australian dollar, "840" for United States dollar, "826" for Pound sterling. Please refer https://en.wikipedia.org/wiki/ISO_4217 for list of all currency codes. paymentDetails - List of payment options for this Recurring Payment schedule. cardNumber string C 14 to 19 digits credit card number to be charged for this recurring payment. This field is applicable when the payment method is selected as Credit Card. This is mandatory field when payment method is selected as CREDITCARD . expiry string C Expiry date as it appears on the credit card and formatted as string in MMYY format. cardHolderName string C The cardholder name as printed on the credit card. transactionAmount string R This is the total amount of the transaction in the designated currency and transmitted as a string. The amount should be in decimal format, such as “10.12” for a transaction totaling $10.12. transactionReference string R The identifier for the transaction in your system formatted as a string. token string C The token value of the credit card. This is a required field when payment methos is selected as TOKEN .
  • [Response Format](https://developer.pay.tnsi.com/api/ecomm/recurring-payments/response-format.md): Field Type Description recurringScheduleId string (UUID) Unique identifier assigned to the recurring payment schedule. transactionReference string Reference to the transaction that initiated the recurring schedule. token string Tokenized representation of the card used for recurring payments. createdDate string (dateTime) ISO 8601 timestamp when the recurring schedule was created. updatedDate string (dateTime) ISO 8601 timestamp of the most recent update to the recurring schedule.
• [BYO Android App](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide.md): Welcome to the official documentation for TNSPay BYOA (Bring Your Own App) —your guide to integrating secure, flexible, and feature-rich payment capabilities into card terminal applications . This guide is designed for developers building directly on card terminal devices, enabling them to leverage the TNSPay SDK to deliver seamless payment experiences, device control, and communication with Payment Orchestration. What You Can Do with TNSPay BYOA Initiate Transactions : Sale, Pre-auth, Capture, Reversal, Void Handle Card Inputs : Chip, Tap, Swipe, Manual Entry Support Multiple Payment Types : Credit, Debit, EBT Cash, Gift Cards Customise Terminal Behaviour : Tipping, surcharges, receipt printing, fallback logic Ensure Compliance : PCI-DSS, EMV, and Payment Orchestration-specific standards What's Included SDK Libraries ( .aar , .jar , .framework ) Sample Integration Code API Reference Developer Guides Error Code Glossary Release Notes
  • [Getting Started](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/getting-started.md): This guide helps developers integrate applications via the TNSPay BYOA API. To help you build an in-person payments integration with TNS, we provide: An Integration checklist to build a test integration. A Go Live Checklist
  • [TNSPay BYOA Integration Checklist](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-integration-checklist.md): 1 Sign up with TNS Register with TNS by reaching out to your TNS Account Manager 2 Request a Test Terminal Request a Test Terminal Kit from TNS via your account manager. The kit will contain Registered Terminal of your choice in test mode TNSPay Android Pay App SDK software Test Sample Application 3 Prepare Terminals Steps to configure the terminal prior to first use Inspect the terminal, to verify it has not been tampered with. Insert the receipt paper roll. Turn on the terminal. Connect the terminal to your network. Configure the terminal. Test the connection with TNS Payment Orchestration 4 Build your Integration Now it is time to thoroughly test all aspects of your integration, from making a payment to reconciliation. Make various types of test transactions. Make payments: Test the happy flow by making payments with your test terminals and test card. Test non-happy flows such as time-outs and connection problems. Simulate various acquirer responses to test your handling of declined transactions. Test different card types and Cardholder Verification Methods (CVM). Test the payment methods and features that you added to your integration. To Handle errors, refer to the Error Handling section
  • [Supported Terminals](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/supported-terminals.md): The following terminals are supported by the TNS Terminal API A920 pro Aries 8 A80 IM25 Note: The specifications of these terminals will be supplied together with the terminal and are also available online The application should support the screen resolution of the supported terminals' display resolution
  • [TNSPay BYOA API Overview](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/tnspay-byoa-api-overview.md): The Terminal API supports the following payment transaction messages Sale (Purchase) A purchase transaction is a single-step process where the card is authorized and the funds are captured immediately in the same flow. This means the merchant gets paid without any additional steps. It’s typically used in retail or e-commerce scenarios where the final amount is known at the time of sale. Pre-Authorization Pre-authorisation is the first step in a two-step transaction process used when the final amount is not yet confirmed. In this step, the merchant requests an authorisation for an estimated amount, and the issuer places a temporary hold on the cardholder’s funds. No money is transferred at this stage; it simply ensures that the funds are available and reduces the risk of non-payment. This method is commonly used in industries like hospitality, car rentals, and fuel stations where the final bill may vary. Capture / Completion Completion, also referred to as the capture of completion, is the second step after a successful pre-authorisation. Once the actual amount is confirmed, the merchant sends a capture request to convert the pre-authorised hold into a settled transaction. This process moves the funds from the cardholder’s account to the merchant’s account. If the capture of completion is not performed within the allowed timeframe (usually a few days), the hold expires, and the merchant will not receive payment. Void A Void occurs when a previously authorised transaction—whether a purchase or a pre-authorisation—is cancelled before settlement. In this process, the merchant sends a Void request to the acquirer, which informs the issuer to release the hold on the cardholder’s funds. No money is moved because the transaction never reaches the capture stage. Void are typically used when the merchant decides not to proceed with the transaction (e.g., order cancellation or service not rendered). This ensures the cardholder’s available credit or funds are restored promptly. Reversal A refund transaction is initiated when a customer requests reimbursement for a previously completed payment at the point of sale. This transaction type ensures that the original charge is reversed in a secure and traceable manner. Upon initiating the refund, the terminal communicates with the Payment Orchestration layer, which coordinates the necessary steps across payment processors and financial institutions to return the funds to the customer’s account. The orchestration system processes the request, updates the transaction record, and ensures the funds are released appropriately. Incremental Auth Incremental Authorization allows the authorized amount on an existing Pre-Auth to be increased so that it matches a higher final amount at completion. When a transaction completes for a value greater than the original Pre-Auth, an additional Authorization is used to raise the held amount up to the completion value — equalizing the authorized and completion amounts before the transaction is captured. This ensures the funds held against the card fully cover the final amount being charged.
  • [SDK Overview](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview.md): The TNSPay BYOA (Bring Your Own App) SDK empowers developers to build custom applications directly on card terminal devices, enabling secure, compliant, and feature-rich payment experiences. Designed for flexibility and speed, the SDK provides all the tools needed to integrate with payment gateways, manage transaction flows, and control terminal behaviour. SDK Components Explained PaymentSDK Class This is the main class that third-party developers will use. It handles: Binding to the payment service Sending Payment Requests Releasing the service when done RequestMsg A data class that encapsulates all the information needed for a transaction: msgType Type of transaction amount Transaction amount currency Currency code invoiceNbr origTransNo Additional fields for tracking PaymentResponseService A singleton object that provides three callback hooks: responseCallback Final result of the transaction in Json format messageCallback Intermediate messages (e.g. “Insert Card”) stateCallback State changes (e.g. “Processing”, “Completed”) Security Model The payment app uses a whitelist mechanism to ensure only trusted apps can bind to it. When a client app tries to connect: The payment app checks the calling package name. If it’s not in the whitelist ( com.tnsi.clientapp , com.tnsi.thirdpartyapp ), it throws a SecurityException . This ensures that only authorized apps can initiate payments. Why Use the SDK Instead of AIDL Directly? Simplifies development : No need to manage ServiceConnection , IBinder , or AIDL interfaces manually. Error handling : Built-in error callbacks. Cleaner code : Developers can focus on business logic, not IPC. Based on the sample code and documentation provided, here's a comprehensive integration guide for third-party developers to use the com.tnsi.sdk.PaymentSdk in their Android applications:
    • [SDK Integration Guide](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide.md): This guide provides third-party developers with the necessary steps and code examples to integrate the PaymentSdk into their Android applications for handling payment operations. The PaymentSdk enables Android apps to perform payment operations such as: Sale (Purchase) Pre-Authorization Completion Void Reversal It communicates with a payment application via AIDL and provides callbacks for responses, messages, and state changes. Which is also why there are no endpoints needed for the API call
      • [IDE Setup](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/ide-setup.md): Prerequisites Android Studio 4.2+ Kotlin 1.5.30+ Android SDK 30+ Payment SDK AAR/JAR and AIDL files from vendor Setup Andoid Studio The development of the app requires understanding the use of Android Studio. For more information on Android studio, please follow this link . Create New Project: Create a new project in the IDE by Open the file menu Click on New Create a new project For detailed instructions, please follow the link . Add SDK Dependencies: Include the TNS-Payment-SDK-vX.X.X.X.aar file in your project When you add an .aar file to your IDE: Library Integration : It imports a complete Android library module, including compiled code ( .class files), resources (layouts, drawables, strings), and manifest entries. SDK Functionality : It enables your client app to access the SDK’s APIs, UI components, and background services—essential for interacting with card terminals. Build Configuration : The IDE updates the project’s build.gradle to include the .aar as a dependency, ensuring it’s packaged correctly during compilation. Code Completion & Debugging : You get access to auto-complete, documentation, and debugging support for the SDK’s exposed methods and classes. Encapsulation : It keeps the SDK modular and version-controlled, allowing easy updates without exposing internal implementation details.
      • [Initializing the SDK](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/initializing-the-sdk.md): Initializing the SDK Declare and initialize the SDK in your Activity or Fragment: What Initialising an SDK Does 1 Loads Core Components It sets up the SDK’s internal modules, such as communication protocols, transaction handlers, and device interfaces, so they’re ready for use. 2 Establishes Configuration It applies configuration parameters like merchant credentials, environment settings (e.g. test vs production), terminal capabilities, and feature flags (e.g. tipping, cashback). 3 Registers Context The SDK links itself to the app’s context (e.g. Android Context or iOS UIApplication ) to access system resources, lifecycle events, and UI elements. 4 Prepares Communication Channels It opens secure channels for interacting with payment gateways, card readers, or external APIs—essential for real-time transaction processing. 5 Validates Dependencies It checks for required permissions, hardware availability (e.g. NFC, Bluetooth), and compatibility with the host app and OS version. 6 Enables Logging and Error Handling It activates diagnostic tools for debugging, logging, and capturing runtime errors or transaction failures. In short, SDK initialisation is the first step in enabling your client app to securely and reliably interact with card terminals and payment services
      • [Best Practices](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/best-practices.md): Please follow the Android Studio guidelines for writing code, this can be found using this link . Error Handling: Plain text val parsedAmount = parseAmount(street) ?: run { Toast.makeText(this, "Invalid amount", Toast.LENGTH_SHORT).show() return } val parsedAmount = parseAmount(street) ?: run { Toast.makeText(this, "Invalid amount", Toast.LENGTH_SHORT).show() return } Logging Plain text Log.d("SDK", "Sending transaction: $request") Log.d("SDK", "Sending transaction: $request") Threading Always update UI with runOnUiThread { } Project Structure Example Plain text app/ ├── build.gradle.kts ├── src/ │ └── main/ │ ├── java/ // Kotlin source code │ ├── res/ // JSON/xml resources │ └── aidl/ // AIDL interface files from SDK ├── libs/ │ └── tnsi-sdk.aar // Payment SDK binary app/ ├── build.gradle.kts ├── src/ │ └── main/ │ ├── java/ // Kotlin source code │ ├── res/ // JSON/xml resources │ └── aidl/ // AIDL interface files from SDK ├── libs/ │ └── tnsi-sdk.aar // Payment SDK binary Key Notes Validation : Ensure amount , currency , and readerType match business rules before sending the request. Error Handling : The SDK should provide exceptions or status codes for invalid input (e.g., missing msgType ). Security : Sensitive data (e.g., agreementID , jsonMsg ) should be encrypted if transmitted outside the app. Logging : Debug logs can track invoiceNbr and origTransNo for auditing. Validation : Always validate parsing results ( ?.takeIf { it > 0 } ). Default Values : invoiceNbr and currency are hardcoded ( USD ). Tokenization : If tokenRequest is checked, agreementID and agreementType are included. Disclaimers / Consent The app/merchant should allow for the display of disclaimers/collect consent whenever applicable. eg. during Tokenization. If requesting a token for a cardholder, you need to ensure the merchant collects consent from the customer to allow the merchant to store the card token information and to perform future transactions .
      • [Key Classes](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/key-classes.md): MsgType This class defines constants for payment message types , specifying the action to be performed: Valiue Description SALE Standard purchase transaction. PRE_AUTH Authorization for a future transaction. SALE_COMP Completion of a pre-authorized payment. VOID Cancel an unprocessed transaction. REFUND Refund a processed transaction. CANCEL_CARD Cancel the current card read operation. ReaderType This class defines constants for card reader types , specifying how the card is processed: Value Description SWIPE Magnetic stripe card swipe. INSERT Chip card inserted. CLESS Contactless payment (e.g., NFC). SWIPE_INSERT Support for both swipe and insert methods. CLESS_SWIPE Support for contactless and swipe. INSERT_CLESS Support for chip and contactless. INSERT_CLESS_SWIPE Support for chip, contactless, and swipe. RequestMsg The RequestMsg class is a Parcelable data container for all payment-related parameters. It is annotated with @Parcelize to support Android-specific serialization (required for AIDL/IPC). Plain text private const val CURRENCY = "USD" private const val DEFAULT_INVOICE_NUMBER = "10120304" private const val DEFAULT_TXN_AMOUNT = "15.00" private const val DEFAULT_STAN_NUMBER = "1" private const val DEFAULT_AGREEMENT_ID = "MERCH123_20250804_001" private const val DEFAULT_AGREEMENT_TYPE = "I" private const val CURRENCY = "USD" private const val DEFAULT_INVOICE_NUMBER = "10120304" private const val DEFAULT_TXN_AMOUNT = "15.00" private const val DEFAULT_STAN_NUMBER = "1" private const val DEFAULT_AGREEMENT_ID = "MERCH123_20250804_001" private const val DEFAULT_AGREEMENT_TYPE = "I"
      • [Integration with AIDL](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/integration-with-aidl.md): The RequestMsg class is designed to be passed between Android components (e.g., Activity and AIDL service). Steps to Use: Construct a RequestMsg object with the desired parameters. Pass it to a service (e.g., using AIDL or a Messenger ), which processes it via a payment SDK or terminal. Handle the response (not shown in the provided code). AIDL Interface Example :
      • [Common Steps for All Requests](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/common-steps-for-all-requests.md): Parse UI Input: Use parseAmount() and parseStan() to validate and convert inputs. Build RequestMsg : Set msgType based on the transaction type. Include mandatory fields: invoiceNbr , amount , currency , readerType . Send to SDK: Plain text sdk.sendRequestMessage(requestMsg) sdk.sendRequestMessage(requestMsg)
      • [Payment Requests](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests.md): Making Payment Requests Each payment operation uses a RequestMsg object. Below are examples for each type: An API for making payment requests is a set of programmable interfaces that allows a client application—such as a mobile app, ePOS system, or card terminal—to initiate and manage payment transactions with Payment Orchestration. Here's what it typically does: What the SDK Does 1 Initiates Transaction Instance It sends a structured request to Payment Orchestration to begin a transaction. This includes details like amount, currency and merchant ID 2 Handles Card Data It securely transmits card information (PAN, expiry, CVV) or tokenised data, often using encryption or PCI-compliant methods. 3 Supports Multiple Payment Types It can handle various transaction types such as Sale/Purchase, Pre-Auth, Capture, Reversal, Void 4 Manages Authentication It may trigger PIN entry, Signature flows depending on the card type and transaction context. 5 Processes Responses It receives and interprets the Payment Orchestration's response—approved, declined, or error—and passes it back to the client app for UI updates or receipt generation. 6 Logs and Audits It often includes logging mechanisms for transaction tracking, reconciliation, and compliance reporting. 7 Supports Fallbacks and Retries In case of failure, the API may support retry logic or “fall forward” mechanisms to alternate payment methods or gateways. Sequence
        • [Sale/Purchase](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/sale-purchase.md): An API for Sale/Purchase transactions in a card payment system enables a client application—such as a card terminal —to initiate and process a standard payment transaction where a customer pays for goods or services. Here's what it typically does: Key Parameters: MsgType.SALE : Indicates a sale. tokenReq : If true , requires tokenization (agreement fields are used). agreementID / agreementType : Required for tokenized transactions. What a Sale/Purchase Transaction API Does 1 Initiates a Payment Request It sends a structured request to Payment Orchestration, including: Transaction amount Currency Merchant ID Card details or token Transaction type (e.g. SALE, PURCHASE) 2 Handles Card Data Securely It transmits card information (e.g. PAN, expiry, CVV) or tokenised data using secure protocols (e.g. TLS, PCI-DSS compliant encryption). 3 Triggers Authentication Depending on the card type and configuration, it may prompt for: PIN entry Signature 4 Processes Authorisation The API communicates with Payment Orchestration to: Validate the card Check available funds Authorise the transaction 5 Returns a Response It provides a response to the client app, including: Approval or decline status Authorisation code Transaction ID Error codes (if any) 6 Supports Receipt Generation The response can be used to generate a customer receipt with transaction details. 7 Logs and Reconciliation The transaction is logged for reporting, settlement, and reconciliation purposes. Disclaimers / Consent The app/merchant should allow for the display of disclaimers/collect consent whenever applicable. eg. during Tokenization. If requesting a token for a cardholder, you need to ensure the merchant collects consent from the customer to allow the merchant to store the card token information and to perform future transactions
        • [Pre-Auth](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/pre-auth.md): A Pre-Authorisation (Pre-auth) Transaction API is used to reserve funds on a customer’s card before the final transaction is completed. This is common in industries like hospitality, fuel, and e-commerce where the final amount may not be known upfront. Here's what it does: Key Parameters: MsgType.PRE_AUTH : Indicates a pre-authorization. What a Pre-auth Transaction API Does 1 Initiates a Hold on Funds It sends a request to the payment gateway to temporarily reserve a specified amount on the customer’s card without actually capturing it. This ensures the customer has sufficient funds. 2 Captures Card Details Securely It transmits card data (or tokenised equivalent) using secure protocols, often requiring PIN or authentication depending on the card type. 3 Returns Authorisation Code If approved, the gateway responds with an authorisation code and a transaction ID, which are used later to complete or void the transaction. 4 Delays Settlement Unlike a sale transaction, the funds are not transferred immediately. The merchant must send a completion (capture) request to finalise the transaction. 5 Handles Reversal If the transaction is not completed within a set time, the API reverses the transaction 6 Improves Risk Management It reduces the risk of declined payments at the time of final billing and helps merchants manage cash flow and inventory more effectively. Disclaimers / Consent The app/merchant should allow for the display of disclaimers/collect consent whenever applicable. eg. during Tokenization. If requesting a token for a cardholder, you need to ensure the merchant collects consent from the customer to allow the merchant to store the card token information and to perform future transactions
        • [Capture/Completion](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/capture-completion.md): A Capture/Completion API is used to finalise a payment transaction that was previously authorised using a Pre-auth API. It’s a critical part of the payment flow in industries where the final transaction amount may change after the initial authorisation—such as hospitality, fuel, or services. Key Parameters: MsgType.SALE_COMP : Indicates a completion. origTransNo : STAN of the original PRE_AUTH transaction. tokenReq : Enables agreement fields if true . The System Trace Audit Number or STAN number is the primary method to link the message to the original/parent transaction. In addition to this, invoice number may also be used What a Capture/Completion API Does 1 Finalises the Transaction It confirms the transaction and instructs the payment gateway to transfer the reserved funds from the customer’s account to the merchant. 2 References the Pre-auth The API uses the authorisation code and transaction ID from the original pre-auth request to link the two operations. 3 Specifies Final Amount It may include the same or adjusted amount (e.g. adding minibar charges to a hotel bill), depending on business rules and gateway support. 4 Updates Receipts and Logs The system generates a final receipt and updates transaction logs for reconciliation and reporting. 5 Handles Errors and Expiry If the pre-auth has expired or is invalid, the API will return an error, prompting the merchant to re-authorise or retry the transaction.
        • [Void](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/void.md): it occurs when a previously authorised transaction—whether a purchase or a pre-authorisation—is cancelled before settlement. In this process, the merchant sends a Void request to the acquirer, which informs the issuer to release the hold on the cardholder’s funds. Key Parameters: MsgType.VOID : Indicates a void. origTransNo : STAN of the transaction to void. The System Trace Audit Number or STAN number is the primary method to link the message to the original/parent transaction. In addition to this, invoice number may also be used What a Void Transaction API Does 1 Cancels a Transaction Before Settlement It reverses a transaction that was authorised but not yet settled, ensuring that the customer’s funds are not captured. 2 References the Original Transaction The API uses identifiers such as the transaction ID, authorisation code, and timestamp to locate and reverse the original transaction. 3 Prevents Double Charges It ensures that if a transaction was initiated in error (e.g. wrong amount, duplicate entry), the customer is not charged twice. 4 Updates Gateway and Issuer The reversal request is sent to the payment gateway and card issuer, updating their records to reflect the cancellation. 5 Triggers Receipt and Logs A reversal receipt is generated, and the transaction logs are updated for audit and reconciliation purposes. 6 Improves Customer Experience It allows merchants to quickly correct mistakes without requiring a separate refund process, which can take longer.
        • [Refund](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/reversal.md): The Refund API allows a terminal to initiate a transaction that returns funds to a customer for a previous payment. It securely processes the refund through the Payment Orchestration layer, ensuring accurate transaction updates and return of funds. Key Parameters: MsgType. REFUND : Indicates a refund. amount : Amount value to refund. What a Refund Transaction API Does 1 Initiates Refund After Authorization Begins the refund for a transaction that was authorized but not yet settled, ensuring the customer’s funds are not captured. 2 Identifies the Original Transaction Uses key identifiers like transaction ID, authorization code, and timestamp to locate and reverse the original payment. 3 Communicates with Payment Orchestration Sends the refund request to the Payment Orchestration layer, which updates records across processors and issuers. 4 Generates Receipt and Audit Logs Produces a refund receipt and updates transaction logs for reconciliation and compliance tracking. 5 Streamlines Merchant Operations Enables quick correction of payment errors without requiring a separate refund workflow, improving customer satisfaction.
        • [Incremental Authorization](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/incremental-authorization.md): Incremental Authorization allows the authorized amount on an existing Pre-Auth to be increased so that it matches a higher final amount at completion. When a transaction completes for a value greater than the original Pre-Auth, an additional Authorization is used to raise the held amount up to the completion value — equalizing the authorized and completion amounts before the transaction is captured. This ensures the funds held against the card fully cover the final amount being charged. This differs from Stepped Incremental Authorization, where multiple incremental messages are generated to build the authorization up in stages as usage progresses (for example, fuel dispensing). Normal Incremental Authorization uses just one increment to reconcile the authorized and completion values. What this means for your BYOA app Incremental Authorization is handled entirely within the TNS payment layer (PayOrch ). No changes are required in your application to support it — you do not need to add new message types, modify your Pre-Auth or Completion calls, or update your integration. Your app continues to send standard Pre-Auth and Capture/Completion requests through the API exactly as documented, and the incremental authorization is managed for you behind the scenes. How to enable it If you'd like Incremental Authorization enabled for your terminals, simply r each out to your TNS Account Manager. They'll arrange to have the capability switched on for your account — no development or integration work is needed on your side.
        • [Set Card Reader Mode](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/set-card-reader-mode.md): Overview The SDK exposes a ReaderType class that constrains how a card can be presented during a transaction—magnetic stripe (swipe), EMV chip (insert), and/or contactless (tap). Choose one value per request to match your business rules and the terminal’s capabilities. Meaning of Each Option Constant Allows SWIPE Only magnetic stripe cards NSERT Only chip (EMV) cards SWIPE_INSERT Either swipe or insert CLESS Contactless (tap) only CLESS_SWIPE Contactless or swipe INSERT_CLESS Insert or contactless INSERT_CLESS_SWIPE All card input methods (recommended) Setting ReaderType in a Transaction Request Assign the desired readerType when constructing a RequestMsg for a sale, refund, or token operation. Select exactly one constant per transaction. Plain text val requestMsg = RequestMsg( msgType = MsgType.SALE, invoiceNbr = DEFAULT_INVOICE_NUMBER, amount = parsedAmount, currency = DEFAULT_CURRENCY, readerType = ReaderType.INSERT, // Choose allowed card input method here tokenReq = tokenRequest, agreementID = agreementID, agreementType = agreementType, ) val requestMsg = RequestMsg( msgType = MsgType.SALE, invoiceNbr = DEFAULT_INVOICE_NUMBER, amount = parsedAmount, currency = DEFAULT_CURRENCY, readerType = ReaderType.INSERT, // Choose allowed card input method here tokenReq = tokenRequest, agreementID = agreementID, agreementType = agreementType, ) Common Usage Patterns Allow all input methods (most common) readerType = ReaderType.INSERT_CLESS_SWIPE Force contactless only readerType = ReaderType.CLESS Restrict to chip insert readerType = ReaderType.INSERT Allow tap + insert readerType = ReaderType.INSERT_CLESS Best Practices & Notes Prefer flexibility : Use INSERT_CLESS_SWIPE unless your flow or compliance rules require otherwise. Match hardware : Ensure the terminal supports the selected method(s) to avoid interaction errors. One per request : Only one readerType can be set per transaction. UI hint : If your UI lets a cashier pick methods, map those choices to a single constant before sending the request.
        • [Fields](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/fields.md): Request Field Type Description Constraints Example msgType Enum Specifies the type of transaction being initiated. Must be a valid MsgType enum value. MsgType.SALE invoiceNbr String Unique identifier for the transaction invoice. Alphanumeric, typically 8–12 characters. 10120304 amount Integer Transaction amount in minor currency units (e.g., cents). Must be a positive integer. 1500 currency String ISO 4217 currency code for the transaction. Must be a valid 3-letter currency code. USD readerType Enum Specifies the card reader method used for the transaction. Optional; must be a valid ReaderType enum value. ReaderType.INSERT_CLESS_SWIPE stan Integer System Trace Audit Number used to reference a previous transaction. Required for completion and void transactions. 2 tokenReq Boolean Indicates whether a token is requested for the transaction. true or false true agreementID String Identifier for the merchant agreement related to the transaction. Alphanumeric, format may include date and sequence. MERCH123_20250804_001 agreementType String Type of merchant agreement. Typically a single character code. I Response Title Description Description Constraints Example msgType String Type of transaction response Must be one of SALE, PREAUTH, SALECOMP, VOID, REFUND SALE responseCodes String Response code from the transaction Typically '00' for success 00 responseText String Textual description of the response Should match responseCodes meaning Success dateTime Datetime Timestamp of the transaction ISO 8601 format 2025-10-27T02:21:14Z cardEntryMode String Mode of card entry Single character code (e.g., C for contactless) C cardExpiryDate String Card expiration date Nullable; format MMYY null cardBin String Bank Identification Number of the card, first 6 digits of the PAN 6-digit numeric 541333 cardLast4 String Last 4 digits of the card number 4-digit numeric 0010 cardSchemeName String Card brand name Nullable MasterCard cardSchemeAppName String Application name on the card Nullable PPC MCD 01 v2 2 cardholderName String Name of the cardholder Nullable null sessionGUID String Session identifier for the transaction UUID format; Nullable 040fd541-faf8-445d-a8e6-2b4ccd641cbf stan String System Trace Audit Number 6-digit numeric 000001 token String Tokenized card reference Nullable 248757 rrn String Retrieval Reference Number Nullable; numeric 100001652541 totalAmount Float Total transaction amount Must be positive 15.0 onlineIndicator String Indicates if transaction was online Y or N Y receipt String Formatted receipt text Multiline string MID M11000000000098 ... emvPix String EMV PIX value 4-digit hexadecimal 1010 emvRid String EMV RID value Hexadecimal string A000000004 emvTsi String EMV TSI value 4-digit hexadecimal 0000 emvTvr String EMV TVR value 8-digit hexadecimal 0000008001 emvArqc String EMV ARQC value Hexadecimal string; Nullable BAA0082B5C384C2A Receipt Fields: MID String Merchant Identifier Alphanumeric, fixed length M11000000000098 TERM String Terminal Identifier Alphanumeric, fixed length T1100039 DATE String Transaction Date and Time Format: YYYYMMDDHHMMSS 20251027132044 TRAN Integer Transaction Sequence Number Positive integer 8 CARD String Masked Card Number Last 4 digits visible ************0010 Card Scheme String Card Brand Name Standard card brand MasterCard Card Scheme App Name String Card Application Name Descriptive name PPC MCD 01 v2 2 Entry Mode String Card Entry Method Descriptive label CONTACTLESS Transaction Type String Type of Transaction Standard transaction type REFUND AID String Application Identifier Hexadecimal format A0000000041010 AMOUNT Float Transaction Amount Currency format $15.00 TOTAL Float Total Amount Currency format $15.00 CURRENCY String Transaction Currency ISO 4217 format USD Verification Status String Cardholder Verification Result Descriptive label No Cardholder Verification
        • [Input Validation](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/input-validation.md): Input Validation is a critical process in software development that ensures all data received by an application is accurate, complete, and secure before it is processed. In the context of the TNSPay BYOA SDK, which runs directly on card terminal devices, input validation plays a vital role in maintaining transaction integrity, preventing errors, and ensuring compliance with security standards. Why Input Validation Matters Card terminals handle sensitive financial data and interact with external systems such as payment gateways, card networks, and merchant applications. Without proper input validation, the system is vulnerable to: Transaction failures due to malformed or missing data Security breaches from injection attacks or unauthorised access Compliance violations with PCI-DSS and EMV standards Poor user experience caused by unexpected behaviour or crashes
        • [Troubleshooting Checklist](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/troubleshooting-checklist.md): Issue Solution AIDL binding fails Verify AndroidManifest.xml service declarations Null responses Log onError callbacks and share with SDK vendor UI crashes Check if isFinishing before updating UI post rotation
      • [Handling Responses](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/handling-responses.md): Handling Responses The SDK returns the result via PaymentResponseService.responseCallback . Display the JSON response in a DialogActivity . This module sets up a response callback for handling payment responses received from the PaymentResponseService. When a response is received, the callback creates an Intent to launch the DialogActivity, passing the response data as a JSON string via the "json_response" extra. The Intent.FLAG_ACTIVITY_NEW_TASK flag ensures that the activity is started in a new task, which is useful when launching from a non-activity context. This design allows the application to display transaction results or messages in a dedicated dialog interface, improving user feedback and flow control after a payment operation. What Handling Responses Does 1 Registers Listeners Early It ensures that your app is ready to receive and process responses (e.g. transaction results, errors, device status) as soon as the activity starts. 2 Enables Real-Time Feedback Callbacks allow the app to react immediately to SDK events—such as payment success, failure, or timeout—without polling or waiting. 3 Improves User Experience By handling responses promptly, you can update the UI (e.g. show a receipt, display an error message, or prompt for retry) in a smooth and responsive way. 4 Supports Asynchronous Operations Many SDKs operate asynchronously. Callbacks let you manage these operations without blocking the main thread, keeping the app fast and fluid. 5 Centralises Event Handling Setting up callbacks helps consolidate logic for SDK interactions, making the codebase cleaner and easier to maintain. 6 Ensures Lifecycle Awareness By tying callbacks to the activity lifecycle, you avoid memory leaks and ensure that responses are only handled when the activity is active.
      • [Example: Sale Request Flow](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/example-sale-request-flow.md): User Input: Enters 50.00 as amount. UI Button Click: Plain text onSaleClicked = { val requestMsg = RequestMsg( msgType = MsgType.SALE, amount = 50.00, currency = "USD", etc. ) sdk.sendRequestMessage(requestMsg) } SDK Response: Plain text { "status": "approved", "transactionId": "TXN123", "amount": 50.00 }
      • [Releasing the SDK](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/releasing-the-sdk.md): Releasing the SDK Release resources in onDestroy : Releasing an SDK refers to the process of releases resources currently allocated and available for use by the next session.
      • [UI Integration Example](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/ui-integration-example.md): UI Integration Example (Jetpack Compose)
      • [Terminal States](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/terminal-states.md): State Description Value IDLE Initial state; no transaction in progress 0 CARD_READ Card is being read 1 PREPARE_ONLINE_DATA Preparing data for online transaction 2 PIN_INPUT Awaiting PIN input 3 ONLINE_PROCESSING Processing transaction online 4 ONLINE_TRANSFER Transferring data online 5 ONLINE_RECEIVE Receiving response from host 6 ONLINE_TIMEOUT Online transaction timed out 7 ENTER_AMOUNT User is entering transaction amount 8 CHECK_CARD Checking card validity 9 SCAN_CODE Scanning QR or barcode 10 OFFLINE_SEND Sending offline transaction data 11 SIGNATURE Capturing customer signature 12 CHECK_OFFLINE Checking offline transaction 13 CLSS_PROCESS Processing contactless transaction 14 EMV_PROCESS Processing EMV transaction 15 FALLBACK_REMOVE_CARD Prompting user to remove card for fallback 16 FALLBACK_SWIPE_CARD Prompting user to swipe card for fallback 17 WAIT_REMOVE_CARD Waiting for card removal 18 EMV_WAIT_APP_SELECT Waiting for EMV application selection 19 EMV_INPUT_PWD EMV password input 20 EMV_CARD_CONFIRM Confirming EMV card details 21 CLSS_DECTECT_2ND_TAP Detecting second tap for contactless transaction 22 CLSS_SEE_PHONE Prompting user to see phone for contactless 23 CLSS_READ_CARD_OK Contactless card read successfully 24 TRANS_CANCEL Transaction cancelled -1 ERROR_RECEIVED Error received during transaction -2 TRANS_ABORT Transaction aborted -3 TRANS_NOT_FOUND Transaction not found -4
  • [Terminal Management](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/terminal-management.md): Once the application is ready for deployment, please reach out to your TNS Account Manager to learn about the next steps
  • [Response/Action Codes](https://developer.pay.tnsi.com/api/card-present/tnspay-byoa-api-integration-guide/error-codes.md): The following guide contains information regarding the different Error codes supported by the TNS Terminal API and also provides information required to troubleshoot the terminal when necessary Positive Results Codes Reason Description 00 Approved The transaction can be treated as Approved. The issuer has authorized the payment, and all standard risk checks have passed. Funds will be captured according to normal processing timelines. No further action is required from the merchant. 08 Honor with identification The transaction may proceed if the cardholder provides valid identification. This response indicates conditional approval and requires additional verification before completion. 09 Request in Progress The transaction is currently being processed and a final response is pending. The terminal should wait for completion or retry after a timeout. 11 Partial approval The transaction was approved for a lesser amount than requested. The merchant should prompt for an additional payment method to cover the remaining balance. 85 No reason to decline The transaction is approved with no specific reason to decline. This is typically used for test or fallback scenarios. Y1 Offline approved The transaction was approved by the terminal as per the standard EMV scheme rules, this transaction has been processed offline, however all EMV risk and liability controls will still be present. The consumer's card has approved this transaction on behalf of their bank, their bank will honour this approval. The transaction will settle once the terminal has been able to forward this to TNS. There might be a mismatch between your reporting and the TNS with the Merchant Portal until the terminal is able to pass this transaction on. Y3 Unable to go online – offline approved The terminal attempted to process the transaction online, this process failed for some reason, the terminal has elected to process this transaction offline, this decision is based on configuration in the terminal. The transaction will be stored and forwarded at a later time when connectivity is restored. It was not the consumers card that gave the authority to do this like EMV Offline, in this scenario there is no liability shift to the card holders bank on this transaction. If the card holder cannot honour the transaction, then you will lose these finds. Deferred Authorisation should only be used when you do not want to cause operational issues on declines due to connectivity issues but are okay with the chance of declined transactions when the consumer has already departed with your service or product. Y6 Approved – TIAC The transaction was approved under TIAC rules. This is a fallback approval mechanism used in specific configurations where online authorization is not possible. The merchant should ensure compliance with TIAC guidelines. Negative Results Codes Reason Description 01 Refer to card issuer The transaction was declined.The cardholder must contact their issuing bank for further instructions.Merchant should not retry and advise the customer to use an alternate payment method. 02 Refer to card issuer (special condition) The transaction was declined.The issuer flagged a special condition requiring cardholder intervention.Merchant should advise the customer to contact their bank before retrying. 03 Invalid merchant The transaction was rejected.Merchant credentials are invalid or unrecognized due to configuration errors.Merchant should verify setup and contact their payment provider. 04 Card lost or stolen The transaction was declined.The card has been reported as lost or stolen by the issuer.Merchant may retain the card if safe and advise the customer to contact their bank. 05 Do not honor The transaction was declined.Issuer did not provide a specific reason, possibly due to account status or suspected fraud.Merchant should request an alternate payment method. 06 General error The transaction failed.A general processing error occurred due to system or network issues.Merchant may retry or escalate to technical support. 07 Card lost or stolen (special condition) The transaction was declined.The card is flagged under a special lost/stolen status requiring immediate attention.Merchant may be instructed to retain the card and follow acquirer guidelines. 12 Invalid transaction The transaction was rejected.The transaction type is unsupported or incorrectly formatted.Merchant should verify parameters and retry. 13 Invalid amount The transaction was rejected.The amount is invalid or exceeds configured thresholds.Merchant should correct the amount and retry. 14 Invalid account number The transaction was declined.The account number is not recognized or incorrectly formatted.Merchant should verify card details before retrying. 15 Invalid issuer The transaction was declined.The card issuer is not supported by the payment network.Merchant should request a different card from the customer. 16 Insufficient funds The transaction was declined.The cardholder’s account lacks sufficient funds.Merchant should request an alternate payment method or retry with a lower amount. 19 Re-enter transaction The transaction could not be processed.A temporary issue occurred during entry.Merchant should re-enter the transaction details and retry. 20 Invalid response The transaction failed.The issuer returned an invalid or unexpected response.Merchant should retry or escalate to technical support. 21 Invalid card number The transaction was declined.The card number format is incorrect or not recognized.Merchant should verify the card details before retrying. 22 Suspected malfunction The transaction failed.A terminal or system malfunction is suspected.Merchant should check the device and retry or contact support. 25 Account missing The transaction was declined.The requested account does not exist or cannot be found.Merchant should request an alternate payment method. 28 File unavailable The transaction failed.A required file or record is unavailable.Merchant should retry later or contact support. 30 Format error The transaction was rejected.The message format is invalid or corrupted.Merchant should verify the request structure and retry. 41 Merchant retain lost card The transaction was declined.The card has been reported lost by the issuer.Merchant should retain the card if safe and follow acquirer instructions. 43 Merchant retain stolen card The transaction was declined.The card has been reported stolen by the issuer.Merchant should retain the card if safe and follow acquirer instructions. 51 Insufficient funds The transaction was declined.The account has insufficient funds to complete the transaction.Merchant should request an alternate payment method. 52 No checking account The transaction was declined.The cardholder does not have a checking account linked to the card.Merchant should request an alternate payment method. 53 No saving account The transaction was declined.The cardholder does not have a savings account linked to the card.Merchant should request an alternate payment method. 54 Expired card The transaction was declined.The card has expired and is no longer valid.Merchant should request an alternate payment method. 57 Transaction not permitted The transaction was declined.The cardholder is not permitted to perform this transaction type.Merchant should request an alternate payment method. 58 Transaction not allowed at terminal The transaction was rejected.The terminal is not authorized to perform this transaction type.Merchant should verify terminal configuration. 59 Suspected fraud The transaction was declined.Issuer suspects fraudulent activity.Merchant should not proceed and may need to retain the card. 61 Exceeded amount limit The transaction was declined.The amount exceeds the card’s allowed limit.Merchant should reduce the amount or request another payment method. 62 Restricted card The transaction was declined.The card is restricted and cannot be used for this transaction.Merchant should request an alternate payment method. 63 Security violation The transaction failed.A security violation occurred during processing.Merchant should retry or escalate to support. 65 Exceeded count limit The transaction was declined.The card has exceeded the allowed number of transactions.Merchant should request an alternate payment method. 68 Response timeout The transaction failed.The issuer did not respond within the expected time.Merchant may retry or advise the customer to use another method. 78 Blocked card The transaction was declined.The card is blocked and cannot be used.Merchant should request an alternate payment method. 80 Issuer unavailable The transaction failed.The issuer is temporarily unavailable.Merchant may retry later or request another payment method. 82 Negative CVV The transaction was declined.CVV verification failed.Merchant should verify the card details and retry. 91 Issuers unavailable The transaction failed.The card issuer is not available to respond.Merchant should retry later or request another payment method. 92 Routing failure The transaction failed.The request could not be routed to the issuer.Merchant should retry or escalate to support. 93 Transaction cannot be completed The transaction was declined.Issuer restrictions prevent completion.Merchant should request an alternate payment method. 94 Duplicate transmission The transaction was rejected.It appears to be a duplicate submission.Merchant should verify and avoid resubmitting. 95 Reconciliation error The transaction failed.A reconciliation error occurred.Merchant should contact support for resolution. 96 System malfunction The transaction failed.A system malfunction occurred during processing.Merchant should retry or escalate to technical support. H0 Insert card The transaction requires card insertion.The terminal needs the card to be inserted for EMV processing.Merchant should prompt the customer accordingly. N0 Force STIP The transaction will proceed under fallback rules.Stand-in processing is required due to issuer unavailability.Merchant should ensure fallback configuration is correct. N3 Cash service unavailable The transaction was declined.Cash service is not available for this card or terminal.Merchant should inform the customer and suggest alternatives. N4 Cashback exceeded limit The transaction was declined.The cashback amount exceeds the allowed limit.Merchant should reduce the amount or decline the request. N7 CVV2 decline The transaction was declined.CVV2 verification failed during processing.Merchant should verify the card details and retry. P2 Invalid biller The transaction was rejected.The biller information provided is invalid.Merchant should correct the details and retry. Q1 Card authentication failed The transaction was declined.Card authentication failed during EMV or contactless processing.Merchant should request an alternate payment method. R0 Stop payment order The transaction was declined.A stop payment order has been issued by the issuer.Merchant should not retry and advise the customer to contact their bank. R1 Revocation order The transaction was declined.The issuer has revoked the transaction authorization.Merchant should not retry and request an alternate payment method. R3 Revocation order (alternate) The transaction was declined.The issuer has revoked the transaction authorization.Merchant should not retry and request an alternate payment method. XA Forward to issuer The transaction requires issuer intervention.It should be forwarded to the issuer for additional processing.Merchant should ensure connectivity and retry. XD Forward to issuer (alternate) The transaction requires issuer intervention.It should be forwarded to the issuer for additional processing.Merchant should ensure connectivity and retry. CA Cancelled The transaction was cancelled.It was aborted by the user or system before completion.No funds will be captured. TO Timeout The transaction timed out.No response was received within the expected timeframe.Merchant may retry or advise the customer to use another method. Z1 Offline declined The transaction was declined offline.The terminal rejected the transaction without issuer involvement.Merchant should request an alternate payment method. Z3 Unable to go online – offline declined The transaction was declined offline.The terminal could not connect for online authorization and rejected the transaction.Merchant should retry when connectivity is restored or request another payment method. Error Response Codes Code Constant Description Code Constant Description 1 SUCC NOREQ BATCH Settlement succeeded without doing batch upload -1 ERR_TIMEOUT Timeout -2 ERR_CONNECT Fail to connect -3 ERR_SEND Fail to send message -4 ERR_RECV Fail to receive message -5 ERR_PACK Fail to generate package -6 ERR_UNPACK Fail to parse package -7 ERR_PACKET Format of package is wrong -8 ERR_MAC MAC of package is wrong -9 ERR PROC CODE Process code is unmatched -10 ERR_MSG Message type is unmatched -11 ERR TRANS AMT Transaction amount is unmatched -12 ERR TRACE NO Trace no is unmatched -13 ERR TERM ID Terminal ID is unmatched -14 ERR MERCH ID Merchant ID is unmatched -15 ERR NO TRANS No transaction -16 ERR NO ORIG_TRANS Cannot find the original transaction -17 ERR HAS VOIDED Transaction has been voided -18 ERR VOID UNSUPPORTED Transaction cannot be voided -19 ERR COMM CHANNEL Comm channel error -20 ERR HOST REJECT Rejected by host -21 ERR_ABORTED Transaction aborted (no message) -22 ERR USER CANCEL Transaction aborted (user cancel) -23 ERR NEED SETTLE_NOW Need to settle now due to limits or currency -24 ERR NEED SETTLE_LATER Need to settle later due to limits or currency -25 ERR NO FREE_SPACE Need to settle due to storage limits -26 ERR NOT SUPPORT_TRANS Transaction is unsupported -27 ERR CARD NO Card number is unmatched -28 ERR_PASSWORD Wrong password -29 ERR_PARAM Wrong parameter -31 ERR BATCH UP NOT COMPLETED Batch upload not completed -33 ERR_AMOUNT Amount exceeded limit -34 ERR CARD DENIED Approved by host, declined by card -35 ERR CARD OFFLINE_DENIED Offline declined by card -36 ERR ADJUST UNSUPPORTED Transaction cannot be adjusted -37 ERR CARD UNSUPPORTED Card is unsupported -38 ERR CARD EXPIRED Expired card -39 ERR CARD INVALID Invalid card number -40 ERR UNSUPPORTED FUNC Unsupported function -41 ERR CLSS PRE_PROC Fail to complete CLSS pre-process -42 NEED FALL BACK Need to fall back -43 ERR INVALID EMV_QR Invalid EMV QR code -44 ERR INVALID BT_PRINTER Invalid BtPrinter code -45 ERR BT PRINT_CANCEL -46 ERR BT CONNECT -47 ERR CONTACT PRE_PROC -48 ERR NO SUPPORTED TRANS METHOD -49 ERR NO PIN_PAD -50 ERR_PIN -51 ERR_PED -52 ERR NO KEY -53 ERR CARD READ_FAIL -54 ON SEARCH CARD EVENT UPDATE_PARAM -55 ERR INVALID CARD Card format correct but not in card bin -56 ERR INVALID KEY_ENC Encryption key not found -57 ERR POS CANCEL WAIT CARD -58 ERR READ FLEET_CARD -59 ERR PED eTRACK2 -60 ERR_DATABASE -61 ERR MAG SERVICE_CODE Mag stripe service code is EMV but swiped -62 ERR MAG DATA_TRACK -63 ERR_CHAINLINK_WHITELIST Chainlink error -64 ERR HAS COMPLETED -65 ERR CHAINLINK LICENCE Chainlink license error -66 ERR CHAINLINK APP Chainlink app error -67 INVALID REQUEST DATA Request data is invalid -68 ERR NOT ALLOW FOREIGN CARD
• [REST Terminal API](https://developer.pay.tnsi.com/api/card-present/point-of-sale.md): This API provides a complete payment orchestration system for point-of-sale terminals. It supports the full payment lifecycle including authentication, sales processing, tokenization for secure card storage, refunds, and secondary transaction operations. All endpoints use REST principles with JSON request/response formats. Authentication is required for all operations. Core Capabilities: Authentication & Headers: All endpoints require HMAC authentication headers and a User-Agent header identifying your terminal application. See HMAC Authentication for details. Auth : Authenticate terminals and obtain session credentials Sale : Process card-present and card-not-present transactions Token : Create and manage payment tokens for recurring transactions Refunds : Process full and partial refunds against original sales Secondary Transactions : Handle post-authorization operations including captures, voids, and adjustments
  • [Authorization Transactions](https://developer.pay.tnsi.com/api/card-present/point-of-sale/authorization-transactions.md): An authorization transaction is conducted to validate a card with the cardholder's issuing bank and confirm the card's validity and available funds. This process does not instantly transfer funds but temporarily reserves the funds in the cardholder's account if sufficient fund is available. To complete the transfer from the cardholder's account to the merchant's account, the authorized transaction must be captured. The captured amount may be lower than the authorized sum, and merchants can choose to capture portions of the authorized amount on multiple occasions. Also, if the merchant wishes to capture an amount higher than the authorized sum, they have the option to conduct an incremental transaction using the authorized amount as a base and then proceed to capture the total amount comprising the authorized sum and the incremental value. Authorization transactions are commonly employed by merchants in situations where goods are dispatched post-purchase.
    • [Authorization using EMV Chip](https://developer.pay.tnsi.com/api/card-present/point-of-sale/authorization-transactions/authorization-using-emv-chip.md): The cardholder inserts the card containing the EMV chip into the card reader of the point-of-sale(POS) machine. The card reader then reads the EMV data from the chip and the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Authorization using Contactless EMV](https://developer.pay.tnsi.com/api/card-present/point-of-sale/authorization-transactions/authorization-using-contactless-emv.md): The cardholder taps or waves the card containing the EMV chip over the card reader of the point-of-sale(POS) machine. The card reader then reads the EMV data from the chip and the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Authorization using Magstripe Swipe](https://developer.pay.tnsi.com/api/card-present/point-of-sale/authorization-transactions/authorization-using-magstripe-swipe.md): If the card does not contain an EMV chip, the cardholder swipes the magnetic stripe of the card through the magnetic stripe reader part of the point-of-sale(POS) machine. The card reader then reads the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Authorization using Manual Input](https://developer.pay.tnsi.com/api/card-present/point-of-sale/authorization-transactions/authorization-using-manual-input.md): The cardholder manually enters the card number using the keypad on the point-of-sale(POS) machine. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Authorization using Fallback to Swipe](https://developer.pay.tnsi.com/api/card-present/point-of-sale/authorization-transactions/authorization-using-fallback-to-swipe.md): If the card's EMV chip is malfunctioning, the cardholder swipes the magnetic stripe of the card through the magnetic stripe reader part of the point-of-sale(POS) machine. The card reader then reads the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Sale Transactions](https://developer.pay.tnsi.com/api/card-present/point-of-sale/sale-transactions.md): A sale transaction can be explained as authorization and capture of funds at the same time. The sale transactions are usually used by merchants who deliver the goods almost immediately like retail stores where the customer receives the goods immediately.
    • [Sale using EMV Chip](https://developer.pay.tnsi.com/api/card-present/point-of-sale/sale-transactions/sale-using-emv-chip.md): The cardholder inserts the card containing the EMV chip into the card reader of the point-of-sale(POS) machine. The card reader then reads the EMV data from the chip and the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Sale using Contactless EMV](https://developer.pay.tnsi.com/api/card-present/point-of-sale/sale-transactions/sale-using-contactless-emv.md): The cardholder taps or waves the card containing the EMV chip over the card reader of the point-of-sale(POS) machine. The card reader then reads the EMV data from the chip and the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Sale using Magstripe Swipe](https://developer.pay.tnsi.com/api/card-present/point-of-sale/sale-transactions/sale-using-magstripe-swipe.md): If the card does not contain an EMV chip, the cardholder swipes the magnetic stripe of the card through the magnetic stripe reader part of the point-of-sale(POS) machine. The card reader then reads the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Sale using Manual Input](https://developer.pay.tnsi.com/api/card-present/point-of-sale/sale-transactions/sale-using-manual-input.md): The cardholder manually enters the card number using the keypad on the point-of-sale(POS) machine. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Sale using Fallback to Swipe](https://developer.pay.tnsi.com/api/card-present/point-of-sale/sale-transactions/sale-using-fallback-to-swipe.md): If the card's EMV chip is malfunctioning, the cardholder swipes the magnetic stripe of the card through the magnetic stripe reader part of the point-of-sale(POS) machine. The card reader then reads the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Token Transactions](https://developer.pay.tnsi.com/api/card-present/point-of-sale/token-transaction.md): The token transactions, use the token value instead of real card data.
    • [Token-Based Authorization](https://developer.pay.tnsi.com/api/card-present/point-of-sale/token-transaction/token-based-authorization.md): Transaction authorization takes place using the token obtained from the earlier transactions. The token value replaces the card information here. So we do not need any card information for this transaction. This type of transaction is usually generated from the portal or ecommerce sites. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Token-Based Sale](https://developer.pay.tnsi.com/api/card-present/point-of-sale/token-transaction/token-based-sale.md): A token-based sale takes place using the token obtained from the earlier transactions. The token value replaces the card information here. So we do not need any card information for this transaction. This type of transaction is usually generated from the portal or ecommerce sites. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Token-Based Refund](https://developer.pay.tnsi.com/api/card-present/point-of-sale/token-transaction/token-based-refund.md): A token-based refund takes place using the token obtained from the earlier transactions. The token value replaces the card information here. So we do not need any card information for this transaction. This type of transaction is usually generated from the portal or ecommerce sites. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Refund Transactions](https://developer.pay.tnsi.com/api/card-present/point-of-sale/refund-transactions.md): A refund transaction refers to the process of returning funds to a cardholder for a previous purchase. It allows merchants to reimburse customers for returned merchandise, canceled services, or other situations where a refund is warranted. We support two kinds of refund. Unlinked refund: Card present refund where the cardholder presents the card at the point-of-sale(POS) machine. Linked refund: A card not present refund where we use the TNS reference of the primary authorization or sale transaction. For more information please refer Secondary Transactions sections.
    • [Refund using EMV Chip](https://developer.pay.tnsi.com/api/card-present/point-of-sale/refund-transactions/refund-using-emv-chip.md): The cardholder inserts the card containing the EMV chip into the card reader of the point-of-sale(POS) machine. The card reader then reads the EMV data from the chip and the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Refund using Contactless EMV](https://developer.pay.tnsi.com/api/card-present/point-of-sale/refund-transactions/refund-using-contactless-emv.md): The cardholder taps or waves the card containing the EMV chip over the card reader of the point-of-sale(POS) machine. The card reader then reads the EMV data from the chip and the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Refund using Magstripe Swipe](https://developer.pay.tnsi.com/api/card-present/point-of-sale/refund-transactions/refund-using-magstripe-swipe.md): If the card does not contain an EMV chip, the cardholder swipes the magnetic stripe of the card through the magnetic stripe reader part of the point-of-sale(POS) machine. The card reader then reads the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Refund using Manual Input](https://developer.pay.tnsi.com/api/card-present/point-of-sale/refund-transactions/refund-using-manual-input.md): The cardholder manually enters the card number using the keypad on the point-of-sale(POS) machine. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
    • [Refund using Fallback to Swipe](https://developer.pay.tnsi.com/api/card-present/point-of-sale/refund-transactions/refund-using-fallback-to-swipe.md): If the card's EMV chip is malfunctioning, the cardholder swipes the magnetic stripe of the card through the magnetic stripe reader part of the point-of-sale(POS) machine. The card reader then reads the track data from the card. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
  • [Secondary Transactions](https://developer.pay.tnsi.com/api/card-present/point-of-sale/secondary-transaction.md): Once the merchant delivers the goods or services purchased, to realize the funds into the merchant's bank, the approved authorizations have to be captured using a capture transaction. Or when the customer cancels the order or returns the goods, the merchant can cancel the approved primary transaction in its entirety or refund only partial funds using void or reversal or refund. All such transactions are made on a primary transaction, they are termed as secondary transactions or we can call it as follow-up transactions. For secondary transactions, the card need not be presented at the point of sale or to the merchant. We are running additional transactions based on an approved primary transaction. PayOrch platform provides simple APIs to perform secondary transactions. PayOrch platform returns a transaction identifier in response of the primary transaction. That transaction identifier is the important data used to run secondary or follow-up transactions. In a case where the transaction identifier of the primary transaction is lost, there are other parameters that can be used to run the secondary transactions.
    • [Capture](https://developer.pay.tnsi.com/api/card-present/point-of-sale/secondary-transaction/capture.md): A capture or otherwise known as a completion transaction, is to finalize the original authorization transaction. The original authorization transaction identifier and the authorized amount are mandatory to process a capture transaction. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request. To test this sample capture request, start by initiating an authorize transaction. Upon approval of the authorize transaction, retrieve the transactionId & approvedAmount from the response. Use the transactionId as the originalTransactionId and approvedAmount as the originalTransactionAmount before proceeding with the transaction. Use transactionAmount to capture the desired transaction value. Entry mode is optional for capture transactions. The system will utilize the entry mode of the original transaction unless specifically overwritten in the request.
    • [Reversal](https://developer.pay.tnsi.com/api/card-present/point-of-sale/secondary-transaction/reversal.md): Reversal, also known as authorization reversal, occurs when an authorization is initially granted but subsequently reversed, either in full or in part, due to factors such as product/service unavailability, fraudulent transactions, or customer change of mind. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request. To test this sample reversal request, start by initiating an authorize transaction. Upon approval of the authorize transaction, retrieve the transactionId & approvedAmount from the response. Use the transactionId as the originalTransactionId and approvedAmount as the originalTransactionAmount before proceeding with the transaction. Entry mode is optional for linked refund transactions. The system will utilize the entry mode of the original transaction unless specifically overwritten in the request.
    • [Void](https://developer.pay.tnsi.com/api/card-present/point-of-sale/secondary-transaction/void.md): Void transactions are conducted on a sale transaction. To reverse a sale transaction before settlement takes place, the merchant must initiate a void transaction, referencing the original sale transaction. The void transaction amount should exactly match the original transaction amount. Partial void is not supported by the system. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request. To test this sample void request, start by initiating a sale transaction. Upon approval of the sale transaction, retrieve the transactionId & approvedAmount from the response. Use the transactionId as the originalTransactionId and approvedAmount as the originalTransactionAmount before proceeding with the transaction. Void amount should match with the approved amount. Partial void is not supported. Entry mode is optional for void transactions. The system will utilize the entry mode of the original transaction unless specifically overwritten in the request.
    • [Incremental](https://developer.pay.tnsi.com/api/card-present/point-of-sale/secondary-transaction/incremental.md): An Incremental transaction adjusts the original authorization amount when there is a change in the total transaction amount. This type of transaction is typically used in scenarios where the final cost of goods or services cannot be accurately predicted at the time of the initial authorization. For more info on additional functionality and optional fields, see Request Format . For more information on all possible responses, success and error codes, see Response Format . All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request. To test this sample incremental request, start by initiating an authorize transaction. Upon approval of the authorize transaction, retrieve the transactionId & approvedAmount from the response. Use the transactionId as the originalTransactionId and approvedAmount as the originalTransactionAmount before proceeding with the transaction. transactionAmount should be used as the incremented amount. Entry mode is optional for subsequent transactions. The system will utilize the entry mode of the original transaction unless specifically overwritten in the request.
• [ISO8583 Terminal API](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification.md): ISO 8583 is a standard defined by the International Organization for Standardization to facilitate information exchange for transactions using cards. ISO 8583 defines a message format so that different systems involved in a card transaction can exchange information in an interoperable manner. This standard has also evolved over the years to remain updated with newer and safer payment methods. The ISO 8583 message contains the following sections: Message Type Indicator This is part of the message that indicates what the purpose of the message is. For example, a message could be initiated by an acquirer requesting that the payment for a purchase be authorized by the issuer. Or, a message could be a response from the issuer that the payment has been authorized or declined. Similarly, another example could be a message that was initiated by the issuer to reverse a payment (in case of a payment dispute). There are many such purposes covering simple financial information exchange, administrative tasks, and settlements. Each of these can be communicated using the message type indicator. The message type indicator also contains information about who originated the message (acquirer or issuer). Bitmap This part of the ISO 8583 message indicates which data elements are actually present. For the party receiving an ISO 8583 message, the bitmap informs what specific information is present or absent. The presence of a data element in a specific message is indicated by a one (1) in the assigned position; a zero (0) indicates the absence of a data element in the assigned position. A bitmap is simply an indexing technique and consists of 64 bits numbered from the left starting with bit 1. Data Elements This is the part of the message that contains actual data. There are up to 128 data elements specified in the original ISO 8583:1987 standard and up to 192 data elements in later releases. All these data fields put together cover all the use cases including payments, reversals, settlements, and even administrative activities. Information about the card number (called primary account number), card expiry date, payment amount, payment date and time, conversion rate, and message authentication code (a field that is relevant if the user was asked to enter a password or PIN) are all passed as data elements in ISO 8583 and each data element has a defined position (called data field) in the message where it should be present. Each data field can either be of a fixed or variable length. Sample ISO8583 Message Title Description Title MTI BITMAP DATA FIELDS( Incomplete demo data only for sample* ) 0100 3238048000C18A1B 0000000012301116103008000001183008111600710034303230393938324D45D4352000101414944001441303030303030363135303030314554520007313030323539380840FFFF0610033245200001 Title Description Title Description MTI (Message Type Identifier) 0100 0= ISO 8583 version: 1987 1= Message class: Authorization 0= Message function: Request 0= Message origin: Acquirer Authorization request, from Acquirer to Card Issuer Title Description Title Description Title Description Title Primary Bit Map (64 bits) 3238048000C18A1B(HEX) Binary value(0011 0010 0011 1000 0000 0100 1000 0000 0000 0000 1100 0001 1000 1010 0001 1011) Title Description Title Description Title Description Title 0 10 20 30 40 50 60 1234567890 1234567890 1234567890 1234567890 1234567890 1234567890 1234 00 11 00 1 000 111 0000000 0 1 00 1 00000 0000000000 11 00000 11 0 00 1 0 1 0000 1 1 0 11
  • [Message Field Definitions](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-field-definitions.md): This section describes all fields currently supported by the TNS using ISO8583 format. Please refer the sub sections for more details. Message Field and Subfield Conditions Message Field Data Definitions Encryption Message Header Message Fields
    • [Message Field and Subfield Conditions](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-field-definitions/message-field-and-subfield-conditions.md): Title Description Description Code Condition M Mandatory O Optional SM The subfield is mandatory when the field is specified. 02 Mandatory if information is available and not supplied in the Track 2 Data. 03 If supplied in the original Authorisation Request (01XX) or Financial Transaction Request (02XX) message, is mandatory and shall contain the same data. 05 Mandatory if the PAN Entry Mode of F-22 POS Entry Mode == “05” or “07”. 07 At least one of PAN (F2, or F61 subfield Encrypted PAN) or Track 2 Data (F35, or F61 subfield Encrypted Track 2 Data) is mandatory. PAN is mandatory for keyed/contactless non-EMV Mode transactions (where F-22 POS Entry Mode begins with “01”). Track 2 Data is mandatory for all transactions except keyed/contactless non-EMV mode transactions (where F-22 POS Entry Mode does not begin with “01”). When CHD is encrypted using P2PE / DUKPT or other encryption schemes: PAN (if required) must be supplied in F-61 Encrypted Cardholder Data (subfield Encrypted PAN), and F2 PAN must be omitted. Track 2 Data (if required) must be supplied in F-61 Encrypted Cardholder Data (subfield Encrypted Track 2 Data), and F-35 Track 2 Data must be omitted. When CHD is not encrypted: PAN (if required) must be supplied in F2 PAN. Track 2 Data (if required) must be supplied in F-35 Track 2 Data . F-61 Encrypted Cardholder Data must be omitted. 08 If F-48 Transaction Context Data subfield CVM Used == “04” (Online PIN): For Payment Cards only: PIN must be supplied in F52 Payment Card PIN Data. F-123 Non-Payment Card PIN Data must be omitted. For Non-Payment Cards only: When CHD is encrypted using P2PE / DUKPT or other encryption schemes: PIN must be supplied in F-123 Non-Payment Card PIN Data (subfield Encrypted Current PIN). F52 Payment Card PIN Data must be omitted. When CHD is not encrypted: PIN must be supplied in F-123 Non-Payment Card PIN Data (subfield Clear Current PIN). F52 Payment Card PIN Data must be omitted. 09 When CHD is encrypted using P2PE / DUKPT or other encryption schemes: All PIN values must be supplied in the Encrypted PIN fields of F-123 Non-Payment Card PIN Data . F52 Payment Card PIN Data must be omitted. When CHD is not encrypted: All PIN values must be supplied in the Clear PIN fields of F-123 Non-Payment Card PIN Data . F52 Payment Card PIN Data must be omitted. 10 Mandatory if using DUKPT P2PE ( F-60 Security Data subfield Encryption Mode must identify the mode of encryption as DUKPT). 13 Mandatory if the reconciliation is not in balance; contains the value calculated by the host. 15 Mandatory in a response message if the original request or advice message was successfully processed by the host. 16 Mandatory in a response message if the data element was present in the original request or advice message. If present, it shall contain the same data as the original message. 17 Mandatory in an advice message if the data element was present in the original request response message. If present, it shall contain the same data as the original request response message. 18 Mandatory in a void request message. If present, it shall contain the same data as the original response message. 21 Either 64 or 128 is mandatory if using DUKPT P2PE ( F-60 Security Data subfield Encryption Mode must identify the mode of encryption as DUKPT). 22 Mandatory if a second (non-payment) card participates in the request. (E.g. dual fleet card scenarios.)
    • [Message Field Data Definitions](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-field-definitions/message-field-data-definitions.md): Title Description Title Format Key Definition Example Simple Types DD Day of month, 01-31. 31 MM Month of year, 01-12 12 YY Year, 00-99 21 hh Hour of day, 00-23. 23 mm Minute of hour, 00-59 59 ss Second of minute, 00-59 59 Complex Types BITMAP Primary and Secondary Bitmaps (128 bits, 16 bytes). n/a LLLTLV Variable-length Tag/Length/Value-encoded field containing between 1 and 999 characters or bytes. The field data is prefixed by the length of the field data in four decimal digits, encoded in Packed Unsigned BCD into two bytes. The field data may contain one or more Subfields. Each Subfield is formatted as follows: Tag (Subfield Identifier): Three alphanumeric characters, encoded in ASCII; Length (of value data): Four decimal digits (0000-0999), encoded in Packed Unsigned BCD into two bytes; Value: Data, in ASCII, BCD, or raw bytes (binary fields). n/a LLVAR A variable-length field containing between 1 and 99 characters, bytes (Binary fields), or nibbles (Packed BCD fields). The field data is prefixed by the length of the field data in two decimal digits, encoded in Packed Unsigned BCD into a single byte. A field with the value of length 5 would be prefixed by 05 in BCD [0000 0101] LLLVAR A variable-length field containing between 1 and 999 characters or bytes. The field data is prefixed by the length of the field data in four decimal digits, encoded in Packed Unsigned BCD into two bytes. A field with the value of length 123 would be prefixed by 0123 in BCD [0000 0001][0010 0011] Title Description Title Attribute Key Definition Example a Alphabetic characters, encoded in ASCII. A-Z, a-z b Raw Binary data, grouped into blocks of 8 bits (a byte). The length of such an attribute defines the number of bytes of field data. n/a n Numeric digits (0-9), unsigned. This data is encoded in 4-bit Packed Unsigned BCD (Binary Coded Decimal) containing decimal digits . Each decimal digit is represented by a 4-bit nibble; therefore, two digits are packed into a single byte. The length of such an attribute defines the number of nibbles of field data. Odd-length fields must be preceded by a leading zero nibble [0000] to ensure the field comprises whole bytes; the length should not include any such nibble (see Note 3 below). 0-9 Each byte consists of two nibbles, each nibble representing a decimal digit. E.g.: Nibble 1: [0101] (decimal 5) Nibble 2: [1001] (decimal 9) nS Numeric digits (0-9), signed. This data is encoded in 4-bit Packed Signed BCD (Binary Coded Decimal) containing decimal digits , and a mandatory single sign indicator in the last (least significant) nibble. Use hexadecimal value xC [1100] for positive sign indicator (+), and hexadecimal value xD [1101] for negative sign indicator (-). Each decimal digit is represented by a 4-bit nibble; therefore, two digits are packed into a single byte. The length of such an attribute defines the number of nibbles of field data, excluding the sign nibble . Odd-length fields must be preceded by a leading zero nibble [0000] to ensure the field comprises whole bytes; the length should not include any such nibble (see Note 3 below). +/- 0-9 Each byte consists of two nibbles, each nibble representing a decimal digit, or a sign indicator (last nibble only). E.g.: Nibble 1: [0001] (decimal 1) Nibble 2: [0000] (decimal 0) Nibble 3: [0101] (decimal 5) Nibble 4: [1101] (negative sign indicator) Pz Tracks 2 and 3 code set, as defined in the relevant ISO documentation. This data is encoded in 4-bit Packed Unsigned BCD (Binary Coded Decimal) containing hexadecimal digits . Each hex digit is represented by a 4-bit nibble; therefore, two digits are packed into a single byte. Digits 0-9 represent decimal values 0-9; A-F represent special characters/sentinels. The length of such an attribute defines the number of nibbles of field data. Odd-length fields must be preceded by a leading zero nibble [0000] to ensure the field comprises whole bytes; the length should not include any such nibble (see Note 3 below). Each byte consists of two nibbles, each nibble representing a hexadecimal digit. E.g.: Nibble 1: [0111] (hexadecimal 7) Nibble 2: [1101] (hexadecimal D, representing sentinel '=' in Track 2 Data) p Pad characters (spaces), encoded in ASCII. “ “ s Special characters, encoded in ASCII. = ; ? { } etc v Various formats. See field/subfield definitions for details. n/a x+n “C” for Credit or “D” for Debit (encoded in ASCII), as a prefix to numeric digit(s) encoded in 4-bit Packed Unsigned BCD (Binary Coded Decimal) containing decimal digits . Note: Whilst the C/D prefix is to be encoded in ASCII into a full byte, any subsequent numeric digits are to be encoded in 4-bit Packed Unsigned BCD, as per the definition of attribute “n”. The length specified in the field definition refers to the number of numeric digits only (for example, in the case of “x+n 4”, 4 numeric digits should follow a leading “C” or “D” prefix). The length of such an attribute defines the number of bytes of field data (for example, in the case of “C123456”, the length of the attribute is 4 bytes). Odd-length numeric portions must be preceded by a leading zero nibble [0000] to ensure the numerical data is comprised of whole bytes only. Leading byte encoded in ASCII, and subsequent bytes consisting of two nibbles, each nibble representing a decimal digit. E.g. for “x+n 3” value “C123”: Byte 1: ASCII character “C” Byte 2: Nibble 1: [0000] (leading zero nibble, see Note 3 below) Nibble 2: [0001] (decimal 1) Byte 3: Nibble 1: [0010] (decimal 2) Nibble 2: [0011] (decimal 3) [digit] Fixed length of [digit] characters/bytes/nibbles. “n 5”: 5 numeric characters, fixed length, e.g. “12345” ..[digit] Variable length up to [digit] characters/bytes/nibbles. “a ..3”: Up to 3 alphabetic characters, variable length, e.g. “ab” or “abc” [digit1]..[digit2] Variable length between [digit1] and [digit2] characters/bytes/nibbles. “n 2..4”: Between 2 and 4 numeric characters, variable length, e.g. “12”, “123”, “1234” Notes All fixed-length Numeric-only data elements (e.g. “n 5”) are to be right-justified and padded with leading zeros as required (e.g. “00012”). All other fixed-length data elements (e.g. “an 5”) are to be left-justified with trailing pad characters (spaces) as required (e.g. “ab2 “). All elements encoded using Packed Unsigned BCD data must consist of an even number of nibbles. If the field data consists of an odd number of nibbles, prepend a leading zero nibble to the field data. Variable-length fields must report the length in nibbles excluding the leading zero nibble.
    • [Encryption](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-field-definitions/encryption.md): Connection Encryption All connections to the Terminal Switch Server ISO8583 are to be encrypted via TLS (v1.2 or later). Non-encrypted (plain) connections are not supported. Message Field Data Encryption The majority of message fields within the packager specification are not to be populated with encrypted data. These fields are to be protected by the TLS encryption that protects the entire message. Specific message fields (or subfields of composite fields) are explicitly defined as containing encrypted data only. Encrypted fields should only be used when using P2PE / DUKPT or other encryption schemes. (See F-60 Security Data , subfield Encryption Mode for identification of the encryption scheme used.) DUKPT Keys When DUKPT is used to protect specific message field data, three separate DUKPT keys are to be used to encrypt the data, as follows: Title Description DUKPT Key Description PIN Used to protect Payment Card PIN data only. P2PE Used to protect transaction data (excluding Payment Card PIN data) requiring DUKPT encryption. DATA Used to protect the MAC field only. See also F-64 / F-128 Message Authentication Code
  • [Message Fields](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields.md): Message Fields Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Title Description Field Name Format Attribute DUKPT Key 0100 0110 0200 0210 0220 0221 0230 0300 0310 0420 0421 0430 0520 0521 0530 0800 0810 Notes 0 Message Type Indicator (MTI) n 4 M M M M M M M M M M M M M M 1 Bitmap BITMAP b 16 M M M M M M M M M M M M M M 2 PAN LLVAR n ..19 07 07 07 07 03 To be used when CHD is not encrypted only. 3 Processing Code n 6 M M M M M M M M 03 M F-3 Processing Code 4 Transaction Amount n 12 M M M M M M 03 03 Amount of the transaction in the lowest denomination of the currency (Currency Code, Transaction). 7 Transmission Date Time MMDDhhmmss n 10 M M M M M M M M M M M M M M Applies to message rather than transaction. This date/time should be expressed in UTC. 11 System Trace Audit Number n 6 M M M M M M M M M M M M M M 12 Local Transaction Time hhmmss n 6 M M M M M M M M 03 M M M The time the transaction occurred (took effect), in the terminal’s local timezone. 13 Local Transaction Date MMDD n 4 M M M M M M M M 03 M M M The date the transaction occurred (took effect), in the terminal’s local timezone. 14 Expiry Date YYMM n 4 02 02 02 02 03 22 Point Of Service Entry Mode n 3 M M M M 03 F-22 Point Of Service Entry Mode 25 Point Of Service Condition Code n 2 M M M M 03 F-25 Point Of Service Condition Code 35 Track 2 Data LLVAR Pz ..37 07 07 07 07 03 F-35 Track 2 Data To be used when CHD is not encrypted only. 37 Retrieval Reference Number an 12 15 15 17 15 17 38 Authorisation Code anp 6 O O O O 03 39 Response Code an 2 M M M M M M M F-39 Response Code 41 Card Acceptor Terminal Identification ans 8 M M M M M M M M M M M M M M TNS Terminal Id - ABCD1234 42 Card Acceptor Identification Code ans 15 M M M M M M M M M M M M M M TNS Merchant Id - [0|1|8]00000 48 Reserved Private - Transaction Context Data LLLTLV v ..999 M 15 M 15 M 15 M 15 M F-48 Reserved Private - Transaction Context Data 49 Currency Code, Transaction n 3 M M M M M M 03 03 Numeric Currency Code of the transaction, as defined by ISO4217. 50 Currency Code, Reconciliation n 3 M M Numeric Currency Code of all transaction amounts summarized in the reconciliation, as defined by ISO4217. 52 Payment Card PIN Data b 8 PIN 08 08 53 Security Related Control Information (DUKPT Key Security Numbers) b 30 10 10 10 10 10 10 10 10 10 10 10 10 10 10 F-53 Security Related Control Information (DUKPT Key Security Numbers) Deviation from ISO8583 standard (attribute). 55 Integrated Circuit Card (ICC) Data LLLVAR b ..999 05 O 05 O 05 05 Chip data for EMV Contact and Contactless transactions. Deviation from ISO8583 standard (attribute). 60 Reserved Private - Security Data LLLTLV v ..999 M M M M M M M M M M M M M M F-60 Reserved Private - Security Data 61 Reserved Private - Encrypted Cardholder Data LLLTLV b ..999 07 07 07 07 03 F-61 Reserved Private - Encrypted Cardholder Data Deviation from ISO8583 standard (attribute). 62 Reserved Private - Cardholder Context Data LLLTLV v ..999 O O O 03 F-62 Reserved Private - Cardholder Context Data 63 Reserved Private - Product Data LLLTLV v ..999 O O O 03 F-63 Reserved Private - Product Data 64 MAC b 8 DATA 21 21 21 21 21 21 10 10 See also Field 128. F-64 / F-128 Message Authentication Code 66 Settlement Code n 1 M F-66 Settlement Code 70 Network Management Information Code n 3 M M F-70 Network Management Information Code Deviation from ISO8583 standard (attribute). 74 Credits, Number n 10 M 13 Count of 0200 messages with 21xxxx Processing Code . 75 Credits, Reversal Number n 10 M 13 Count of 042x messages for 0200 messages with 21xxxx Processing Code . 76 Debits, Number n 10 M 13 Count of 0100 and 0200 messages with 00xxxx Processing Code . 77 Debits, Reversal Number n 10 M 13 Count of 042x messages for 0100 and 0200 messages with 00xxxx Processing Code . 80 Inquiries, Number n 10 M 13 Count of 0200 messages with 31xxxx Processing Code . 81 Authorisations, Number n 10 M 13 Count of 0100 messages with 00xxxx Processing Code . 86 Credits, Amount n 16 M 13 Represented in the lowest denomination of the currency (Currency Code, Reconciliation). Sum of amounts of all Credits. 87 Credits, Reversal Amount n 16 M 13 Represented in the lowest denomination of the currency (Currency Code, Reconciliation). Sum of amounts of all Reversals of Credits. 88 Debits, Amount n 16 M 13 Represented in the lowest denomination of the currency (Currency Code, Reconciliation). Sum of amounts of all Debits. 89 Debits, Reversal Amount n 16 M 13 Represented in the lowest denomination of the currency (Currency Code, Reconciliation). Sum of amounts of all Reversals of Debits. 90 Original Data Elements n 42 M F-90 Original Data Elements Deviation from ISO8583 standard (attribute). 97 Amount, Net Settlement x+n 16 M 13 Represented in the lowest denomination of the currency (Currency Code, Reconciliation). Net sum of amounts of all Debits and Credits. 123 Reserved Private - Non-Payment Card PIN Data LLLTLV v ..999 08 08 M F-123 Non-Payment Card PIN Data 124 Reserved Private - Second Card Cardholder Data LLLTLV v ..999 22 22 22 03 F-124 Reserved Private - Second Card Cardholder Data 125 Reserved Private - Associated Account Data LLLTLV v ..999 O O O F-125 Reserved Private - Associated Account Data 128 MAC b 8 DATA 21 21 21 21 21 21 10 10 10 10 10 10 See also Field 64. F-64 / F-128 Message Authentication Code Message Field Fallback Response Values The above Message Fields table identifies the fields that apply for each supported Message Type, and the conditions under which they apply. In many cases, a field will be identified as mandatory for a given response Message Type, and the value to be provided in that response is dependent upon the (also mandatory) value supplied in the original Request or Advice message that preceded it. Should a Request or Advice message be sent that omits a mandatory field, the corresponding response message Response Code will contain a value indicating the request message was not valid. In such cases, any mandatory fields in the response message that depend upon absent request data will be populated with fallback values to ensure the response message remains compliant with the above specification. The following table lists the fallback values that may be used in such cases. Title Description Title Description Title Description Title Field Name Fallback Response Value 3 Processing Code 000000 4 Amount, Transaction 000000000000 11 System Trace Audit Number 000000 12 Time, Local Transaction 000000 13 Date, Local Transaction 0000 41 Card Acceptor Terminal Identification 00000000 42 Card Acceptor Identification Code 000000000000000 49 Currency Code, Transaction 000 50 Currency Code, Reconciliation 000 60 Reserved Private - Security Data Encryption Mode subfield: 00 70 Network Management Information Code 000
    • [Message Header](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/message-header.md): Each message is preceded by a header consisting of a Message Length Indicator (MLI), in "2E" format (2-byte network byte order with the length of the MLI excluded). The MLI value reflects the length of the message body, excluding the length of the header. No TPDU is included in the header. Title Description Header Type Description 2E 2-byte network byte order, MLI excluded The raw data body of the message follows immediately after the header, formatted as described in the subsequent section.
    • [F-0 Message Type Indicator](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-0-message-type-indicator.md): Description MTI stands for Message Type Indicator. This is the part of the message that indicates what the purpose of the message is. For example, a message could be initiated by an acquirer requesting that the payment for a purchase be authorized by the issuer. Or, a message could be a response from the issuer that the payment has been authorized or declined. Similarly, another example could be a message that was initiated by the issuer to reverse a payment (in case of a payment dispute). There are many such purposes covering simple financial information exchange, administrative tasks and settlements. Each of these can be communicated using the message type indicator. The message type indicator also contains information about who originated the message (acquirer or issuer). Attribute nP 4, 2 bytes Format Title Description Title Description MTI Name Message Purpose 0100 Authorisation Request Pre-Authorisation Request 0110 Authorisation Request Response Pre-Authorisation Response 0200 Financial Transaction Request Payment Request (Payment/Completed Pre-Authorisation) Void Request Balance Inquiry Request Credit Request 0210 Financial Transaction Request Response Payment Response (Payment/Completed Pre-Authorisation) Void Response Balance Inquiry Response Credit Response 0220 / 0221 Financial Transaction Advice / Financial Transaction Advice Repeat Completion Advice Offline-Accepted Payment Advice Offline-Accepted Credit Advice (Pre-Authorisation) Void Advice / Repeat 0230 Financial Transaction Advice Response Completion Response Offline-Accepted Payment Advice Response Offline-Accepted Credit Advice Response (Pre-Authorisation) Void Response 0300 Acquirer File Update Request PIN Change Request 0310 Acquirer File Update Response PIN Change Response 0420 / 0421 Acquirer Reversal Advice / Repeat Reversal Advice / Repeat 0430 Acquirer Reversal Advice Response Reversal Response 0520 / 0521 Acquirer Reconciliation Advice / Repeat Settlement/Reconciliation Advice / Repeat 0530 Acquirer Reconciliation Advice Response Settlement/Reconciliation Response 0800 Network Management Request Log On Request Echo Request 0810 Network Management Request Response Log On Response Echo Response
    • [F-1 Bitmap](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-1-bitmap.md): Description ISO 8583 uses a concept called "bit map", where each data element is assigned a position indicator in a control field, or bit map. The presence of a data element in a specific message is indicated by a one (1) in the assigned position; the absence of a data element is indicated by a zero (0) in the assigned position. Each application transaction includes one (1) bit map. A bit map consists of 64 bits numbered from the left starting with bit 1. Attribute b 16 Format BITMAP
    • [F-2 Primary Account Number (PAN)](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-2-primary-account-number-pan.md): Description This field is a series of digits that identify a customer account or relationship. Attributes n19 Format LLVAR
    • [F-3 Processing Code](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-3-processing-code.md): Description This field identifies the type of the transaction submitted and what accounts, if any, the transaction affects. It is a composite field consisting of 3 subfields. Attributes n 6, 3 bytes Format This field contains three subfields with defined two-digit numeric codes for each of the individual sub-fields. Subfield Description Positions Attribute Conditions Example Transaction Type Type of transaction 1-2 n 2 SM 00 From Account Source account 3-4 n 2 SM 00 To Account Destination account 5-6 n 2 SM 00 Transaction Type Value Description Notes 00 Debit Goods and Services Use for Pre-Authorisation and Payment Requests, and Completion, Offline-Accepted Payment, and (Payment) Reversal Advices. 02 Debit Adjustment (Void) Use for Void Requests and Void Advices (Transaction Amount must be set to zero). 20 Refund Not supported. 21 Deposit Use for Credit Requests, Offline-Accepted Credit and (Credit) Reversal Advices. 31 Balance Inquiry Use for Balance Inquiry Requests. 90 PIN Change Use for PIN Change Requests. 92 Settlement Request Use for Settlement/Reconciliation Advices. Value Description Notes 00 Default Account 10 Savings Account 20 Cheque Account 30 Credit Card Account
    • [F-4 Transaction Amount](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-4-transaction-amount.md): Description Amount of the transaction in the lowest denomination of the currency (Currency Code, Transaction) Attributes n 12, 6 bytes Format Right justify and zero fill this field.
    • [F-7 Transmission Date Time](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-7-transmission-date-time.md): Description Applies to messages rather than transactions. This date/time should be expressed in UTC. Attributes n 10, 5 bytes Format MMDDhhmmss
    • [F-11 System Trace Audit Number](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-11-system-trace-audit-number.md): Description This field is a merchant-generated number that identifies the transaction. Attributes n 6, 3 bytes Format It is a required field mirrored back in the response message.
    • [F-12 Local Transaction Time](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-12-local-transaction-time.md): Description The time the transaction occurred (took effect), in the terminal’s local timezone.This is a required field that uniquely identifies the transaction within the acquirer's system, usually to match a response to a request. Attributes nP 6, 3 bytes Format hhmmss
    • [F-13 Local Transaction Date](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-13-local-transaction-date.md): Description The date the transaction occurred (took effect), in the terminal’s local timezone. This is a required field that indicates the local date that the transaction took place at the terminal. For advice and reversal transactions, this is the time that the original transaction occurred. Attributes n 4, 2 bytes Format MMDD
    • [F-14 Expiration Date](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-14-expiration-date.md): Description This field defines the expiration date of the card used to initiate the transactions. Attributes n 4, 2 bytes Format YYMM Note You must include this field in non-original Host Data Capture request messages or if you do not supply Field 35 - Track II Data. Transactions that do not include the expiration date in some form have a higher probability of decline.
    • [F-22 Point Of Service Entry Mode](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-22-point-of-service-entry-mode.md): Description This field identifies the actual method used to capture the account number and expiry date when a terminal is used, and the PIN capture capability of the terminal. This is a fixed-length field consisting of 2 subfields. Attributes n 4, 2 bytes Format Subfield Description Positions Attribute Conditions Example PAN Entry Mode The method by which the PAN was read from the card. 1-2 n 2 SM 05 PIN Entry Capability Capability of the terminal to enter/capture the PIN. 3 n 1 SM 1 PAN Entry Mode Value Description Notes 00 Unknown Not supported 01 Keyed (Manual Entry) 02 Magnetic Stripe (possibly constructed manually, CVV may be checked) 03 Barcode or QR Code 04 OCR Not supported 05 Integrated Circuit Card (ICC) - CVV may be checked 07 Contactless Integrated Circuit Card 10 Credential On File Not supported 80 Fallback 90 Magnetic Stripe as read from Track 2 Not supported 91 Contactless Magnetic Stripe 95 Integrated Circuit Card (ICC) - CVV may not be checked Not supported PIN Entry Capability Value Description Notes 0 Unknown 1 Terminal can accept PIN 2 Terminal cannot accept PIN 8 PINpad unavailable
    • [F-25 Point Of Service Condition Code](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-25-point-of-service-condition-code.md): Description This field contains a value that describes the overall environment in which a transaction is taking place. Attributes n 2, 1 byte Format Value Description Notes 00 Normal Presentment
    • [F-35 Track 2 Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-35-track-2-data.md): Description This field should contain the information encoded on Track II of the magnetic stripe on the card or the bar code information for gift cards, excluding start and end sentinel and longitudinal redundancy check (LRC) characters. Note that this field should not be used when CHD is encrypted using DUKPT or other encryption schemes. See F-61 Encrypted Cardholder Data (subfield Encrypted Track 2 Data). This field attribute is defined as “Pz ..37”, (Packed Unsigned BCD, containing hexadecimal digits). Each hex digit is represented by a 4-bit nibble (two digits encoded in a single byte). Digits 0-9 represent decimal values 0-9; A-F represents special characters/sentinels. The field can contain a maximum of 37 hexadecimal digits; odd-length fields must contain a leading nibble containing 0 (making for a maximum of 38 nibbles across 19 bytes). Attributes Pz ..37 Format Element Format Notes PAN (Primary Account Number) Up to 19 digits Up to 19 digits. Field Separator = To be encoded using the relevant Hexadecimal value. See ‘Sentinels’ below for encoding. Expiry Date YYMM Replace with a Field Separator if not present. Service Code 3 digits Replace with a Field Separator if not present. Discretionary Data Balance of available space May include the PIN offset, PIN Verification Number (PVN), or the PIN Verification Key Indicator (PVKI) and PIN Verification Value (PVV), and card verification value). Sentinels Sentinel Usage ASCII Value Hexadecimal Value Start Sentinel ; xB Field Separator = xD End Sentinel ? x
    • [F-37 Retrieval Reference Number](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-37-retrieval-reference-number.md): Description This field yields a value generated by the message originator to associate a unique identifier to a given transaction. You can use this value to identify the transaction throughout the transaction's life cycle (authorization, reversal, and so on) Attributes an 12
    • [F-38 Authorisation Code](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-38-authorisation-code.md): Description This field contains a value generated by the authorizing processor to indicate their acceptance of the transaction. For all approved credit card transactions, use Field 38 to pass the authorization ID response. Attributes anp 6 Format The format of this field is dictated by the authorizing processor
    • [F-39 Response Code](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-39-response-code.md): Description This field contains a value that describes the result of the previous related request. The value will indicate if the request was approved or declined, and should be used by the terminal to determine any subsequent actions to be taken (including communication with the cardholder). This is a fixed length field of two alphanumeric characters, encoded in ASCII. Attributes an 2 Format Value Description Terminal Action Notes 00 Approved Approve 01 Refer to card issuer Decline 02 Refer to card issuer, special condition Decline 03 Invalid merchant Decline 04 Pick-up card Decline 05 Declined Decline 06 Error Decline 07 Pick-up card, special condition Decline 08 Honour with identification Approve For attended terminals only: message should be reversed (if applicable) if cardholder cannot be identified by operator. 12 Invalid transaction Decline 13 Invalid amount Decline 14 Invalid card number Decline 15 No such issuer Decline 17 Customer cancellation Decline 19 Re-enter transaction Decline 20 Invalid response Decline 21 No action taken Decline 25 Unable to locate record Decline 30 Format error Decline 33 Expired card, pick-up Decline 38 PIN tries exceeded, pick-up Decline 39 No credit account Decline 40 Function not supported Decline 41 Lost card, pick-up Decline 43 Stolen card, pick-up Decline 46 Identification required Decline 51 Insufficient funds Decline 52 No check account Decline 53 No savings account Decline 54 Expired card Decline 55 Incorrect PIN Decline 56 No card record Decline 57 Transaction not permitted to cardholder Decline 58 Transaction not permitted on terminal Decline 59 Suspected fraud Decline 61 Exceeds withdrawal limit Decline 62 Restricted card Decline 63 Security violation Decline 75 PIN tries exceeded Decline 91 Issuer or switch inoperative Decline 92 Routing error Decline 93 Violation of law Decline 94 Duplicate transaction Decline 95 Reconcile error Decline 96 System malfunction Decline An unexpected error occurred. G0 Invalid message data Decline Terminal message contains invalid data. This response code is generated by the Terminal Switch Server only. G1 Message security error Decline Failure to perform successful message decryption/encryption using P2PE or other security scheme. This response code is generated by the Terminal Switch Server only. G2 Message MAC error Decline Failure to verify message MAC. This response code is generated by the Terminal Switch Server only. G3 Transaction failed - host not contacted Decline Request could not be processed and sent to host (possible terminal or gateway misconfiguration). G4 Transaction association error Decline Subsequent Terminal message could not be matched to an original, or the subsequent message could not be accepted given the current state of the original. G6 Gateway timeout Request: Decline, Reverse Advice: Repeat Gateway did not return a response to the switch in the allocated time. If this response code is returned to the terminal, the terminal should send a corresponding Reversal Advice or Repeat Advice message as required. This response code is generated by the Terminal Switch Server only. G7 Host not available Request: Decline Advice: Repeat Request could not be processed due to failure to connect to host. If this response code is returned by an acquirer integration in response to an Advice message, the Gateway should enqueue a Repeat and return an Approved response code to the terminal. If this response code is returned to the terminal in response to an Advice message, the terminal should send a corresponding Repeat Advice message. G8 Host timeout Requests: Decline Advices: Repeat Host did not return a response in the allocated time. If this response code is returned by an acquirer integration in response to a Request message, the Gateway should enqueue a Reversal and return the same response code to the terminal. If this response code is returned by an acquirer integration in response to an Advice message, the Gateway should enqueue a Repeat and return an Approved response code to the terminal. If this response code is returned to the terminal in response to a Request message, the terminal should not send a Reversal Advice message. Any request whose corresponding response message contains this code should be treated as declined. If this response code is returned to the terminal in response to an Advice message, the terminal should send a corresponding Repeat Advice message. G9 Host error Decline Host response could not be parsed for unknown/other reason. If this response code is returned by an acquirer integration in response to a Request message, the Gateway should enqueue a Reversal and return the same response code to the terminal. If this response code is returned by an acquirer integration in response to an Advice message, the Gateway should enqueue a Repeat and return an Approved response code to the terminal. If this response code is returned to the terminal in response to a Request message, the terminal should not send a Reversal Advice message. Any request whose corresponding response message contains this code should be treated as declined. If this response code is returned to the terminal in response to an Advice message, the terminal should send a corresponding Repeat Advice message. H0 Insert card Decline Host demands that card be inserted (or alternative workflow be performed) before reattempting request. H1 PIN required Decline Host demands that PIN be provided when reattempting request. H2 PIN change required Decline Host demands that PIN be changed (or set) prior to reattempting the request.
    • [F-41 Card Acceptor Terminal Identification](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-41-card-acceptor-terminal-identification.md): Description This field contains a unique code that provides identification(TNS Provide Terminal ID) of the terminal or device originating the request. Attributes ans 8 Format ABCD1234
    • [F-42 Card Acceptor Identification Code](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-42-card-acceptor-identification-code.md): Description TNS Provided merchant ID. Attributes ans 15 Format ABCH1248
    • [F-48 Reserved Private - Transaction Context Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-48-reserved-private-transaction-context-data.md): Description This field contains data related to the transaction context, as required by ADVAM in order to qualify and process the transaction. This is a TLV (Tag/Length/Value) encoded field, in LLLTLV format. Attributes v ..999 Format LLLTLV Subfield Description Tag Attribute Conditions Transaction GUID Unique identifier for the Transaction in TNS systems. UID ans 36 0110, 0210, 0230, 0310: 15 0220, 0420: 17 0200: 18 Terminal Local Timezone Offset The offset from UTC, in format HHMM, of the terminal’s local timezone (such as +0930 or -0500). Note that this is a signed numeric field. TZO nS 4 0100, 0200, 0220, 0300, 0420: SM Message Reason Code Specifies the reason the message was processed as a Request (taken online), as an Advice (accepted offline), or as a specific category of Message Type . Based on ISO8583-2 Message Reason Code. MRC n 4 0100, 0200, 0220, 0300, 0420: SM CVM Used Cardholder Verification Method used by the terminal. CVM n 2 0100, 0200, 0300: SM 0220, 0420: 17 Merchant Choice Routing Indicates if the transaction is to be routed (processed) through a network configured by the merchant or terminal, if supported. MCR n 1 0100, 0200, 0220, 0300, 0420: O MCR Application Identifier The Application Identifier (AID) of the network to process the transaction, if known. (Hexadecimal digits.) AID an ..32 0100, 0200, 0220, 0300, 0420: O Equipment Transaction Reference A reference for the transaction assigned or otherwise used by equipment interfacing with the terminal (such as a POS device, vending machine, etc), if any. ETR anps ..32 0100, 0200, 0220, 0300, 0420: O Host Response Message A free-form textual message providing additional context of the result of the transaction request. This message is provided by the Gateway or upstream host if available. Note: This information is for debugging and logging purposes only, and should not be displayed to the cardholder. This message does not constitute a human-readable representation of F39 Response Code. HRM anps ..64 0110, 0210, 0230, 0310: O Settlement Batch Identifier The identifier of the settlement batch into which the transaction is allocated for clearing, if any. SBI n 6 0110, 0210, 0230: O Void Transaction Reason Not supported. VTR Not supported. Not supported. Message Reason Code Note that these codes are a subset of those Message Reason Codes defined in the ISO8583-2 standard. Value Description MTI Message Types Notes Reason for Advice (transaction accepted offline) 1003 Card issuer unavailable 0220 Offline-Accepted Payment Advice Offline-Accepted Credit Advice To be used only when all of the following are true: Initial Pre-Authorisation, Payment or Credit Request has failed (timeout, link or system error only). Initial request has been reversed. TNS, merchant, acquirer and issuer support offline acceptance of the transaction. ICC indicates the transaction may be accepted offline. An advice specifying this value will not refer to any previous transaction. 1004 Terminal processed 0220 Completion Advice (Pre-Authorisation) Void Advice To be used for all Financial Transaction Advices preceded by an approved Pre-Authorisation. 1005 ICC processed 0220 Completion Advice Not supported. 1006 Under floor limit 0220 Completion Advice Not supported. Reason for Request (transaction taken online) 1503 Terminal random selection 0100 0200 Pre-Authorisation Request Payment Request Credit Request Not supported. 1504 Unable to read/process ICC Data; Magstripe fallback 0100 0200 Pre-Authorisation Request Payment Request Credit Request Use when F-22 Point Of Service Entry Mode begins with “80” 1505 Online forced by ICC 0100 0200 Pre-Authorisation Request Payment Request Credit Request Not supported. 1506 Online forced by card acceptor 0100 0200 Pre-Authorisation Request Payment Request Credit Request 1508 Online forced by terminal 0100 0200 0300 Pre-Authorisation Request Payment Request (Payment/Completed Pre-Authorisation) Void Request Balance Inquiry Request Credit Request PIN Change Request 1509 Online forced by card issuer 0100 0200 Pre-Authorisation Request Payment Request Credit Request 1510 Over floor limit 0100 0200 Pre-Authorisation Request Payment Request Credit Request Default (when floor limit is 0) Reason for Reversal 4002 Suspected malfunction 0420 (Pre-Authorisation) Reversal Advice (Payment) Reversal Advice (Credit) Reversal Advice Terminal or Gateway internal error 4021 Timeout waiting for response 0420 (Pre-Authorisation) Reversal Advice (Payment) Reversal Advice (Credit) Reversal Advice CVM Used Value Description Notes 00 None No CVM rules are compatible with the terminal (cardholder verification cannot be performed), or no cardholder verification is required. 01 No CVM CVM List is not present (e.g. Magstripe fallback), or empty (no CVM rules present); cardholder verification cannot be performed. 02 Offline PIN PIN verified by terminal. 03 Mobile / Consumer Device CVM Cardholder verified by their device (e.g. mobile phone or smart watch), using device-specific method(s). 04 Online PIN PIN verified by acquirer/issuer. 07 Signature Signature was captured from the cardholder. Merchant Choice Routing Value Description Notes 0 Not Enabled Transaction will be routed via card scheme network in accordance with Gateway configuration only. Do not specify MCR Application Identifier in conjunction with this value. 1 Enabled Transaction will be routed via merchant- or terminal-preferred network, if supported. Specify MCR Application Identifier in conjunction with this value, if known.
    • [F-49 Transaction Currency Code](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-49-transaction-currency-code.md): Description The numeric Currency Code of the transaction, as defined by ISO4217. Attributes n 3, 2 bytes Format See ISO4217 for currency codes
    • [F-50 Reconciliation Currency Code](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-50-reconciliation-currency-code.md): Description The numeric Currency Code of all transaction amounts is summarized in the reconciliation, as defined by ISO4217. Attributes n 3, 2 bytes Format See ISO4217 for currency codes
    • [F-52 Payment Card PIN Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-52-payment-card-pin-data.md): Description This field assigns a number to the cardholder that uniquely identifies that cardholder at the Point of Sale. You must encrypt the Personal Identification Number (PIN) using DES encryption before transmission to TNS. Attributes b 8
    • [F-53 Security Related Control Information (DUKPT)](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-53-security-related-control-information-dukpt.md): Description This field contains the Key Security Numbers (including the transaction counter) used to derive the DUKPT keys used for encrypting/protecting/translating sensitive data (such as cardholder data, PIN data, MAC, etc) to be protected by DUKPT. This field is only required for DUKPT P2PE messages when F-60 Security Data subfield Encryption Mode identifies the mode of encryption as DUKPT. This is a binary field, of length 30 bytes. Subfields must appear in the order detailed below. Attributes b 30 Format Subfield Description Positions Attribute Conditions Data Key Security Number KSN for the Data key (used for MAC generation/verification) 1 - 10 b 10 10 P2PE Key Security Number KSN for the P2PE key (used for protecting cardholder data) 11 - 20 b 10 10 PIN Key Security Number KSN for the PIN key (used for protecting PIN data) 21 - 30 b 10 10 This field is a Deviation from ISO8583 standard (attribute).
    • [F-55 Integrated Circuit Card (ICC) Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-55-integrated-circuit-card-icc-data.md): Description Chip data for EMV Contact and Contactless transactions. Attributes b 999 Note: Deviation from ISO8583 standard (attribute)
    • [F-60 Reserved Private - Security Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-60-reserved-private-security-data.md): Description This field contains data related to the secure encryption of the message and/or data elements. This is a TLV (Tag/Length/Value) encoded field, in LLLTLV format. Attributes v 999 Format Title Description Subfield Description Tag Attribute Conditions Encryption Mode Security scheme used to protect/encrypt CHD, PIN Block, MAC, and other cypher data. ENC n 2 SM Terminal Cryptographic Unit (TCU) ID ID of the TCU in the terminal. Required to identify and authenticate the terminal. If the TCU ID is not available, the merchant can use the Terminal Serial Number as a substitute for the TCU ID. The merchant should send the serial number to TNS, allowing it to be loaded into the HSM for authentication purposes. TCU n 16 0100, 0200, 0220, 0300, 0420, 0520, 0800: SM Operator Username Username of the Operator used to authenticate the terminal with the TNS Gateway. USR ans ..64 0100, 0200, 0220, 0300, 0420, 0520, 0800: SM Terminal Serial Number Not supported. TSN Not supported. Not supported. Terminal Part Number Not supported. TPN Not supported. Not supported. Encryption Mode Title Description Value Description Notes 00 No Encryption (Whitelisted) 01 DUKPT 02 AS2805 Not supported 03 Merchant RSA Key Encryption Not supported 04 Merchant AES Key Encryption Not supported
    • [F-61 Reserved Private - Encrypted Cardholder Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-61-reserved-private-encrypted-cardholder-data.md): Description This field contains Encrypted Cardholder Data (CHD) including the Encrypted PAN and Encrypted Track 2 Data fields. It should only be used when CHD is encrypted using P2PE / DUKPT or other encryption schemes. (See F-60 Security Data , subfield Encryption Mode for identification of encryption scheme used.) If CHD fields are not to be encrypted (independently of the message as a whole), do not use this field. This is a TLV (Tag/Length/Value) encoded field, in LLLTLV format. Attributes b 999 Format LLLTLV Subfield Description Tag Attribute DUKPT Key Conditions Encrypted PAN PAN encrypted by the encryption method identified in Security Data. Note: This data should be encoded in ASCII prior to encrypting. PAN b ..999 (up to overall field capacity) P2PE 07 Encrypted Track 2 Data Track 2 Data encrypted using the encryption method identified in Security Data. See Track 2 Data Format for information regarding the format of the Track 2 Data content within this field. Note: This data should be encoded in ASCII prior to encrypting. T2D b ..999 (up to overall field capacity) P2PE 07 Note: Deviation from ISO8583 standard (attribute)
    • [F-62 Reserved Private - Cardholder Context Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-62-reserved-private-cardholder-context-data.md): Description This field contains data related to the cardholder in the context of the transaction, if applicable. This is a TLV (Tag/Length/Value) encoded field, in LLLTLV format. Attributes v ..999 Format LLLTLV Subfield Description Tag Attribute Conditions Employee Identifier Employee / Driver Identifier or number. EID anps ..32 To be determined. Vehicle Odometer Current odometer reading of the vehicle pertaining to the transaction. VOD n 7 To be determined. Vehicle Registration Tag Registration tag of the vehicle pertaining to the transaction. VRT anps ..32 To be determined.
    • [F-63 Reserved Private - Product Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-63-reserved-private-product-data.md): Description This field contains data related to products associated with the transaction, if applicable. Note that this field may contain one or more instances of the Product subfield, each of which represents a single instance of a Product. The value of each subfield is itself a TLV-encoded field, whose format is detailed below. This is a TLV (Tag/Length/Value) encoded field, in LLLTLV format. Attributes v ..999 Format LLLTLV Subfield Description Tag Format Attribute Conditions Product Data for a single instance of a product associated with the transaction. Note that there may be multiple instances of this subfield. PRD LLLTLV Product v ..999 (up to overall field capacity) SM Rounding Amount of rounding applied to the transaction amount, in the lowest denomination of the currency (Currency Code, Transaction), with a leading “C” (Credit - when rounding down) or “D” (“Debit” - when rounding up) prefix. If not present, rounding is assumed to be 0. For example, rounding the transaction amount up by “$0.02” would be expressed as “D2”. (Note that the numerical portion of this field is encoded in 4-bit Packed Unsigned BCD, as per the attribute definition; therefore any odd-length numerical values must be must be preceded by a leading zero nibble [0000] to ensure the numerical data is comprised of whole bytes only. Therefore, in the above example, the value “D2” would be encoded as the ASCII byte “D” followed by the digits 0 and 2 in 4-bit Packed Unsigned BCD.) RND x+n 1..4 O Product This subfield contains data related to a single instance of a product associated with the transaction. This is a TLV (Tag/Length/Value) encoded field, in LLLTLV format. Subfield Description Tag Attribute Conditions Product Code Product Code to identify the product. Valid Product Codes are defined below. Note that this subfield must not be specified in conjunction with the Host Product Code subfield - they are mutually exclusive . PCD n 8 One of Product Code OR Host Product Code must be specified only Host Product Code Upstream host-specific code to identify the product to that host. This subfield should only be used when no applicable Product Code is available, or when it is necessary to override the Product Code mapping for the relevant upstream host. Note that this subfield must not be specified in conjunction with the Product Code subfield - they are mutually exclusive . HPC ans ..12 One of Product Code OR Host Product Code must be specified only Quantity Quantity of units of this product type associated with this transaction. The value is expressed as “n 9.3”: the rightmost (least significant) three digits are fraction digits (to the right of the absent decimal point). For example, “12.34” would be expressed as “12340”. QTY n 4..12 SM Unit Price Unit price of the product, in the lowest denomination of the currency (Currency Code, Transaction). The value is expressed as “n 10.2”: the rightmost (least significant) two digits are fraction digits (to the right of the absent decimal point). For example, “$12.34” would be expressed as “123400”. UPR n 3..12 SM Total Price Total price of all units of this product in this transaction, in the lowest denomination of the currency (Currency Code, Transaction). This value is expressed as whole units only. For example, “$12.34” would be expressed as “1234”. Note that the Total Price may not equal the value of Unit Price multiplied by the value of Quantity, owing to any rounding that may have been applied. TPR n 1..12 SM Description Description of the product. DES anps ..32 100, 200, 220, 420: O Product Code These codes are a subset of those published by GS1 ; the full list can be found here . Value Description 10000159 Beer 10000026 Milk (Shelf Stable) 10000214 Ice 10000215 Ice Cream/Ice Novelties (Frozen) 10000223 Fruit Juice Drinks - Ready to Drink (Shelf Stable) 10000232 Packaged Water 10000928 Printed Periodicals 50000000 Food/Beverage/Tobacco 50130000 Milk/Butter/Cream/Yogurts/Cheese/Eggs/Substitutes 50161800 Confectionery Products 50180000 Bread/Bakery Products 50181900 Bread 50182100 Biscuits/Cookies 50190000 Prepared/Preserved Foods 50192100 Snacks 50200000 Beverages 50201700 Coffee/Tea/Substitutes 50202200 Alcoholic Beverages (Includes De-Alcoholised Variants) 50202300 Non Alcoholic Beverages - Ready to Drink 50211800 Tobacco 53000000 Beauty/Personal Care/Hygiene 75000000 Household/Office Furniture/Furnishings
    • [F-64/F-128-Message Authentication Code](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-64-f-128-message-authentication-code.md): Description This field contains a Message Authentication Code (MAC) - a mechanism to validate the content of the message between the sender and the receiver. The field contains 8 bytes of raw binary data. The MAC must be provided in Field 64 only when the message utilizes fields in the first bitmap only (fields 1-64), or in Field 128 only when the message utilizes one or more fields in the second bitmap (65-128). To ensure messages are MACed consistently, they must be prepared consistently. As such, each message will be MACed without the MAC field set, and without the corresponding bit set in the bitmap. Attributes b 8
    • [F-66 Settlement Code](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-66-settlement-code.md): Description This field indicates the result of the reconciliation request. Attributes n 1 Format Value Description Notes 1 In balance 2 Out of balance 3 Error out of balance
    • [F-70 Network Management Information Code](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-70-network-management-information-code.md): Description This field identifies the network management administrative action to be performed. Attributes n 3, 2 bytes Format Value Description Notes 001 Log On 0800 (Request) and 0810 (Request Response) message types only. 002 Log Off 0800 (Request) and 0810 (Request Response) message types only. 301 Echo Test 0800 (Request) and 0810 (Request Response) message types only. Note: Deviation from ISO8583 standard (attribute).
    • [F-74 Credits, Number](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-74-credits-number.md): Description Count of 0200 messages with 21xxxx Processing Code . Attributes n 10
    • [F-75 Credits, Reversal Number](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-75-credits-reversal-number.md): Description Count of 042x messages for 0200 messages with 21xxxx Processing Code . Attributes n 10
    • [F-76 Debits, Number](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-76-debits-number.md): Description Count of 0100 and 0200 messages with 00xxxx Processing Code . Attributes n 10
    • [F-77 Debits, Reversal Number](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-77-debits-reversal-number.md): Description Count of 042x messages for 0100 and 0200 messages with 00xxxx Processing Code . Attributes n 10
    • [F-80 Inquiries, Number](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-80-inquiries-number.md): Description Count of 0200 messages with 31xxxx Processing Code . Attributes n 10
    • [F-81 Authorisations, Number](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-81-authorisations-number.md): Description Count of 0100 messages with 00xxxx Processing Code . Attributes n 10
    • [F-86 Credits, Amount](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-86-credits-amount.md): Description Represented in the lowest denomination of the currency (Currency Code, Reconciliation). The sum of amounts of all Credits. Attribute n 16
    • [F-87 Credits, Reversal Amount](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-87-credits-reversal-amount.md): Description Represented in the lowest denomination of the currency (Currency Code, Reconciliation). The sum of amounts of all Reversals of Credits. Attributes n16
    • [F-88 Debits, Amount](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-88-debits-amount.md): Description Represented in the lowest denomination of the currency (Currency Code, Reconciliation). The sum of amounts of all Debits. Attributes n 16
    • [F-89 Debits, Reversal Amount](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-89-debits-reversal-amount.md): Description Represented in the lowest denomination of the currency (Currency Code, Reconciliation). The sum of amounts of all Reversals of Debits. Attributes n 16
    • [F-90 Original Data Elements](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-90-original-data-elements.md): Description This field, used for reversal request messages only, identifies those values from the original transaction which an issuer may need to successfully reverse the original request. This is a fixed-length field consisting of 5 subfields. Attributes n 42 Format Subfield Description Positions Attribute Conditions Example Original Message Type Indicator (MTI) MTI of the original request (F0). 1-4 n 4 SM 0100 Original System Trace Audit Number (STAN) STAN of the original request (F11). 5-10 n 6 SM 123456 Original Transmission Date Time Transmission Date Time of the original request (F7). 11-20 n 10 SM 3112235959 Original Acquiring Institution ID Fill this subfield with zeros. 21-31 n 11 SM 00000000000 Original Forwarding Institution ID Fill this subfield with zeros. 32-42 n 11 SM 00000000000 Deviation from ISO8583 standard (attribute).
    • [F-97 Amount, Net Settlement](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-97-amount-net-settlement.md): Description Represented in the lowest denomination of the currency (Currency Code, Reconciliation). The net sum of amounts of all Debits and Credits. Attributes x+n 16
    • [F-123 Reserved Private - Non-Payment Card PIN Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-123-reserved-private-non-payment-card-pin-data.md): Description This field contains Non-Payment Card PIN Data fields. Note that PIN data fields are classified as Clear or Encrypted : Clear fields should only be used when CHD is NOT encrypted . Encrypted fields should only be used when CHD is encrypted using P2PE / DUKPT or other encryption schemes. (See F-60 Security Data , subfield Encryption Mode for identification of encryption scheme used.) This is a TLV (Tag/Length/Value) encoded field, in LLLTLV format. Attributes V 999 Format LLLTLV Subfield Description Tag Attribute DUKPT Key Conditions Clear Current PIN Current PIN of the Non-Payment Card ( non-encrypted CHD only ). CCP ans ..999 (up to overall field capacity) 0100, 0200: 08 0300: 09 Clear New PIN New PIN of the Non-Payment Card ( non-encrypted CHD only ). CNP ans ..999 (up to overall field capacity) 0300: 09 Clear Confirm New PIN Confirm New PIN of the Non-Payment Card ( non-encrypted CHD only ). CCN ans ..999 (up to overall field capacity) 0300: 09 Encrypted Current PIN Current PIN of the Non-Payment Card, encrypted by the encryption method identified in Security Data ( encrypted CHD only ). Note: This data should be encoded in ASCII prior to encrypting. ECP b ..999 (up to overall field capacity) P2PE 0100, 0200: 08 0300: 09 Encrypted New PIN New PIN of the Non-Payment Card, encrypted by the encryption method identified in Security Data ( encrypted CHD only ). Note: This data should be encoded in ASCII prior to encrypting. ENP b ..999 (up to overall field capacity) P2PE 0300: 09 Encrypted Confirm New Pin Confirm New PIN of the Non-Payment Card, encrypted by the encryption method identified in Security Data ( encrypted CHD only ). Note: This data should be encoded in ASCII prior to encrypting. ECN b ..999 (up to overall field capacity) P2PE 0300: 09
    • [F-124 Reserved Private-Second Card Cardholder Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-124-reserved-private-second-card-cardholder-data.md): Description This field contains Second Card Cardholder Data fields. (Second card cardholder data should only be specified for specific scenarios, such as when dual fleet cards participate in a single transaction.) Note that Second Card Cardholder Data fields are classified as Clear or Encrypted : Clear fields should only be used when CHD is NOT encrypted . Encrypted fields should only be used when CHD is encrypted using P2PE / DUKPT or other encryption schemes. (See F-60 Security Data , subfield Encryption Mode for identification of encryption scheme used.) This is a TLV (Tag/Length/Value) encoded field, in LLLTLV format. Attributes V 999 Format LLLTLV Subfield Description Tag Attribute DUKPT Key Conditions Clear Second Card Track 2 Data Second Card Track 2 Data ( non-encrypted CHD only ). CT2 Pz ..37 0100, 0200, 0220: 22 (and CHD is not encrypted only) Encrypted Second Card Track 2 Data Second Card Track 2 Data encrypted using the encryption method identified in Security Data ( encrypted CHD only ). Note: This data should be encoded in ASCII prior to encrypting. ET2 b ..999 (up to overall field capacity) P2PE 0100, 0200, 0220: 22 (and CHD is encrypted only)
    • [F-125 Reserved Private - Associated Account Data](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/message-fields/f-125-reserved-private-associated-account-data.md): Description This field contains account data (balances, awards and redemptions) related to account(s) associated with the transaction, if applicable. Note that this field may contain one or more instances of the Associated Account subfield, each of which represents data for a single instance of an Associated Account. The value of each subfield is itself a TLV-encoded field, whose format is detailed below. This is a TLV (Tag/Length/Value) encoded field, in LLLTLV format. Subfield Description Tag Format Attribute Conditions Associated Account Data for a single instance of an account associated with the transaction. Note that there may be multiple instances of this subfield. AAC LLLTLV Associated Account v ..999 (up to overall field capacity) SM Associated Account This subfield contains data related to a single instance of an account associated with the transaction. This is a TLV (Tag/Length/Value) encoded field, in LLLTLV format. Note that all subfields containing Unit measurements or balances are represented in the Unit Type associated with the Account Type for that Account. Each Unit measurement is expressed as “x+n 10.2”: the rightmost (least significant) two digits are fraction digits (to the right of the absent decimal point). The prefix must be “C” (credit) for positive or zero values, or “D” (debit) for negative values. For example, a credit balance of “12.34” would be expressed as “C1234”. The numerical portion of any such field is encoded in 4-bit Packed Unsigned BCD, as per the attribute definition; therefore any odd-length numerical values must be preceded by a leading zero nibble [0000] to ensure the numerical data is comprised of whole bytes only. Therefore, in the case of a credit of “1.23”, the value would be encoded as the ASCII byte “C” followed by the digits 0, 1, 2 and 3 (in 4-bit Packed Unsigned BCD). The overall length (in bytes) of this example value would be 3. Attributes V 999 Format LLLTLV Subfield Description Tag Attribute Conditions Account Type Account Type to identify the type of account. Valid Account Types are defined below. ACT ans ..12 SM Opening Unit Balance Opening unit balance (before the effect of this transaction, if any) of the account associated with this transaction. OUB x+n 3..12 SM Closing Unit Balance Closing unit balance (after the effect of this transaction, if any) of the account associated with this transaction. CUB x+n 3..12 SM Total Units Awarded Total number of units awarded (credited, accrued) as a result of this transaction, if any, and added to the Closing Balance of the account associated with this transaction. This value includes any bonus units awarded. TUA x+n 3..12 O Bonus Units Awarded Number of units awarded (credited, accrued) as a bonus or other special condition as a result of this transaction, if any, and added to the Closing Balance of the account associated with this transaction. BUA x+n 3..12 O Total Units Redeemed Total number of units redeemed (debited, consumed) as a result of this transaction, if any, and deduced from the Opening Balance of the account associated with this transaction. TUR x+n 3..12 O Account Type Value Description Unit Type PMILES Petron Miles loyalty scheme. Petron Miles Point ADO Malaysian ADO (Automated Diesel Oil) fuel subsidy/discount scheme. Fuel, Litres FLEET Petron Fleet Cards Money, RM Amount
  • [Auth Message](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/sample-messages/auth-message.md): Request 01003238048000C18A1B0000000000000012301116103008000001183008111600710034303230393938324D45524348414E54444556494345200058545A4F000500800C4D52430004151043564D0002044D4352000101414944001441303030303030363135303030314554520007313030323539380840FFFF0610033245200001FFFF06100132452000010000000000000000000001545F24032709305F2A0204585F340101820209008407A0000006150001950500000080009A032311169C01009F02060000000012309F03060000000000009F080200019F090200019F10200FA501A800F8000000000000000000000F0011111111111111111111111111119F1A0204589F2608C2384ED4F30D2E2E9F2701809F3303E0F8C89F34033F00009F3501229F360209399F37049B0700D20034454E43000201544355001600000012402099825553520010504554524F4E5F415049002954324400246E43153D9E1FAB4FE1B34E30CB7C1CE4381266A70F79678B00355052440030485043000431303031515459000410005550520003000054505200041231C7790EB09F92562E Title Description Title Description MTI(Message Type Identifier) 0100 0= ISO 8583 version : 1987 1= Message class: Authorization 0= Message function : Request 0= Message origin: Acquirer Authorization request , from Acquirer to Card Issuer Title Description Primary Bit Map (64 bits) 3238048000C18A1B Equivalent binary of Primary Bit Map Title Description Title Description Title Description Title 0 10 20 30 40 50 60 1234567890 1234567890 1234567890 1234567890 1234567890 1234567890 1234 00 11 00 1 000 111 0000000 0 1 00 1 00000 0000000000 11 00000 11 0 00 1 0 1 0000 1 1 0 11 Detected Data Elements Title Description Title Description Id Field Type Usage Value 3 n 6 Processing code <000000> 4 n 12 Amount, transaction <000000001230> 7 n 10 Transmission date & time <1116103008> 11 n 6 System trace audit number (STAN) <000001> 12 n 6 Local transaction time (hhmmss) <183008> 13 n 4 Local transaction date (MMDD) <1116> 22 n 3 Point of service entry mode <007> 25 n 2 Point of service condition code <10> 41 ans 8 Card acceptor terminal identification <03430323> 42 ans 15 Card acceptor identification code <0393938324D4552> 48 an...999 Additional data (private) <8414E54444556494345200058545A4F000500800C4D5243000 4151043564D0002044D4352000101414944001441303030303 030363135303030314554520007313030323539380840FFFF0 610033245200001FFFF0610013245200001000000000000000 0000001545F24032709305F2A0204585F34010182020900840 7A0000006150001950500000080009A032311169C01009F020 60000000012309F03060000000000009F080200019F0902000 19F10200FA501A800F8000000000000000000000F001111111 1111111111111111111119F1A0204589F2> 49 a or n 3 Currency code, transaction <608> 53 n 16 Security related control information <C2384ED4F30D2E2E> 55 ans...999 ICC data – EMV having multiple tags <Warning: Not valid length indicator detected = 9F2 Could not continue parsing. Please check your ISO8583 message> 60 ans...999 Reserved (national) (e.g. settlement request: batc h number, advice transactions: original transactio n amount, batch upload: original MTI plus original RRN plus original STAN, etc.) <809F3303E0F8C89F34033F00009F3501229F360209399F3704 9B0700D20034454E4300020154435500160000001240209982 5553520010504554524F4E5F415049002954324400246E4315 3D9E1FAB4FE1B34E30CB7C1CE4381266A70F79678B00355052 44003048504300043130303151545900041000555052000300 0054505200041231C7790EB09F92562E> 61 ans...999 Reserved (private) (e.g. CVV2/service code transactions) <Warning: Not valid length indicator detected = Could not continue parsing. Please check your ISO8583 message> 63 ans...999 Reserved (private) <Warning: Not valid length indicator detected = Could not continue parsing. Please check your ISO8583 message> 64 b 64 Message authentication code (MAC) <> Sample PreAuth:
    • [Sale](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/sample-messages/auth-message/sale.md): Sale Request The following is a formatted sale transaction request Plain text 6000190000 Sale Response The following is the formatted sale transaction response Plain text 6000000019
    • [PreAuthorization](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/sample-messages/auth-message/preauthorization.md): The following are sample formatted ISO8583 messages for dual message transactions: PreAuth Request Plain text 6000190000 PreAuth Response Response message received from the ISO8583 interface: Plain text 6000000019
    • [Capture](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/sample-messages/auth-message/capture.md): Capture Advice The following is a formatted capture advice. Plain text 6000190000 Capture Response: The following is a formatted capture response you will receive Plain text 6000000019
    • [Reversal](https://developer.pay.tnsi.com/api/card-present/tss-iso8583-interface-specification/sample-messages/auth-message/reversal.md): The following is a sample transaction reversal advice message. A reversal advice can only be performed if the transaction has not yet been settled. A reversal cannot apply to a capture transaction. Reversal Advice Message Plain text 6000190000 Reversal Advice Response Plain text 6000000019
• [Webhook Notifications](https://developer.pay.tnsi.com/api/supporting-apis/webhook-notifications.md): Webhook Notifications deliver real-time HTTP POST callbacks to your server when payment events occur on the TNS Payment Orchestration platform. Instead of polling for transaction status, your system receives instant notification when a payment is approved or declined. The below steps will help you to get started with setting up Webhooks 1 Ensure you have an API Key with Webhook Access Your merchant account must have an API key with permission to "Webhook Notifications". If you are receiving a permission error, please contact TNS. API Keys can be found in the Account Management > API Keys section of the TNS Payment Orchestration Portal Click on “Test" 2 Configure a Webhook Endpoint In the Merchant Portal, navigate to your merchant account and select the “Webhooks” tab. You can configure up to 5 active webhook endpoints per merchant. Click Add Endpoint and provide the following information: Title Description Field Description URL Your HTTPS endpoint that will receive notifications. Must use Display Name A friendly name for this endpoint (e.g. "Production Order Processor"). This allows you to recognise why the webhook event was created. API Key Select one of your API keys with webhook access. This key is used to sign deliveries. Event Categories Choose which events to receive: approved, declined, or both. 3 Implement Your Endpoint Your endpoint must: Accept HTTP POST requests with a JSON body Respond with an HTTP 2xx status code within 15 seconds to acknowledge receipt Be accessible via HTTPS (HTTP URLs are rejected) 4 Test Connectivity & Receive a Test Notification After saving your webhook, you can perform a connectivity and sample webhook test. Identify the webhook you want to test Click the accordion menu Click on "Test" If successful, you will receive the webhook notification on your server. If failed, you will receive a failure toast message. Successful : Failure :
  • [Webhook Format](https://developer.pay.tnsi.com/api/supporting-apis/webhook-notifications/webhook-format.md): Event Categories The event category that you subscribed for within the Webhook Merchant Portal setup. Title Description Category Triggered When approved Transaction status is APPROVED declined Transaction status is anything other than APPROVED (HOST_DECLINED, INVALID etc) Each event also includes the transaction action (SALE, AUTHORIZATION, CAPTURE, REFUND, VOID, REVERSAL etc) so you can distinguish event types within each category. Event Payload Format Each webhook delivery is an HTTP POST with a JSON body: JSON { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "approved", "created": "2024-11-14T22:13:20Z", "merchantId": "M10000000000001", "data": { "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "action": "SALE", "status": "APPROVED", "isApproved": true, "amount": 1500, "currency": "USD", "cardType": "VISA", "firstSix": "411111", "lastFour": "1111", "responseCode": "00", "responseText": "Approved", "authCode": "ABC123", "originalTransactionId": null, "clientReference": "ORDER-12345", "receiptNumber": "RN000001" } } Payload Fields Title Description Title Field Type Description id string (UUID) Unique event identifier. Use this for idempotency. type string Event category: approved or declined created string (ISO 8601) Timestamp of the event merchantId string Your TNS merchant identifier. Note - this will be different to your Acquirers Bank Merchant ID. data.transactionId string (UUID) The transaction identifier data.action string Transaction action: SALE, AUTHORIZATION, CAPTURE, LINKED_REFUND, VOID data.status string Transaction status: APPROVED, HOST_DECLINED, INVALID, SUSPECT data.isApproved boolean Whether the transaction was approved. TRUE,FALSE data.amount integer Amount in minor currency units (e.g. 1500 = $15.00) data.currency string ISO 4217 currency code (e.g. EUR, USD, GBP) data.cardType string Card scheme: VISA, MASTERCARD, AMEX, etc. data.firstSix string First 6 digits of the card number data.lastFour string Last 4 digits of the card number data.responseCode string TNS platform response code data.responseText string Human-readable response description data.authCode string Authorisation code (present when approved) data.originalTransactionId string Original transaction reference (for subsequent transactions such as refunds, voids, captures) data.clientReference string Your merchant-supplied reference data.receiptNumber string TNS receipt number
  • [Verify Signature](https://developer.pay.tnsi.com/api/supporting-apis/webhook-notifications/verify-signature.md): Every webhook delivery includes three HTTP headers for signature verification: Title Description Header Description hmac HMAC-SHA256 signature of the signing data apikey The API key identifier used for signing timestamp Unix epoch milliseconds at time of signing Verification Algorithm Extract the apikey, timestamp, and hmac headers from the request Read the raw request body (the JSON payload) Construct the signing data: {apikey}:{timestamp}:{body} Compute HMAC-SHA256 of the signing data using your API key's secret Compare your computed signature with the hmac header value Sample Code Java Java import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; public boolean verifyWebhook(String apiKey, String timestamp, String hmacHeader, String body, String secret) { String signingData = apiKey + ":" + timestamp + ":" + body; Mac mac = Mac.getInstance("HmacSHA256"); SecretKeySpec keySpec = new SecretKeySpec( secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); mac.init(keySpec); byte[] hash = mac.doFinal(signingData.getBytes(StandardCharsets.UTF_8)); String computed = bytesToHex(hash); return computed.equalsIgnoreCase(hmacHeader); } Python Python import hmac import hashlib def verify_webhook(api_key: str, timestamp: str, hmac_header: str, body: str, secret: str) -> bool: signing_data = f"{api_key}:{timestamp}:{body}" computed = hmac.new( secret.encode('utf-8'), signing_data.encode('utf-8'), hashlib.sha256 ).hexdigest() return hmac.compare_digest(computed.lower(), hmac_header.lower()) Node.js Plain text const crypto = require('crypto'); function verifyWebhook(apiKey, timestamp, hmacHeader, body, secret) { const signingData = `${apiKey}:${timestamp}:${body}`; const computed = crypto .createHmac('sha256', secret) .update(signingData) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(computed, 'hex'), Buffer.from(hmacHeader, 'hex') ); } const crypto = require('crypto'); function verifyWebhook(apiKey, timestamp, hmacHeader, body, secret) { const signingData = `${apiKey}:${timestamp}:${body}`; const computed = crypto .createHmac('sha256', secret) .update(signingData) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(computed, 'hex'), Buffer.from(hmacHeader, 'hex') ); } Replay Protection To guard against replay attacks, verify that the timestamp header is within an acceptable window (e.g. 5 minutes) of your server's current time: Plain text long receivedTimestamp = Long.parseLong(timestampHeader); long now = System.currentTimeMillis(); if (Math.abs(now - receivedTimestamp) > 300_000) { // 5 minutes // Reject — potential replay attack } long receivedTimestamp = Long.parseLong(timestampHeader); long now = System.currentTimeMillis(); if (Math.abs(now - receivedTimestamp) > 300_000) { // 5 minutes // Reject — potential replay attack } Retry Behaviour If your endpoint fails to respond with a 2xx status within 15 seconds, the platform retries delivery with exponential backoff: Title Description Attempt Delay After Failure 1st retry 1 minute 2nd retry 5 minutes 3rd retry 30 minutes 4th retry 2 hours 5th retry 8 hours 6th retry 24 hours After all 6 retries are exhausted, the delivery is marked as permanently failed. Automatic Endpoint Disabling If 5 consecutive events all permanently fail delivery (all retries exhausted for each), the endpoint is automatically disabled. You will need to re-enable it manually in the Merchant Portal after resolving the issue. When you re-enable a disabled endpoint, delivery resumes for new events only — events that occurred while the endpoint was disabled are not retroactively delivered.
  • [Best Practices](https://developer.pay.tnsi.com/api/supporting-apis/webhook-notifications/best-practices.md): Every webhook delivery includes three HTTP headers for signature verification: Title Description Header Description hmac HMAC-SHA256 signature of the signing data apikey The API key identifier used for signing timestamp Unix epoch milliseconds at time of signing Verification Algorithm Extract the apikey, timestamp, and hmac headers from the request Read the raw request body (the JSON payload) Construct the signing data: {apikey}:{timestamp}:{body} Compute HMAC-SHA256 of the signing data using your API key's secret Compare your computed signature with the hmac header value Sample Code Java Java Python Python import hmac import hashlib def verify_webhook(api_key: str, timestamp: str, hmac_header: str, body: str, secret: str) -> bool: signing_data = f"{api_key}:{timestamp}:{body}" computed = hmac.new( secret.encode('utf-8'), signing_data.encode('utf-8'), hashlib.sha256 ).hexdigest() return hmac.compare_digest(computed.lower(), hmac_header.lower()) Node.js Plain text const crypto = require('crypto'); function verifyWebhook(apiKey, timestamp, hmacHeader, body, secret) { const signingData = `${apiKey}:${timestamp}:${body}`; const computed = crypto .createHmac('sha256', secret) .update(signingData) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(computed, 'hex'), Buffer.from(hmacHeader, 'hex') ); } const crypto = require('crypto'); function verifyWebhook(apiKey, timestamp, hmacHeader, body, secret) { const signingData = `${apiKey}:${timestamp}:${body}`; const computed = crypto .createHmac('sha256', secret) .update(signingData) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(computed, 'hex'), Buffer.from(hmacHeader, 'hex') ); } Replay Protection To guard against replay attacks, verify that the timestamp header is within an acceptable window (e.g. 5 minutes) of your server's current time: Plain text long receivedTimestamp = Long.parseLong(timestampHeader); long now = System.currentTimeMillis(); if (Math.abs(now - receivedTimestamp) > 300_000) { // 5 minutes // Reject — potential replay attack } long receivedTimestamp = Long.parseLong(timestampHeader); long now = System.currentTimeMillis(); if (Math.abs(now - receivedTimestamp) > 300_000) { // 5 minutes // Reject — potential replay attack } Retry Behaviour If your endpoint fails to respond with a 2xx status within 15 seconds, the platform retries delivery with exponential backoff: Title Description Attempt Delay After Failure 1st retry 1 minute 2nd retry 5 minutes 3rd retry 30 minutes 4th retry 2 hours 5th retry 8 hours 6th retry 24 hours After all 6 retries are exhausted, the delivery is marked as permanently failed. Automatic Endpoint Disabling If 5 consecutive events all permanently fail delivery (all retries exhausted for each), the endpoint is automatically disabled. You will need to re-enable it manually in the Merchant Portal after resolving the issue. When you re-enable a disabled endpoint, delivery resumes for new events only — events that occurred while the endpoint was disabled are not retroactively delivered.
• [Transaction Details](https://developer.pay.tnsi.com/api/supporting-apis/reporting-api-home/transaction-details.md)
• [Transaction List](https://developer.pay.tnsi.com/api/supporting-apis/reporting-api-home/transaction-list.md): Search transaction(searchTransaction) API provides a detailed compilation of all transactions based on specific filter criteria. Please refer to the sample request format section for a list of available fields as search criteria. The transaction list allows you to generate detailed reports on all transactions processed through all or any specific merchant account. This list of transactions provides comprehensive insights into your transaction history, helping you monitor activity, generate relevant reports, detect trends, and make informed business decisions. By utilizing various filters, you can customize the reports to focus on the data most relevant to your needs. All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
• [Transactions using Blacklisted Cards](https://developer.pay.tnsi.com/api/supporting-apis/reporting-api-home/transactions-using-blacklisted-cards.md): A blacklist report offers a detailed list of all transactions attempted using a blacklisted credit card by the merchant or at a higher level. The TNS system records all transaction information involving a blacklisted credit card for subsequent actions. All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
• [Transaction History Details](https://developer.pay.tnsi.com/api/supporting-apis/reporting-api-home/transaction-history-details.md): Transaction history, alongside transaction details, provides a comprehensive list of dependent transactions, offering a complete overview of related transactions. For example, when you search the history of a preauthorized transaction, you will receive a detailed list of all transactions conducted in relation to this preauthorized transaction. For a list of all the details sent back in the response please see the sample response section in this document. All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
• [Transaction Summary Data](https://developer.pay.tnsi.com/api/supporting-apis/reporting-api-home/transaction-summary-data.md): The summary report allows you to generate merchant-wise summary reports that provide an overview of your transactions over a specified period. These reports help you analyze overall transaction trends and performance, making it easier to track and manage your business activities. All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
• [Settlement Data](https://developer.pay.tnsi.com/api/supporting-apis/reporting-api-home/settlement-data.md): Settlement report API offers a comprehensive overview of the total transaction amounts and counts involved in the Settlement process, which is executed by the Settlement Engine. Please consult the sample request format section for a detailed list of available fields that can be used as search criteria. The Settlement Report summary feature enables you to generate in-depth reports on all transactions processed by the settlement engine for either all merchant accounts or specific ones. This report provides detailed insights into the total transaction amount for each merchant, categorized by card type and transaction type. By applying various filters, you can tailor the reports to focus on the data that is most pertinent to your requirements. All REST API calls are authenticated using HMAC. See the Authentication Headers section to learn how to sign the payload using HMAC and the mandatory headers required for each request.
• [Request Format](https://developer.pay.tnsi.com/api/resources/request-format.md): Field Name Type Required(R), Optional(O), Conditional(C) Description stan string O 6 digit System Trace Audit Number clientTransactionId string R Client Unique Transaction Identifier. This is the unique identifier that you use to identify transaction in your system transactionDate string R This is the effective date of the transaction in UTC formatted as YYYYMMDDHHmmss. tenderType Enum values: CREDIT, DEBIT string R This allows you to specify whether this a credit or debit transaction. This is formatted as string and always in uppercase. paymentChannel Enum values: CREDITCARD, BATCHCREDIT, BPAY, BPOINT, DIRECTDEBIT, EFTPOS, EFTPOS, SWITCH, NOPAYMENTS, PAYPAL string R Specifies the channel a transaction originates. We support credit card request for now. orderInformation- The order information contains the transaction amount details and the customer details, including billing address for AVS validation. The Amount section is mandatory for all the transactions. amount object currencyCode string R This is the ISO 4217 currency code. Use "036" for Australian dollar, "840" for United States dollar, "826" for Pound sterling. Please refer https://en.wikipedia.org/wiki/ISO_4217 for list of all currency codes. transactionAmount string R This is the total amount of the transaction converted to the lowest unit of currency formatted as a string. Amount can not be negative. Send the amount without a decimal in it. e.g. $10.25 should be sent as 1025. surchargeAmount string O This is the additional amount that you add to the purchase amount. This amount is already included in the transaction amount. Amount can not be negative. Send the amount without a decimal in it. e.g. $1.22 should be sent as 122 paymentInformation object card object track2 string C Track2 data as read from the card's magnetic stripe by a mag-stripe reader or EMV reader (both contact and contactless reader). This value is mandatory when entry mode selected as EMV_CONTACT EMV_CONTACTLESS MAGSTRIPE MAGSTRIPE_FALLBACK accountNumber string C The customer's payment card number, also known as the Primary Account Number (PAN). The account number can be 14 to 19 digits long. This value is mandatory when entry mode selected as keyed expiryDate string C This is the expiration date of the credit card formatted as MMYY. This value is mandatory when account number is provided. entryMode Enum values: EMV_CONTACT, EMV_CONTACTLESS, KEYED, MAGSTRIPE, MAGSTRIPE_FALLBACK string C This defines on how the card data is presented at the point-of-sale(POS). This value is optional for secondary transactions. Usually the entry mode of the primary transaction is used in secondary transaction unless user wants to overwrite this. cvc string O Card Verification Code. This is the three or four-digit codes on the back of the payment card that are used to further authenticate the consumer during a card-not-present transaction. Use as CVV2 for Visa, CVC2 for Master Card, CVD for Discover and CID for Amex card cardName string O Name of the card holder as printed on the card. cardToken - object tokenValue string C This the token that was issued for the card data by TNS. This field is mandatory when a transaction is performed using token. emv emv string C EMV data. This field is mandatory when entry mode selected as EMV_CONTACT or EMV_CONTACTLESS isCardPresent string O This is to specify the physical card was present with card holder at the time of transaction origin. pin object pinBlock string C This is the encrypted cipher of PIN (Personal Identification Number) for the account formatted as base64 string. This field is mandatory for online pin transactions. ksn string C This is the KSN (Key Serial Number) used with the encryption key to encrypt the PIN. This field is mandatory for online pin transactions. originalTransaction - Original transaction group is required for follow-up transaction. Any of the available identification field is used to refer the original transaction stored in the TNS database originalTransactionId string C This is the transaction identifier of the primary transaction, as returned in the response of original primary transaction. This field is mandatory for secondary transactions like capture or void. originalTransactionAmount string O This is the total amount of the original transaction converted to the lowest unit of currency formatted as a string. Amount can not be negative. Send the amount without a decimal in it. e.g. $10.25 should be sent as 1025. originaleRef string C Equipment transaction reference of the original transaction received from the device. If originalTransactionId is not available this is required fields for secondary transactions. originaltRef string C Terminal transaction reference of the original transaction received from the device.. If originalTransactionId is not available this is required fields for secondary transactions. originaleAuth String O This is the External Auth of the original transaction received from the device. If originalTransactionId is not available this is required fields for secondary transactions. merchant - Merchant related information should be provided under this section id string R TNS Merchant id associated with merchant account. countryCd srting O This is the ISO 3166-2 country code. Use “036” for Australia, “840” for United States, “826” for United Kingdom. Please refer https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes for list of all country codes. pos terminalId string C Identifier provided by TNS for the terminal at your retail location. This is required fields for primary transactions. eRef string C Equipment transaction reference as provided by Paystation / Kiosk. This is required fields for primary transactions. tRef string C Terminal transaction reference. This is required fields for primary transactions. eAuth String O This is the External Auth generated using terminal no. and epoch since 1/1/2016. 12 digits only. This is required fields for primary transactions. terminalTxnData string C Terminal-related information, separated by semicolon. Details of terminalTxnData Field Name Type Required(R), Optional(O), Conditional(C) Description posEntryMode Enum values: 011 Payment card data is entered manually and Terminal has PIN entry capability 021 Payment card is swiped using magnetic stripe and Terminal has PIN entry capability 051 Payment card is inserted into the Chip reader slot and Terminal has PIN entry capability 071 Payment card is tapped on the terminal and Terminal has PIN entry capability 801 erminal is unable to read the chip in the payment card, so falling back to Swipe or Manual option and Terminal has PIN entry capability 911 Payment card is tapped on the terminal and only track data is received instead of EMV cryptogram and Terminal has PIN entry capability 012 Payment card data is entered manually and Terminal has NO PIN entry capability 022 Payment card is swiped using magnetic stripe and Terminal has NO PIN entry capability 052 Payment card is inserted into the Chip reader slot and Terminal has NO PIN entry capability 072 Payment card is tapped on the terminal and Terminal has NO PIN entry capability 802 Terminal is unable to read the chip in the payment card, so falling back to Swipe or Manual option and Terminal has NO PIN entry capability 912 Payment card is tapped on the terminal and only track data is received instead of EMV cryptogram and Terminal has NO PIN entry capability string O This field indicates the POS entry mode used by the terminal for this transaction. It is a three-digit value formatted as a string. The first two digits describe how the card data is entered into the terminal, and the last digit indicates the terminal's capability for PIN entry. offlineAuthType Enum values: EMV0 EMV Chip approved FBK0 Chip decision override FBKE Electronic fallback string O This field indicates the Offline Authorization type, which is mandatory for offline sale or completion transactions. cvmUsed Enum values: 00 None 01 NoCVM 02 Offline PIN 03 On Device CVM string O This field indicates the CVM (Cardholder Verification Method) used on the terminal. reasonCode Enum values: 01 Terminal not able to process IC 02 Realtime forced by terminal 03 Over floor limit 04 Terminal random selection 05 Realtime forced by IC 06 Realtime forced by card acceptor 07 Realtime forced by card issuer 08 IC processed 1st Gen TC 09 IC Processed 2nd Gen TC 10 Terminal processed CDO 11 Terminal processed EFB 12 Magstripe online 13 Magstripe offline string O This field indicates whether the terminal 'did' or 'did not' contact the acquirer in realtime. advamEquipmentId string O This is the identifier of the ADVAM equipment (Pay station or Kiosk). equipmentReference string O This is the reference of the merchant equipment. tcCvm Enum values: 1 NoCVM 2 Offline PIN and NoCVM string O This field indicates the CVM capability of the terminal. tcPinpad Enum values: Y The terminal has a PIN pad N The terminal does not have a PIN pad string O This field indicates whether the point of sale terminal has a PIN pad. 'N' indicates that a pinpad is not available, and 'Y' indicates that a pinpad is available. mcr Enum values: 1 MCR is enabled 0 MCR is disabled string O This field indicates whether Merchant Choice Routing is enabled or disabled. This field is used if the terminal has decided to process the transaction with least cost routing through a multi debit network card.
• [Response Format](https://developer.pay.tnsi.com/api/resources/response-format.md): Field Name Type Description authorizedDate string ISO 8601 timestamp indicating when the transaction was authorized. transactionId string Unique identifier generated by TNS for the transaction. stan string System Trace Audit Number (STAN) used for tracking transactions. clientTransactionId string Unique identifier provided by the client for the transaction. transactionDate string Date of the original transaction request. tenderType string Type of tender used, e.g., CREDIT, DEBIT, etc. tnsResponseCode string Response code returned by TNS (e.g., 00 for approved). tnsResponseText string Description of the response code from TNS. hostResponseCode string Response code received from the host/network. hostResponseText string Textual description of the host response. networkId string Identifier for the card network. settlementDate string Date the transaction is scheduled to be settled. x_request_id string Correlation ID for request tracking across systems. amount.approvedAmount string Approved amount in minor units (e.g., cents). amount.currencyCode string ISO 4217 currency code (e.g., 840 for USD). card.accountFirst6 string First 6 digits of the card number (BIN). card.accountLast4 string Last 4 digits of the card number. card.emv.emv string Encoded EMV data returned after chip read. card.hostNetwork string Card brand or network (e.g., Visa, MasterCard). card.expiryMonth string Card expiry month in MM format. card.expiryYear string Card expiry year in YYYY format. avs.avsResult string Address Verification Service result code. receiptData string Encoded string used for receipt generation. responseSource string Indicates source of final decision (e.g., TRANSACTION_APPROVED). authCode string Authorization code returned by the issuer. token string Tokenized representation of the card used.
• [Response Codes](https://developer.pay.tnsi.com/api/resources/response-codes.md): TNS standardises response codes from upsteam hosts. They are normalised, host-independent view of a transaction outcome. Column meanings: tnsResponseCode - the tnsResponseCode value returned to clients. tnsResponseText - the human-readable text returned alongside the code Description - what the code means in practice and the expected client behaviour. Action - A Codes are grouped by prefix and sorted within each group: Approval Declines Host-categorised declines (mapped from the acquirer/issuer decline codes) Fuel / Fleet-specific Declines HTTP Response Codes: It's important to note that HTTP status code and Response Codes answer two different questions: The HTTP status describes whether the API call itself was accepted and processed The TNS Response Codes describes the outcome of the payment itself, and is carried inside the response body. A declined card is a perfectly successful API call. It returns HTTP 200 with a decline code in the body. The HTTP layer is not used to signal decline. Approval Title Description Description tnsResponseCode tnsResponseText Description 00 Approved Transaction was fully approved by the issuer. Complete the sale. H08 Approved - honor with identification Approved on condition the cardholder's identity is verified. Complete the sale after checking ID. H10 Partial approval The issuer approved only part of the requested amount. Collect the remainder via another tender or reverse. General Response Codes The below response codes are generated where the transaction is declined prior to going to the upstream host. Title Description Title tnsResponseCode tnsResponseText Description G03 Invalid merchant configuration The merchant/terminal is not configured correctly at the gateway (e.g. missing acquirer setup). Not retryable by the cardholder; requires operational/config fix. G04 Card blacklisted The card is on the gateway blacklist and was blocked before reaching the host. Do not retry with the same card. G12 Invalid transaction data The request reached the gateway but contained data that is invalid for the transaction type. Fix the request before retrying. G13 Currency mismatch The transaction currency does not match what the merchant/terminal is permitted to process. Correct the currency and retry. G25 Reversal not required A reversal was requested but is unnecessary because the original was not found or was not approved. Treat as handled; no further action needed. G26 Original transaction not found The referenced original transaction (for capture/refund/reversal) could not be located. Check the reference before retrying. G30 Invalid request format The request was malformed and could not be parsed/validated by the gateway. Fix the request structure and retry. G31 Invalid host response The host replied but the response could not be interpreted by the gateway. Outcome uncertain; treat as a host-side failure. G40 Transaction not supported The requested transaction type/function is not supported for this configuration. Do not retry as-is. G57 Authorization failed Gateway-level authorization checks failed for the request. Not approved; review request/permission. G58 Operation not allowed The operation is not permitted for this terminal/merchant. Not retryable without a config change. G68 Host read timeout Payorch connected but did not receive the host response in time. Outcome unknown; a reversal may be triggered. Do not assume approval. G91 Host connection timeout The gateway could not establish a connection to the host. Transaction did not complete; safe to retry later. G94 Duplicate advice already processed This advice message duplicates one already processed. No further action; the original outcome stands G95 Duplicate transaction A transaction with the same key was already submitted. Do not resubmit; look up the original result. G96 Host response error The host returned an error condition the gateway classified as a system/host error. Outcome uncertain; treat as failed. G97 Gateway processing error An internal error occurred in the gateway while processing. Transaction not completed; retry may be possible after investigation. G99 Smart routing block Smart routing rules blocked the transaction before it was sent to a host. Not approved; governed by routing configuration. Host Response Codes (Hxx) The below standardized response codes are mapped from an upsteam host into the below format. Title Description Description tnsResponseCode tnsResponseText Description H01 Refer to card issuer - call issuer The issuer declined and asked the merchant to contact them for authorization. Do not simply retry; follow the call-issuer process. H04 Capture card - pick up The issuer declined and instructed the terminal to retain the card. Do not return the card; do not retry. H05 Host declined Generic issuer decline (do not honour) with no more specific reason. Not approved; a different card may be needed. H08 Approved - honor with identification Approved on condition the cardholder's identity is verified. Complete the sale after checking ID. H10 Partial approval The issuer approved only part of the requested amount. Collect the remainder via another tender or reverse. H30 Host invalid request The host rejected the request as malformed/invalid. Not approved; correct the request. H41 Lost card - pick up Card reported lost; issuer instructed pickup. Retain the card; do not retry. H43 Stolen card - pick up Card reported stolen; issuer instructed pickup. Retain the card; do not retry. H51 Insufficient funds Declined because the account lacks available funds. Suggest another card/tender; retry may succeed later. H54 Expired card Declined because the card has expired. Request a valid card. H55 Incorrect PIN The PIN entered was wrong. Prompt the cardholder to re-enter the PIN and retry. H56 PIN change required The issuer requires the cardholder to change their PIN before transacting. H57 Transaction not permitted to cardholder The issuer does not permit this transaction type for this cardholder. Not approved; try a different transaction/card. H59 Suspected fraud The issuer flagged suspected fraud; the gateway auto-reverses. Do not retry with the same card. H61 Exceeds withdrawal limit Declined for exceeding the permitted amount/withdrawal limit. Retry with a lower amount or another card. H63 Security violation The issuer declined for a security-rule violation; the gateway auto-reverses. Not approved. H65 Fallback required Additional authentication is required. Depending on client capability, retry with chip, PIN, CVV, or 3DS. H66 PIN required A PIN is required to complete this transaction. Prompt for PIN and retry. H68 Host suspect The host response arrived too late, so the final state is uncertain. Do not assume approval; reconcile before retrying. H75 PIN tries exceeded The allowed number of PIN attempts was exceeded; may warrant card pickup. Do not keep retrying the PIN. H91 Issuer unavailable The issuer or switch was unreachable/inoperative. Transaction not completed; safe to retry later. H96 Host error The host reported a system malfunction. Outcome uncertain; treat as failed and retry later Fuel / fleet codes (Fxx) Specific response codes for Fleet/Fuel Merchants. Title Description Title Description Code tnsResponseText Description Action F01 Invalid vehicle Declined because the vehicle identifier supplied is not valid for the fleet card. HOST_DECLINED F02 Invalid driver Declined because the driver identifier supplied is not valid for the fleet card. HOST_DECLINED F03 Invalid product Declined because the fuel/merchandise product is not permitted on this card. HOST_DECLINED F04 Exceeds transaction total limit per product class Declined because the transaction total exceeds the limit for that product class. HOST_DECLINED F05 Over daily limit Declined because the card's daily spend/usage limit has been exceeded. HOST_DECLINED F06 Invalid date or time Declined because the transaction date/time is outside the card's permitted window. HOST_DECLINED F07 Exceeds quantity Declined because the requested quantity exceeds the card's permitted amount. HOST_DECLINED F08 Invalid prompt entry Declined because a fuel-site prompt (e.g. odometer, ID) was answered with invalid data. HOST_DECLINED F09 Invalid track 2 data Declined because the card's track 2 data is invalid or unreadable. HOST_DECLINED F10 Voyager ID problem Declined due to a problem with the Voyager fleet card identification. HOST_DECLINED F11 Invalid odometer Declined because the odometer reading entered is invalid. HOST_DECLINED F12 Invalid restriction code Declined because a card restriction code prevents this purchase. HOST_DECLINED F13 Pay at pump not allowed Declined because the card is not permitted to pay at the pump; go inside to pay. HOST_DECLINED F14 Over fuel limit Declined because the fuel amount exceeds the card's fuel limit. HOST_DECLINED F15 Over cash limit Declined because the cash portion exceeds the card's cash limit. HOST_DECLINED F16 Fuel price error Declined due to a fuel price error/mismatch at the site. HOST_DECLINED F17 Over repair limit Declined because the repair/service amount exceeds the card's limit. HOST_DECLINED F18 Over additive limit Declined because the additive amount exceeds the card's limit. HOST_DECLINED F19 Invalid user Declined because the user identifier supplied is not valid for the card. HOST_DECLINED F20 Driver's License or ID is Required Declined because a driver's licence or ID must be supplied to proceed. HOST_DECLINED F21 Fuel only Declined for non-fuel items; the card is restricted to fuel purchases only. HOST_DECLINED F22 Received prompts do not match expected values Declined because the site prompt responses did not match the values the card expected. HOST_DECLINED F23 Extended prompting required Declined because additional (extended) prompts must be completed before approval. HOST_DECLINED
• [Transaction Management](https://developer.pay.tnsi.com/api/resources/transaction-management.md): Our PayOrch platform gives all the APIs to control the status of your transactions throughout its lifecycle allowing you to capture, adjust or cancel (void or reverse) transactions quickly and easily from your application. In the transaction lifecycle, the transactions authorization or sale is for goods purchased and they are termed as primary transactions. Step 1: Purchase To charge a customer for the goods or services purchased, you can charge the customer's card through authorization or sale transactions. Authorization : An authorization transaction is to get authorize the card with the cardholder's issuing bank and verify that the card is valid and there are enough funds in the cardholder's account to pay for the purchase. This step doesn't transfer the funds. To get the funds from the cardholder's account to the merchant's account, the approved transaction should be captured. The authorization transactions are usually used by merchants when the goods are delivered later after the purchase. Sale : A sale transaction can be explained as authorization and capture of funds at the same time. The sale transactions are usually used by merchants who deliver the goods almost immediately like retail stores where the customer receives the goods immediately. For primary transactions, the card must be presented at the point-of-sale(POS) or the card details should be entered into the online website or application during checkout. When the card is physically presented and read by a card reader, they are called card present transactions. When a card number is manually entered, it is termed as a card not present transaction. For more information on how a card is presented at the point of sale, please refer Entry Modes in API References. Title Sample card-present EMV chip insert transaction Run a sample Sale Transaction Plain text { "stan": "123456", "clientTransactionId": "12345678", "transactionDate": "20230501240000", "tenderType": "CREDIT", "paymentChannel": "CREDITCARD", "orderInformation": { "amount": { "currencyCode": "840", "transactionAmount": "1000" } }, "paymentInformation": { "card": { "isCardPresent": true, "entryMode": "EMV", "track1": "B4000340000000506^John/Doe ^10251110000123000", "emv": { "emv": "XyQDJwkwXyoCBFhfNAEBggIJAIQHoAAABhUAAZUFAAAAgACaAyMRFpwBAJ8CBgAAAAASMJ8DBgAAAAAAAJ8IAgABnwkCAAGfECAPpQGoAPgAAAAAAAAAAAAADwAREREREREREREREREREZ8aAgRYnyYIwjhO1PMNLi6fJwGAnzMD4PjInzQDPwAAnzUBIp82Agk5nzcEmwcA0g\u003d\u003d" } } }, "merchant": { "id": "M1002", "countryCd": "840" }, "pos": { "terminalId": "TID100012" } } Step 2: Follow-Up Transactions Once merchant delivers the goods or services purchased, to realize the funds into merchant's bank, the approved authorizations has to be captured using capture transaction. Or when the customer cancels the order or returns the good, the merchant can cancel the approved primary transaction in its entirety or refund only partial funds using void or reversal or refund. All such transactions are made on a primary transaction, they are termed as secondary transactions or we can call it as follow-up transactions. For secondary transactions, the card need not be presented at the point-of-sale(POS) or to the merchant. We are running additional transactions based on an approved primary transaction. PayOrch platform provides simple APIs to perform secondary transactions. PayOrch platform returns a transaction identifier in the response of primary transaction. That transaction identifier is the important data used to run secondary or follow-up transactions. In a case where the transaction identifier of the primary transaction is lost, there are other parameters that can used to run the secondary transactions. Please refer API reference for more details. All secondary transactions use the same request format. Title Sample payload for a secondary transaction to Void the sale Run a sample Void Transaction Plain text { "clientTransactionId": "12345678", "transactionDate": "20240401240000", "orderInformation": { "amount": { "currencyCode": "840", "transactionAmount": "900" } }, "originalTransaction": { "originalTransactionId": "0784fe39-2b54-4f9b-bb5c-71d9f262dbe7", "originalTransactionAmount": "1000", "originaleRef": "", "originaltRef": "", "originaleAuth": "" } "merchant": { "id": "M1002" } } Step 3: Settlement Settlement is a process of finalizing all the transactions for the merchant and send it to the acquirer for consolidation and initiate the funds transfer. All settlements are scheduled and automatically run by PayOrch platform.
• [Payment Methods](https://developer.pay.tnsi.com/api/resources/payment-methods.md): Payment methods refer to the various ways customers can pay for goods and services. These methods can vary depending on factors such as location, technological advancements, and consumer preferences. Here are some common payment methods: Credit Cards : Credit cards allow customers to make purchases by borrowing funds from a credit card issuer, up to a predetermined credit limit. Credit cards offer convenience, security features, and the ability to make purchases online and in-person Debit Cards : Debit cards deduct funds directly from the cardholder's bank account when used for purchases. Debit cards are widely accepted and offer similar conveniences to credit cards, but transactions are limited by the available funds in the linked account Mobile Payments : Mobile payment methods, such as Apple Pay, Google Pay and other digital wallets, enable customers to make payments using their smartphones or wearable devices. These methods typically use Near Field Communication (NFC) technology for contactless transactions Online Payment Platforms : Online payment platforms, such as PayPal, Venmo, and Square Cash, allow customers to transfer funds electronically and make purchases online or through mobile apps. These platforms often offer additional features such as peer-to-peer payments, bill splitting, and integration with ecommerce websites Digital Wallet Payment Methods The transactions can be made using electronic wallet payments that securely store the payment card information either in a electronic device or in the cloud. These digital wallets enable users to make purchases online, in-app, or in-person without having to manually enter payment card details each time. ApplePay : It allows users to make payments using their compatible Apple devices, such as iPhones, iPads, Apple watches, and Mac computers. Apple Pay securely stores users' credit card, debit card, and other payment card information, allowing for convenient and secure transactions both in-store and online GooglePay : It allows users to make payments using their compatible Android devices, such as smartphones and smartwatches. Google Pay securely stores users' credit card, debit card, and other payment card information, enabling convenient and secure transactions both in-store and online
• [Entry Modes](https://developer.pay.tnsi.com/api/resources/entry-modes.md): Entry modes is a term that defines how payment card data is presented by the customer at the time of checkout (at point-of-sale(POS) machines or on an ecommerce website) and submitted for processing a transaction. The entry modes are classified based on the card presented at the point-of-sale (transaction origin). Following is the list of entry modes supported in the TNS PayOrch platform Title Description Card Present Card Not Present EMV Chip : entryMode : EMV_CONTACT EMV (Europay, Mastercard, and Visa) chip cards have a small microchip embedded in them. Instead of swiping, the card is inserted into the terminal's chip reader or tapped on a contactless-enabled terminal. This method provides greater security than magnetic stripe transactions due to dynamic authentication. Try a sample transaction → Contactless (NFC) : entryMode : EMV_ CONTACTLESS This method allows for payments to be made by tapping or waving a contactless-enabled credit card or mobile device (such as a smartphone or smartwatch) near a compatible POS terminal. Near Field Communication (NFC) technology facilitates communication between the card or device and the terminal. Try a sample transaction → Magnetic Stripe : entryMode : MAGSTRIPE Traditionally, credit card transactions were swiped through a magnetic stripe reader on the POS terminal. The magnetic stripe on the back of the card contains encoded information about the cardholder's account. Try a sample transaction → Manual Entry : entryMode : KEYED In cases where the card cannot be swiped or inserted, such as for card-not-present transactions (e.g., online or over the phone), the card details (card number, expiration date, CVV/CVC) can be manually entered into the POS terminal or in the checkout page of the Ecommerce platform. Try a sample transaction → Tokenization : entryMode : KEYED This method replaces sensitive card data (such as the card number) with a unique token. Tokenization enhances security by preventing the exposure of sensitive data during transactions. Tokenization can be used in combination with other entry modes, such as EMV chip or contactless payments. Try a sample transaction → Note : KEYED entry mode could be a card presented at the point-of-sale(POS), but manually entered through the number pad/keyboard. But still, such transactions are always considered as card not present because there is no possible evidence that could be given that the card was actually presented at the point-of-sale(POS).
• [Test Cards](https://developer.pay.tnsi.com/api/resources/test-cards.md): VISA Title Card Number: 4111 1111 1111 1111 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 4012 8888 8888 1881 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 4222 2222 2222 2222 Expiration Date: Any future date CVV: Any 3-digit number MASTERCARD Title Card Number: 5555 5555 5555 4444 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 5105 1051 0510 5100 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 5432 1234 5678 9876 Expiration Date: Any future date CVV: Any 3-digit number AMERICAN EXPRESS Title Card Number: 3782 822463 10005 Expiration Date: Any future date CID (Card Identification Number): Any 4-digit number Card Number: 3714 496353 98431 Expiration Date: Any future date CID (Card Identification Number): Any 4-digit number Card Number: 3411 726629 87061 Expiration Date: Any future date CID (Card Identification Number): Any 4-digit number DISCOVER Title Card Number: 6011 0000 0000 0004 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 6011 1111 1111 1117 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 6011 0000 0000 0009 Expiration Date: Any future date CVV: Any 3-digit number DINERS CLUB Title Card Number: 3056 9309 0259 04 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 3600 6666 3333 44 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 3852 0000 0232 37 Expiration Date: Any future date CVV: Any 3-digit number JCB Title Card Number: 3530 1113 3330 0000 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 3566 0020 2036 0505 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 3530 1113 3330 0000 Expiration Date: Any future date CVV: Any 3-digit number UNION PAY Title Card Number: 6250 9460 0000 0016 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 6250 9470 0000 0014 Expiration Date: Any future date CVV: Any 3-digit number Card Number: 6222 8212 3456 0017 Expiration Date: Any future date CVV: Any 3-digit number