TNS Payments Developer Portal

## Sections
• [Home](https://developer.pay.tnsi.com/terminal-api/supported-libraries.md): Terminal Solution TNS Terminal Solutions provides a fast, secure, and reliable method for businesses to accept card payments through Attended and Unattended devices. The deployment of our system is remarkably straightforward, with user-friendly operation, and our web-based merchant portal provides data accessibility from any location. You have the flexibility to select one or more terminals from our range of available, pre-configured terminals based on your specific requirements. Why TNS? Bring your existing POS terminal Keep the payment terminal you&apos;re already using and leverage our Payment Orchestration platform to integrate and process your transactions, securely. Simple integration - Our card readers and terminals easily integrate with your existing equipment, eliminating the need to build, add and maintain complex connections. Managed security - Help reduce your regulatory burden and fraud risk with a secure, global solution. We make sure you adopt the latest compliance standards – including PCI DSS, PCI P2PE, PCI PIN. Accept payments with any payment method - Your customers want to pay in the way that&apos;s easiest for them. With TNS, they can. Real-time visibility - Centralize your in person payments, transactions, payments data and insights in a single dashboard. Supported Terminals Choose from a range of pre-certified, plug-and-play terminals that easily install on your machines or equipment. Or, bring your own. All terminals must be EMV (Europay, Mastercard, and Visa) L1 and L2 certified and must be listed with PCI Security Standards Council to ensure a smooth and secure payment process, thereby bolstering customer confidence. By integrating EMV-certified POS terminals, merchants can protect their business operations, adhere to industry regulations, and deliver a secure and efficient payment service to their clientele. TNS-provided terminals come pre-certified, significantly reducing the risk of fraud. Each transaction generates a unique code, rendering it extremely challenging for fraudsters to replicate card details. You have the flexibility to choose either option based on your technical requirements and existing infrastructure, enabling smooth payment acceptance across your current devices. Integration Options BYO App SDK: This integration method empowers developers to embed our payment orchestration capabilities directly into their own applications (e.g., mobile, web, desktop). Our comprehensive SDK simplifies the development process, providing pre-built components and tools that accelerate integration and allow for a highly customized, native user experience within third-party applications. See SDK Integration Guide for more details. REST API: This contemporary interface facilitates seamless web-based integration, enabling your point-of-sale(POS) systems to directly communicate with our payment processing services through standard HTTP methods. It is an optimal choice for businesses seeking a versatile and easily customizable solution. See Terminal REST API section for more details. ISO 8583: This traditional interface standard is designed for systems that process card-based transactions. It guarantees compatibility and reliable communication among devices within financial networks, making it especially well-suited for intricate banking systems and well-established payment infrastructures. See ISO 8583 documentation for more details.
• [BYO Android App](https://developer.pay.tnsi.com/terminal-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&apos;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/terminal-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/terminal-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/terminal-api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/supported-terminals.md): The following terminals are supported by the TNS Terminal API PAX A920 Pro PAX Aries 8 PAX A80 PAX IM25 &amp; IM30 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&apos; display resolution
  • [TNSPay BYOA API Overview](https://developer.pay.tnsi.com/terminal-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/terminal-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&apos;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/terminal-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/terminal-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 &amp; 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/terminal-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/terminal-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, &quot;Invalid amount&quot;, Toast.LENGTH_SHORT).show() return } val parsedAmount = parseAmount(street) ?: run { Toast.makeText(this, &quot;Invalid amount&quot;, Toast.LENGTH_SHORT).show() return } Logging Plain text Log.d(&quot;SDK&quot;, &quot;Sending transaction: $request&quot;) Log.d(&quot;SDK&quot;, &quot;Sending transaction: $request&quot;) 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 &gt; 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/terminal-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 = &quot;USD&quot; private const val DEFAULT_INVOICE_NUMBER = &quot;10120304&quot; private const val DEFAULT_TXN_AMOUNT = &quot;15.00&quot; private const val DEFAULT_STAN_NUMBER = &quot;1&quot; private const val DEFAULT_AGREEMENT_ID = &quot;MERCH123_20250804_001&quot; private const val DEFAULT_AGREEMENT_TYPE = &quot;I&quot; private const val CURRENCY = &quot;USD&quot; private const val DEFAULT_INVOICE_NUMBER = &quot;10120304&quot; private const val DEFAULT_TXN_AMOUNT = &quot;15.00&quot; private const val DEFAULT_STAN_NUMBER = &quot;1&quot; private const val DEFAULT_AGREEMENT_ID = &quot;MERCH123_20250804_001&quot; private const val DEFAULT_AGREEMENT_TYPE = &quot;I&quot;
      • [Integration with AIDL](https://developer.pay.tnsi.com/terminal-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/terminal-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/terminal-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&apos;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&apos;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/terminal-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&apos;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/terminal-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&apos;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/terminal-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/terminal-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/terminal-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/terminal-api/card-present/tnspay-byoa-api-integration-guide/tnspay-byoa-api/sdk-overview/sdk-integration-guide/payment-requests/incremental-authorization.md): Incremental Authorization lets you increase the funds held on a customer&apos;s card after an initial Pre-Authorization - without needing to cancel and start over. It&apos;s perfect for situations where the final charge isn&apos;t known upfront. Here&apos;s how it works: The terminal performs the original Pre-Authorization to hold an initial amount from the cardholders credit card account. If you need more funds, send an Incremental Authorization referencing the original Approved Pre-Authroization. You can send multiple Incremental Authorizations if needed to increase the amount held (no more than 99 incremental authorizations) When the final amount is known, send a single Completion/Capture to charge referencing the original approved Pre-Authorization. Important: Please confirm with your TNS Account Manager if Incremental Authorization is supported with your chosen acquirer by TNS. The final capture amount should not exceed the total authorized amount (original Pre-Auth + any approved incremental authorizations). If an incremental authorization declines (e.g. Insufficient funds available from the cardholder), then you can only complete for the authorized amount. Incremental Authorizations should be performed as early as possible within the transaction lifecycle. In most cases, they need to be completed within 7 days, otherwise incurring risk of a chargeback. Please confirm with your acquirer the acceptable time limit on when the incremental authorization and final completion needs to be completed. An incremental authorization is not guaranteed to be approved. If it is declined, you can only process the final completion amount for the approved amount. Providing a product or service prior to the incremental authorization being approved is at your own risk. Common Use Cases Incremental Authorization is can be used in industries where the final bill isn&apos;t known at checkout: Parking - Session duration isn&apos;t known upfront EV charging - An initial pre-authorization may not cover the full charge of an EV car. As charing approaches the pre-authorization amount, you can then process an incremental authorization to allow the charging to continue. If the incremental authroization declines, you can stop charging and perform the final capture. Vending - Where an original Pre-Authorization is charged, but additional goods are requested. Card Network Support Visa Supported Globally where TNS has added support with your acquirer Mastercard Supported Globally where TNS has added support with your acquirer Amex Supported Globally where TNS has added support with your acquirer Discover/Diners Limited - Support (specific to certain industries and issuers) UnionPay Not Supported JCB Not Supported Local Debit Cards Not supported Multiple increments allowed - You can send more than one Incremental Authorization Single capture only - Only one Completion/Capture is performed at the end. This will show a single final amount on the cardholders online banking &amp; bank statements. Always reference the original - Both Incremental Authorizations and the Completion must include the original Pre-Auth transaction ID No over-capture - The final amount cannot exceed what&apos;s been authorized Integration Options 1 - Hybrid - Terminal &amp; Payment Orchestration REST API Best for: Merchants with a centralized system that manages charges across multiple terminals or locations Terminal performs the original Pre-Authorization and the equipment integration/POS sends this back to the merchants backend server. Merchants central server/cloud environment records those sends Incremental Authorization(s) directly to the Payment Orchestration REST API Merchants central server sends the final Completion via the REST API 2 - Terminal BYOA Only Merchants who want full control over authorization amounts and timing at the point of sale and do not have a centralized server Terminal performs the original Pre-Authorization Terminal sends one or more Incremental Authorizations as needed Terminal sends the final Completion for up to the approved amount 3 - Automatic (Payment Orchestration Handles It) Merchants who want a simpler integration with no additional message types to manage. Terminal performs the original Pre-Authorization Terminal sends the final Completion with the actual amount If the Completion amount exceeds the Pre-Auth, Payment Orchestration automatically generates an Incremental Authorization for the difference. If the Incremental Authroization is approved, the full completion will be processed. If the incremental authorization is declined, the completion will only be processed for the approved amount of prior incremental authoizations - resulting in a loss of funds for the merchant. If the auto-generated Incremental Authorization is declined by the card issuer, acquirer or TNS Payment Orchestration, this will result in Payment Orchestration only being able to complete the transaction for the originally approved Pre-Authorization amount — not the full requested completion amount. Sample Transactions Please refer to the below sample Payment Orchestration REST API Messages (Option 1) Incremental Authorization Transaction JSON { &quot;clientTransactionId&quot;: &quot;123415678&quot;, &quot;transactionDate&quot;: &quot;20261022122370&quot;, &quot;tenderType&quot;: &quot;CREDIT&quot;, &quot;paymentChannel&quot;: &quot;CREDITCARD&quot;, &quot;orderInformation&quot;: { &quot;amount&quot;: { &quot;currencyCode&quot;: &quot;036&quot;, &quot;transactionAmount&quot;: &quot;1000&quot; }, &quot;metadata&quot;: [ { &quot;name&quot;: &quot;exampleKey1&quot;, &quot;value&quot;: &quot;exampleValue1&quot; }, { &quot;name&quot;: &quot;exampleKey2&quot;, &quot;value&quot;: &quot;exampleValue2&quot; } ] }, &quot;paymentInformation&quot;: { &quot;storedCredentialAgreementType&quot;: &quot;INCREMENTAL&quot;, &quot;transactionInitiator&quot;: &quot;MERCHANT&quot;, }, &quot;originalTransaction&quot;: { &quot;originalTransactionId&quot;: &quot;341b4b1b-8164-4d0c-a4d5-77db2e5b33c6&quot; }, &quot;merchant&quot;: { &quot;id&quot;: &quot;M12000000000783&quot; } } Capture (Completion) Transaction JSON { &quot;clientTransactionId&quot;: &quot;123405678&quot;, &quot;transactionDate&quot;: &quot;20261022122340&quot;, &quot;tenderType&quot;: &quot;CREDIT&quot;, &quot;paymentChannel&quot;: &quot;CREDITCARD&quot;, &quot;agreementId&quot;: &quot;INC123&quot;, &quot;orderInformation&quot;: { &quot;amount&quot;: { &quot;currencyCode&quot;: &quot;036&quot;, &quot;transactionAmount&quot;: &quot;4500&quot; }, &quot;metadata&quot;: [ { &quot;name&quot;: &quot;exampleKey1&quot;, &quot;value&quot;: &quot;exampleValue1&quot; }, { &quot;name&quot;: &quot;exampleKey2&quot;, &quot;value&quot;: &quot;exampleValue2&quot; } ] }, &quot;originalTransaction&quot;: { &quot;originalTransactionId&quot;: &quot;341b4b1b-8164-4d0c-a4d5-77db2e5b33c6&quot; }, &quot;merchant&quot;: { &quot;id&quot;: &quot;M12000000000783&quot; } }
        • [Set Card Reader Mode](https://developer.pay.tnsi.com/terminal-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 &amp; 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/terminal-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 &apos;00&apos; 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/terminal-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/terminal-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/terminal-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 &quot;json_response&quot; 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/terminal-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 = &quot;USD&quot;, etc. ) sdk.sendRequestMessage(requestMsg) } onSaleClicked = { val requestMsg = RequestMsg( msgType = MsgType.SALE, amount = 50.00, currency = &quot;USD&quot;, etc. ) sdk.sendRequestMessage(requestMsg) } SDK Response: Plain text { &quot;status&quot;: &quot;approved&quot;, &quot;transactionId&quot;: &quot;TXN123&quot;, &quot;amount&quot;: 50.00 } { &quot;status&quot;: &quot;approved&quot;, &quot;transactionId&quot;: &quot;TXN123&quot;, &quot;amount&quot;: 50.00 }
      • [Releasing the SDK](https://developer.pay.tnsi.com/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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&apos;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/terminal-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 &amp; 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/terminal-api/card-present/point-of-sale/authorization-transactions.md): An authorization transaction is conducted to validate a card with the cardholder&apos;s issuing bank and confirm the card&apos;s validity and available funds. This process does not instantly transfer funds but temporarily reserves the funds in the cardholder&apos;s account if sufficient fund is available. To complete the transfer from the cardholder&apos;s account to the merchant&apos;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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-api/card-present/point-of-sale/authorization-transactions/authorization-using-fallback-to-swipe.md): If the card&apos;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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-api/card-present/point-of-sale/sale-transactions/sale-using-fallback-to-swipe.md): If the card&apos;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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-api/card-present/point-of-sale/refund-transactions/refund-using-fallback-to-swipe.md): If the card&apos;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/terminal-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&apos;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/terminal-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 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 &amp; 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/terminal-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 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 &amp; 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/terminal-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 &amp; 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/terminal-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 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 from the response. Use the transactionId as the originalTransactionId before proceeding with the transaction. 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/terminal-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/terminal-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/terminal-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/terminal-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 &apos;=&apos; 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/terminal-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/terminal-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 Fields by Message Type **Legend:** M = Mandatory, O = Optional, Number = Condition code --- ## 0100 - Authorisation Request (Pre-Auth) ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 2 | PAN | LLVAR n ..19 | 07 || 3 | Processing Code | n 6 | M || 4 | Transaction Amount | n 12 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M || 14 | Expiration Date | n 4 | 02 | ### Entry &amp; Identification | Field | Name | Format | Cond ||-------|------|--------|------|| 22 | POS Entry Mode | n 3 | M || 23 | Card Sequence Number | n 3 | O || 24 | Function Code | n 3 | M || 25 | POS Condition Code | n 2 | M || 35 | Track 2 Data | LLVAR Pz ..37 | 07 || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M | ### Context &amp; Security | Field | Name | Format | Cond ||-------|------|--------|------|| 48 | Transaction Context | LLLTLV v ..999 | M || 49 | Currency Code | n 3 | M || 52 | PIN Data | b 8 | 08 || 53 | DUKPT Key Numbers | b 30 | 10 || 55 | ICC Data | LLLVAR b ..999 | 05 || 60 | Security Data | LLLTLV v ..999 | M || 61 | Encrypted CHD | LLLTLV b ..999 | 07 || 62 | Cardholder Context | LLLTLV v ..999 | O || 64 | MAC | b 8 | 21 || 123 | Non-Payment PIN | LLLTLV v ..999 | 08 || 124 | Second Card Data | LLLTLV v ..999 | 22 || 128 | MAC (alt) | b 8 | 21 | --- ## 0110 - Authorisation Request Response ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 3 | Processing Code | n 6 | M || 4 | Transaction Amount | n 12 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M | ### Entry &amp; Response | Field | Name | Format | Cond ||-------|------|--------|------|| 22 | POS Entry Mode | n 3 | M || 23 | Card Sequence Number | n 3 | 16 || 24 | Function Code | n 3 | M || 25 | POS Condition Code | n 2 | M || 37 | Retrieval Ref Number | an 12 | 15 || 38 | Authorisation Code | anp 6 | O || 39 | Response Code | an 2 | M || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M | ### Context &amp; Security | Field | Name | Format | Cond ||-------|------|--------|------|| 48 | Transaction Context | LLLTLV v ..999 | 15 || 49 | Currency Code | n 3 | M || 53 | DUKPT Key Numbers | b 30 | 10 || 55 | ICC Data | LLLVAR b ..999 | O || 60 | Security Data | LLLTLV v ..999 | M || 63 | Transaction Advice | LLLTLV v ..999 | O || 64 | MAC | b 8 | 21 || 125 | Associated Account | LLLTLV v ..999 | O || 128 | MAC (alt) | b 8 | 21 | --- ## 0200 - Financial Request (Payment/Sale) ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 2 | PAN | LLVAR n ..19 | 07 || 3 | Processing Code | n 6 | M || 4 | Transaction Amount | n 12 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M || 14 | Expiration Date | n 4 | 02 | ### Entry &amp; Identification | Field | Name | Format | Cond ||-------|------|--------|------|| 22 | POS Entry Mode | n 3 | M || 23 | Card Sequence Number | n 3 | O || 24 | Function Code | n 3 | M || 25 | POS Condition Code | n 2 | M || 35 | Track 2 Data | LLVAR Pz ..37 | 07 || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M | ### Context &amp; Security | Field | Name | Format | Cond ||-------|------|--------|------|| 48 | Transaction Context | LLLTLV v ..999 | M || 49 | Currency Code | n 3 | M || 52 | PIN Data | b 8 | 08 || 53 | DUKPT Key Numbers | b 30 | 10 || 55 | ICC Data | LLLVAR b ..999 | 05 || 60 | Security Data | LLLTLV v ..999 | M || 61 | Encrypted CHD | LLLTLV b ..999 | 07 || 62 | Cardholder Context | LLLTLV v ..999 | O || 64 | MAC | b 8 | 21 || 123 | Non-Payment PIN | LLLTLV v ..999 | 08 || 124 | Second Card Data | LLLTLV v ..999 | 22 || 128 | MAC (alt) | b 8 | 21 | --- ## 0210 - Financial Response ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 3 | Processing Code | n 6 | M || 4 | Transaction Amount | n 12 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M | ### Entry &amp; Response | Field | Name | Format | Cond ||-------|------|--------|------|| 22 | POS Entry Mode | n 3 | M || 23 | Card Sequence Number | n 3 | 16 || 24 | Function Code | n 3 | M || 25 | POS Condition Code | n 2 | M || 37 | Retrieval Ref Number | an 12 | 15 || 38 | Authorisation Code | anp 6 | O || 39 | Response Code | an 2 | M || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M | ### Context &amp; Security | Field | Name | Format | Cond ||-------|------|--------|------|| 48 | Transaction Context | LLLTLV v ..999 | 15 || 49 | Currency Code | n 3 | M || 53 | DUKPT Key Numbers | b 30 | 10 || 55 | ICC Data | LLLVAR b ..999 | O || 60 | Security Data | LLLTLV v ..999 | M || 63 | Transaction Advice | LLLTLV v ..999 | O || 64 | MAC | b 8 | 21 || 125 | Associated Account | LLLTLV v ..999 | O || 128 | MAC (alt) | b 8 | 21 | --- ## 0220/0221 - Financial Advice (Capture) ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 2 | PAN | LLVAR n ..19 | 07 || 3 | Processing Code | n 6 | M || 4 | Transaction Amount | n 12 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M || 14 | Expiration Date | n 4 | 02 | ### Entry &amp; Identification | Field | Name | Format | Cond ||-------|------|--------|------|| 22 | POS Entry Mode | n 3 | M || 23 | Card Sequence Number | n 3 | O || 24 | Function Code | n 3 | M || 25 | POS Condition Code | n 2 | M || 35 | Track 2 Data | LLVAR Pz ..37 | 07 || 37 | Retrieval Ref Number | an 12 | 17 || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M | ### Context &amp; Security | Field | Name | Format | Cond ||-------|------|--------|------|| 48 | Transaction Context | LLLTLV v ..999 | M || 49 | Currency Code | n 3 | M || 53 | DUKPT Key Numbers | b 30 | 10 || 55 | ICC Data | LLLVAR b ..999 | 05 || 60 | Security Data | LLLTLV v ..999 | M || 61 | Encrypted CHD | LLLTLV b ..999 | 07 || 62 | Cardholder Context | LLLTLV v ..999 | O || 63 | Transaction Advice | LLLTLV v ..999 | O || 64 | MAC | b 8 | 21 || 124 | Second Card Data | LLLTLV v ..999 | 22 || 128 | MAC (alt) | b 8 | 21 | --- ## 0230 - Financial Advice Response ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 3 | Processing Code | n 6 | M || 4 | Transaction Amount | n 12 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M | ### Entry &amp; Response | Field | Name | Format | Cond ||-------|------|--------|------|| 22 | POS Entry Mode | n 3 | M || 24 | Function Code | n 3 | M || 25 | POS Condition Code | n 2 | M || 38 | Authorisation Code | anp 6 | O || 39 | Response Code | an 2 | M || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M | ### Context &amp; Security | Field | Name | Format | Cond ||-------|------|--------|------|| 48 | Transaction Context | LLLTLV v ..999 | 15 || 49 | Currency Code | n 3 | M || 53 | DUKPT Key Numbers | b 30 | 10 || 60 | Security Data | LLLTLV v ..999 | M || 63 | Transaction Advice | LLLTLV v ..999 | O || 64 | MAC | b 8 | 21 || 125 | Associated Account | LLLTLV v ..999 | O || 128 | MAC (alt) | b 8 | 21 | --- ## 0420/0421 - Reversal Advice ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 2 | PAN | LLVAR n ..19 | 03 || 3 | Processing Code | n 6 | 03 || 4 | Transaction Amount | n 12 | 03 || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | 03 || 13 | Local Date | n 4 | 03 || 14 | Expiration Date | n 4 | 03 | ### Entry &amp; Identification | Field | Name | Format | Cond ||-------|------|--------|------|| 22 | POS Entry Mode | n 3 | 03 || 23 | Card Sequence Number | n 3 | 03 || 24 | Function Code | n 3 | M || 25 | POS Condition Code | n 2 | 03 || 35 | Track 2 Data | LLVAR Pz ..37 | 03 || 37 | Retrieval Ref Number | an 12 | 17 || 38 | Authorisation Code | anp 6 | 03 || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M | ### Context &amp; Security | Field | Name | Format | Cond ||-------|------|--------|------|| 48 | Transaction Context | LLLTLV v ..999 | M || 49 | Currency Code | n 3 | 03 || 53 | DUKPT Key Numbers | b 30 | 10 || 55 | ICC Data | LLLVAR b ..999 | 05 || 60 | Security Data | LLLTLV v ..999 | M || 61 | Encrypted CHD | LLLTLV b ..999 | 03 || 63 | Transaction Advice | LLLTLV v ..999 | O || 90 | Original Data Elements | n 42 | M || 124 | Second Card Data | LLLTLV v ..999 | 03 || 128 | MAC | b 8 | 10 | --- ## 0430 - Reversal Response | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 3 | Processing Code | n 6 | M || 4 | Transaction Amount | n 12 | 03 || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M || 24 | Function Code | n 3 | M || 25 | POS Condition Code | n 2 | M || 39 | Response Code | an 2 | M || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M || 49 | Currency Code | n 3 | 03 || 53 | DUKPT Key Numbers | b 30 | 10 || 60 | Security Data | LLLTLV v ..999 | M || 63 | Transaction Advice | LLLTLV v ..999 | O | --- ## 0520/0521 - Reconciliation (Settlement) ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M || 24 | Function Code | n 3 | M || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M || 50 | Currency Code, Recon | n 3 | M | ### Totals | Field | Name | Format | Cond ||-------|------|--------|------|| 74 | Credits, Number | n 10 | M || 75 | Credits, Rev Number | n 10 | M || 76 | Debits, Number | n 10 | M || 77 | Debits, Rev Number | n 10 | M || 80 | Inquiries, Number | n 10 | M || 81 | Auths, Number | n 10 | M || 86 | Credits, Amount | n 16 | M || 87 | Credits, Rev Amount | n 16 | M || 88 | Debits, Amount | n 16 | M || 89 | Debits, Rev Amount | n 16 | M || 97 | Net Settlement | x+n 16 | M | ### Security | Field | Name | Format | Cond ||-------|------|--------|------|| 53 | DUKPT Key Numbers | b 30 | 10 || 60 | Security Data | LLLTLV v ..999 | M || 128 | MAC | b 8 | 10 | --- ## 0530 - Reconciliation Response ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M || 24 | Function Code | n 3 | M || 39 | Response Code | an 2 | M || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M || 50 | Currency Code, Recon | n 3 | M || 66 | Settlement Code | n 1 | M | ### Totals (if not in balance) | Field | Name | Format | Cond ||-------|------|--------|------|| 74 | Credits, Number | n 10 | 13 || 75 | Credits, Rev Number | n 10 | 13 || 76 | Debits, Number | n 10 | 13 || 77 | Debits, Rev Number | n 10 | 13 || 80 | Inquiries, Number | n 10 | 13 || 81 | Auths, Number | n 10 | 13 || 86 | Credits, Amount | n 16 | 13 || 87 | Credits, Rev Amount | n 16 | 13 || 88 | Debits, Amount | n 16 | 13 || 89 | Debits, Rev Amount | n 16 | 13 || 97 | Net Settlement | x+n 16 | 13 | ### Security | Field | Name | Format | Cond ||-------|------|--------|------|| 53 | DUKPT Key Numbers | b 30 | 10 || 60 | Security Data | LLLTLV v ..999 | M || 128 | MAC | b 8 | 10 | --- ## 0800 - Network Management (Log On/Echo) | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 24 | Function Code | n 3 | M || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M || 53 | DUKPT Key Numbers | b 30 | 10 || 60 | Security Data | LLLTLV v ..999 | M || 70 | Network Mgmt Info | n 3 | M || 128 | MAC | b 8 | 10 | --- ## 0810 - Network Management Response | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 24 | Function Code | n 3 | M || 39 | Response Code | an 2 | M || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M || 53 | DUKPT Key Numbers | b 30 | 10 || 60 | Security Data | LLLTLV v ..999 | M || 63 | Transaction Advice | LLLTLV v ..999 | O || 70 | Network Mgmt Info | n 3 | M || 128 | MAC | b 8 | 10 | --- ## 0300 - File Update (PIN Change) ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 2 | PAN | LLVAR n ..19 | 07 || 3 | Processing Code | n 6 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M || 14 | Expiration Date | n 4 | 02 | ### Entry &amp; Identification | Field | Name | Format | Cond ||-------|------|--------|------|| 22 | POS Entry Mode | n 3 | M || 23 | Card Sequence Number | n 3 | O || 24 | Function Code | n 3 | M || 35 | Track 2 Data | LLVAR Pz ..37 | 07 || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M | ### Context &amp; Security | Field | Name | Format | Cond ||-------|------|--------|------|| 48 | Transaction Context | LLLTLV v ..999 | M || 53 | DUKPT Key Numbers | b 30 | 10 || 60 | Security Data | LLLTLV v ..999 | M || 61 | Encrypted CHD | LLLTLV b ..999 | 07 || 123 | Non-Payment PIN | LLLTLV v ..999 | M || 128 | MAC | b 8 | 10 | --- ## 0310 - File Update Response (PIN Change) ### Core Fields | Field | Name | Format | Cond ||-------|------|--------|------|| 0 | MTI | n 4 | M || 1 | Bitmap | b 16 | M || 3 | Processing Code | n 6 | M || 7 | Transmission Date Time | n 10 | M || 11 | STAN | n 6 | M || 12 | Local Time | n 6 | M || 13 | Local Date | n 4 | M | ### Entry &amp; Response | Field | Name | Format | Cond ||-------|------|--------|------|| 22 | POS Entry Mode | n 3 | M || 23 | Card Sequence Number | n 3 | 16 || 24 | Function Code | n 3 | M || 37 | Retrieval Ref Number | an 12 | 15 || 38 | Authorisation Code | anp 6 | O || 39 | Response Code | an 2 | M || 41 | Terminal ID | ans 8 | M || 42 | Merchant ID | ans 15 | M | ### Context &amp; Security | Field | Name | Format | Cond ||-------|------|--------|------|| 48 | Transaction Context | LLLTLV v ..999 | 15 || 53 | DUKPT Key Numbers | b 30 | 10 || 60 | Security Data | LLLTLV v ..999 | M || 63 | Transaction Advice | LLLTLV v ..999 | O | 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/terminal-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 &quot;2E&quot; 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/terminal-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/terminal-api/card-present/tss-iso8583-interface-specification/message-fields/f-1-bitmap.md): Description ISO 8583 uses a concept called &quot;bit map&quot;, 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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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&apos;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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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&apos;s life cycle (authorization, reversal, and so on) Attributes an 12
    • [F-38 Authorisation Code](https://developer.pay.tnsi.com/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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/terminal-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 &lt;000000&gt; 4 n 12 Amount, transaction &lt;000000001230&gt; 7 n 10 Transmission date &amp; time &lt;1116103008&gt; 11 n 6 System trace audit number (STAN) &lt;000001&gt; 12 n 6 Local transaction time (hhmmss) &lt;183008&gt; 13 n 4 Local transaction date (MMDD) &lt;1116&gt; 22 n 3 Point of service entry mode &lt;007&gt; 25 n 2 Point of service condition code &lt;10&gt; 41 ans 8 Card acceptor terminal identification &lt;03430323&gt; 42 ans 15 Card acceptor identification code &lt;0393938324D4552&gt; 48 an...999 Additional data (private) &lt;8414E54444556494345200058545A4F000500800C4D5243000 4151043564D0002044D4352000101414944001441303030303 030363135303030314554520007313030323539380840FFFF0 610033245200001FFFF0610013245200001000000000000000 0000001545F24032709305F2A0204585F34010182020900840 7A0000006150001950500000080009A032311169C01009F020 60000000012309F03060000000000009F080200019F0902000 19F10200FA501A800F8000000000000000000000F001111111 1111111111111111111119F1A0204589F2&gt; 49 a or n 3 Currency code, transaction &lt;608&gt; 53 n 16 Security related control information &lt;C2384ED4F30D2E2E&gt; 55 ans...999 ICC data – EMV having multiple tags &lt;Warning: Not valid length indicator detected = 9F2 Could not continue parsing. Please check your ISO8583 message&gt; 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.) &lt;809F3303E0F8C89F34033F00009F3501229F360209399F3704 9B0700D20034454E4300020154435500160000001240209982 5553520010504554524F4E5F415049002954324400246E4315 3D9E1FAB4FE1B34E30CB7C1CE4381266A70F79678B00355052 44003048504300043130303151545900041000555052000300 0054505200041231C7790EB09F92562E&gt; 61 ans...999 Reserved (private) (e.g. CVV2/service code transactions) &lt;Warning: Not valid length indicator detected = Could not continue parsing. Please check your ISO8583 message&gt; 63 ans...999 Reserved (private) &lt;Warning: Not valid length indicator detected = Could not continue parsing. Please check your ISO8583 message&gt; 64 b 64 Message authentication code (MAC) &lt;&gt; Sample PreAuth:
    • [Sale](https://developer.pay.tnsi.com/terminal-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 &lt;header&gt;6000190000&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0200&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000300&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0716010457&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000025&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;090457&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0716&quot;/&gt; &lt;field id=&quot;22&quot; value=&quot;051&quot;/&gt; &lt;field id=&quot;25&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100039&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000098&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;545A4F000500800C4D52430004150843564D0002044D435200010045545200083039303530313033&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;52&quot; value=&quot;AA55AA55&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF06100300344001E2FFFF06100100344001C2FFFF0610020034400026&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;55&quot; value=&quot;9F26080A5715A9CA195ADA9F2701809F100706010A03A0A84C9F3704094509659F36021E13950508C00400009A032507169C01009F02060000000003005F2A02084082023C009F1A0208409F03060000000000009F3303E0F8C89F34034203009F3501229F1E0831363430323434318407A00000000310109F0902008C9F4104000000255F3401019F0607A00000000310105F28020554&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201544355001600000016402441435553520010504554524F4E5F415049&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;61&quot; value=&quot;AA55AA55&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;0E5ED910BC091AAF&quot; type=&quot;binary&quot;/&gt; &lt;/log&gt; &lt;header&gt;6000190000&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0200&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000300&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0716010457&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000025&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;090457&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0716&quot;/&gt; &lt;field id=&quot;22&quot; value=&quot;051&quot;/&gt; &lt;field id=&quot;25&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100039&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000098&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;545A4F000500800C4D52430004150843564D0002044D435200010045545200083039303530313033&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;52&quot; value=&quot;AA55AA55&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF06100300344001E2FFFF06100100344001C2FFFF0610020034400026&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;55&quot; value=&quot;9F26080A5715A9CA195ADA9F2701809F100706010A03A0A84C9F3704094509659F36021E13950508C00400009A032507169C01009F02060000000003005F2A02084082023C009F1A0208409F03060000000000009F3303E0F8C89F34034203009F3501229F1E0831363430323434318407A00000000310109F0902008C9F4104000000255F3401019F0607A00000000310105F28020554&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201544355001600000016402441435553520010504554524F4E5F415049&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;61&quot; value=&quot;AA55AA55&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;0E5ED910BC091AAF&quot; type=&quot;binary&quot;/&gt; &lt;/log&gt; Sale Response The following is the formatted sale transaction response Plain text &lt;header&gt;6000000019&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0210&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000300&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0716010547&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000025&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;090457&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0716&quot;/&gt; &lt;field id=&quot;37&quot; value=&quot;100001557592&quot;/&gt; &lt;field id=&quot;38&quot; value=&quot;934282&quot;/&gt; &lt;field id=&quot;39&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100039&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000098&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;554944003633353863356230362D373139372D346561642D623236342D39353338323861666438356148524D0008415050524F56414C&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF06100300344001E2FFFF06100100344001C2FFFF0610020034400026&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;55&quot; value=&quot;8A0230309F36021E13&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;B3893C09FB180906&quot; type=&quot;binary&quot;/&gt; &lt;header&gt;6000000019&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0210&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000300&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0716010547&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000025&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;090457&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0716&quot;/&gt; &lt;field id=&quot;37&quot; value=&quot;100001557592&quot;/&gt; &lt;field id=&quot;38&quot; value=&quot;934282&quot;/&gt; &lt;field id=&quot;39&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100039&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000098&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;554944003633353863356230362D373139372D346561642D623236342D39353338323861666438356148524D0008415050524F56414C&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF06100300344001E2FFFF06100100344001C2FFFF0610020034400026&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;55&quot; value=&quot;8A0230309F36021E13&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;B3893C09FB180906&quot; type=&quot;binary&quot;/&gt;
    • [PreAuthorization](https://developer.pay.tnsi.com/terminal-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 &lt;header&gt;6000190000&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0100&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000700&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0807011333&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000039&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;091333&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0807&quot;/&gt; &lt;field id=&quot;22&quot; value=&quot;071&quot;/&gt; &lt;field id=&quot;25&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100042&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000100&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;545A4F000500800C4D52430004150843564D0002004D435200010045545200083039313333333034&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF061003002EA0004CFFFF061001002EA0002F00000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;55&quot; value=&quot;5F2A0208405F340100820219808407A0000000041010950500000080019A032508079B0200009C01009F02060000000007009F03060000000000009F080200029F090200029F10120110A04001240000000000000000000000FF9F1A0208409F260812E7C8F0B13C5A049F2701809F3303E008089F34031F03029F3501229F360202829F3704A4CE461E9F6E07045800003030005F280204589F530182&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201544355001600000018530461075553520010504554524F4E5F415049&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;61&quot; value=&quot;AA55AA55&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;9E513FE637140584&quot; type=&quot;binary&quot;/&gt; &lt;header&gt;6000190000&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0100&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000700&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0807011333&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000039&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;091333&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0807&quot;/&gt; &lt;field id=&quot;22&quot; value=&quot;071&quot;/&gt; &lt;field id=&quot;25&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100042&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000100&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;545A4F000500800C4D52430004150843564D0002004D435200010045545200083039313333333034&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF061003002EA0004CFFFF061001002EA0002F00000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;55&quot; value=&quot;5F2A0208405F340100820219808407A0000000041010950500000080019A032508079B0200009C01009F02060000000007009F03060000000000009F080200029F090200029F10120110A04001240000000000000000000000FF9F1A0208409F260812E7C8F0B13C5A049F2701809F3303E008089F34031F03029F3501229F360202829F3704A4CE461E9F6E07045800003030005F280204589F530182&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201544355001600000018530461075553520010504554524F4E5F415049&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;61&quot; value=&quot;AA55AA55&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;9E513FE637140584&quot; type=&quot;binary&quot;/&gt; PreAuth Response Response message received from the ISO8583 interface: Plain text &lt;header&gt;6000000019&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0110&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000700&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0807011659&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000039&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;091333&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0807&quot;/&gt; &lt;field id=&quot;37&quot; value=&quot;100001577523&quot;/&gt; &lt;field id=&quot;38&quot; value=&quot;670586&quot;/&gt; &lt;field id=&quot;39&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100042&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000100&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;554944003636616338386238392D643262622D346131392D393461352D33633038366264326665653948524D0008415050524F56414C&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF061003002EA0004CFFFF061001002EA0002F00000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;604F56E6B56F7761&quot; type=&quot;binary&quot;/&gt; &lt;header&gt;6000000019&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0110&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000700&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0807011659&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000039&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;091333&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0807&quot;/&gt; &lt;field id=&quot;37&quot; value=&quot;100001577523&quot;/&gt; &lt;field id=&quot;38&quot; value=&quot;670586&quot;/&gt; &lt;field id=&quot;39&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100042&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000100&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;554944003636616338386238392D643262622D346131392D393461352D33633038366264326665653948524D0008415050524F56414C&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF061003002EA0004CFFFF061001002EA0002F00000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;604F56E6B56F7761&quot; type=&quot;binary&quot;/&gt;
    • [Capture](https://developer.pay.tnsi.com/terminal-api/card-present/tss-iso8583-interface-specification/sample-messages/auth-message/capture.md): Capture Advice The following is a formatted capture advice. Plain text &lt;header&gt;6000190000&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0220&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000001500&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0808024134&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000008&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;024420&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0808&quot;/&gt; &lt;field id=&quot;22&quot; value=&quot;071&quot;/&gt; &lt;field id=&quot;25&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;37&quot; value=&quot;100001578483&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100042&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000100&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;554944003634353562383361312D326635612D346135372D613361302D376265356331313732396137545A4F000500800C4D52430004100443564D0002074D435200010045545200083130343133323035&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF061003002EA00060FFFF061001002EA0003E00000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;55&quot; value=&quot;5F2A0208405F340100820220008407A0000000031010950500000000009A032508089C01009F02060000000015009F100706011203A000009F1A0208409F2608036C7535ADD3D4249F2701809F33009F3602024D9F3704947346F69F6E04207000005F28020458&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201544355001600000018530461075553520010504554524F4E5F415049&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;61&quot; value=&quot;AA55AA55&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;586B85DA6A4B8968&quot; type=&quot;binary&quot;/&gt; &lt;/log&gt; &lt;header&gt;6000190000&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0220&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000001500&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0808024134&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000008&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;024420&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0808&quot;/&gt; &lt;field id=&quot;22&quot; value=&quot;071&quot;/&gt; &lt;field id=&quot;25&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;37&quot; value=&quot;100001578483&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100042&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000100&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;554944003634353562383361312D326635612D346135372D613361302D376265356331313732396137545A4F000500800C4D52430004100443564D0002074D435200010045545200083130343133323035&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF061003002EA00060FFFF061001002EA0003E00000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;55&quot; value=&quot;5F2A0208405F340100820220008407A0000000031010950500000000009A032508089C01009F02060000000015009F100706011203A000009F1A0208409F2608036C7535ADD3D4249F2701809F33009F3602024D9F3704947346F69F6E04207000005F28020458&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201544355001600000018530461075553520010504554524F4E5F415049&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;61&quot; value=&quot;AA55AA55&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;586B85DA6A4B8968&quot; type=&quot;binary&quot;/&gt; &lt;/log&gt; Capture Response: The following is a formatted capture response you will receive Plain text &lt;header&gt;6000000019&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0230&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000001500&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0808024455&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000008&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;024420&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0808&quot;/&gt; &lt;field id=&quot;37&quot; value=&quot;100001578483&quot;/&gt; &lt;field id=&quot;38&quot; value=&quot;455536&quot;/&gt; &lt;field id=&quot;39&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100042&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000100&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;554944003634623765356363322D363236392D346137662D393833652D35316531336665373437303048524D0008415050524F56414C&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF061003002EA00060FFFF061001002EA0003E00000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;B7247C370379E062&quot; type=&quot;binary&quot;/&gt; &lt;header&gt;6000000019&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0230&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000001500&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0808024455&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000008&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;024420&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0808&quot;/&gt; &lt;field id=&quot;37&quot; value=&quot;100001578483&quot;/&gt; &lt;field id=&quot;38&quot; value=&quot;455536&quot;/&gt; &lt;field id=&quot;39&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100042&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000100&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;554944003634623765356363322D363236392D346137662D393833652D35316531336665373437303048524D0008415050524F56414C&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF061003002EA00060FFFF061001002EA0003E00000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;B7247C370379E062&quot; type=&quot;binary&quot;/&gt;
    • [Reversal](https://developer.pay.tnsi.com/terminal-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 &lt;header&gt;6000190000&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0420&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000100&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0806000701&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000009&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;080701&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0806&quot;/&gt; &lt;field id=&quot;22&quot; value=&quot;071&quot;/&gt; &lt;field id=&quot;25&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100041&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000102&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;545A4F000500800C4D52430004402143564D0002074D435200010045545200083038303634313033&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF06100300344002C1FFFF06100100344002C300000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;55&quot; value=&quot;5F2A0208405F340101820220008407A0000000031010950500000000009A032508069C01009F02060000000001009F100706011103A000009F1A0208409F2608148BE8F2B73934669F2701809F33009F36021EB49F3704BBCEC101&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201544355001600000016402441435553520010504554524F4E5F415049&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;61&quot; value=&quot;AA55AA55&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;90&quot; value=&quot;020000000908060006380000000000000000000000&quot;/&gt; &lt;field id=&quot;128&quot; value=&quot;30C60D711E4074D5&quot; type=&quot;binary&quot;/&gt; &lt;header&gt;6000190000&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0420&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000100&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0806000701&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000009&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;080701&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0806&quot;/&gt; &lt;field id=&quot;22&quot; value=&quot;071&quot;/&gt; &lt;field id=&quot;25&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100041&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000102&quot;/&gt; &lt;field id=&quot;48&quot; value=&quot;545A4F000500800C4D52430004402143564D0002074D435200010045545200083038303634313033&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF06100300344002C1FFFF06100100344002C300000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;55&quot; value=&quot;5F2A0208405F340101820220008407A0000000031010950500000000009A032508069C01009F02060000000001009F100706011103A000009F1A0208409F2608148BE8F2B73934669F2701809F33009F36021EB49F3704BBCEC101&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201544355001600000016402441435553520010504554524F4E5F415049&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;61&quot; value=&quot;AA55AA55&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;90&quot; value=&quot;020000000908060006380000000000000000000000&quot;/&gt; &lt;field id=&quot;128&quot; value=&quot;30C60D711E4074D5&quot; type=&quot;binary&quot;/&gt; Reversal Advice Response Plain text &lt;header&gt;6000000019&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0430&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000100&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0806000747&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000009&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;080701&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0806&quot;/&gt; &lt;field id=&quot;37&quot; value=&quot;&quot;/&gt; &lt;field id=&quot;39&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100041&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000102&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF06100300344002C1FFFF06100100344002C300000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;27BC62C53F70E856&quot; type=&quot;binary&quot;/&gt; &lt;header&gt;6000000019&lt;/header&gt; &lt;field id=&quot;0&quot; value=&quot;0430&quot;/&gt; &lt;field id=&quot;3&quot; value=&quot;000000&quot;/&gt; &lt;field id=&quot;4&quot; value=&quot;000000000100&quot;/&gt; &lt;field id=&quot;7&quot; value=&quot;0806000747&quot;/&gt; &lt;field id=&quot;11&quot; value=&quot;000009&quot;/&gt; &lt;field id=&quot;12&quot; value=&quot;080701&quot;/&gt; &lt;field id=&quot;13&quot; value=&quot;0806&quot;/&gt; &lt;field id=&quot;37&quot; value=&quot;&quot;/&gt; &lt;field id=&quot;39&quot; value=&quot;00&quot;/&gt; &lt;field id=&quot;41&quot; value=&quot;T1100041&quot;/&gt; &lt;field id=&quot;42&quot; value=&quot;M11000000000102&quot;/&gt; &lt;field id=&quot;49&quot; value=&quot;840&quot;/&gt; &lt;field id=&quot;53&quot; value=&quot;FFFF06100300344002C1FFFF06100100344002C300000000000000000000&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;60&quot; value=&quot;454E43000201&quot; type=&quot;binary&quot;/&gt; &lt;field id=&quot;64&quot; value=&quot;27BC62C53F70E856&quot; type=&quot;binary&quot;/&gt;
• [HMAC Authentication](https://developer.pay.tnsi.com/terminal-api/resources/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&apos;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 tag to your HTML file to load CryptoJS from a CDN. Javascript &lt;script src=&quot;https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js&quot;&gt;&lt;/script&gt; Javascript function generateHMAC(apiKey, secret, requestBody) { var time = new Date().getTime(); var rawSignature = apiKey + &quot;:&quot; + time + &quot;:&quot; + 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.
• [Response Codes](https://developer.pay.tnsi.com/terminal-api/resources/response-codes.md): Response codes provide a consistent, host-independent view of transaction outcomes by standardising codes returned by upstream hosts. Use the codes, human-readable messages, and practical guidance to interpret outcomes and determine how your application should respond. 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. 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&apos;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. H08 Approved - honor with identification Approved on condition the cardholder&apos;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 00 Approved Transaction was fully approved by the issuer. 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&apos;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 Code tnsResponseText Description F01 Invalid vehicle Declined because the vehicle identifier supplied is not valid for the fleet card. F02 Invalid driver Declined because the driver identifier supplied is not valid for the fleet card. F03 Invalid product Declined because the fuel/merchandise product is not permitted on this card. F04 Exceeds transaction total limit per product class Declined because the transaction total exceeds the limit for that product class. F05 Over daily limit Declined because the card&apos;s daily spend/usage limit has been exceeded. F06 Invalid date or time Declined because the transaction date/time is outside the card&apos;s permitted window. F07 Exceeds quantity Declined because the requested quantity exceeds the card&apos;s permitted amount. F08 Invalid prompt entry Declined because a fuel-site prompt (e.g. odometer, ID) was answered with invalid data. F09 Invalid track 2 data Declined because the card&apos;s track 2 data is invalid or unreadable. F10 Voyager ID problem Declined due to a problem with the Voyager fleet card identification. F11 Invalid odometer Declined because the odometer reading entered is invalid. F12 Invalid restriction code Declined because a card restriction code prevents this purchase. F13 Pay at pump not allowed Declined because the card is not permitted to pay at the pump; go inside to pay. F14 Over fuel limit Declined because the fuel amount exceeds the card&apos;s fuel limit. F15 Over cash limit Declined because the cash portion exceeds the card&apos;s cash limit. F16 Fuel price error Declined due to a fuel price error/mismatch at the site. F17 Over repair limit Declined because the repair/service amount exceeds the card&apos;s limit. F18 Over additive limit Declined because the additive amount exceeds the card&apos;s limit. F19 Invalid user Declined because the user identifier supplied is not valid for the card. F20 Driver&apos;s License or ID is Required Declined because a driver&apos;s licence or ID must be supplied to proceed. F21 Fuel only Declined for non-fuel items; the card is restricted to fuel purchases only. F22 Received prompts do not match expected values Declined because the site prompt responses did not match the values the card expected. F23 Extended prompting required Declined because additional (extended) prompts must be completed before approval.