DEVELOPER
DEVELOPER
Products

Ingenico SI Cloud API Integration Guide

semi-integratedcloud

How To Start


RequirementDetails
Connection TypeWebSocket (WSS)
UAP Base URLwss://epxpay-stg.nabancard.io/staging/
AuthenticationFour-part key + MAC/TIC via query parameter
Supported HardwareAll Ingenico Tetra terminals (DESK, LANE, MOVE, LINK)

  1. Sign up for a free North Developer account.
  2. Purchase a test terminal or contact us to use your own device. Test credentials (four-part key and MAC/TIC) will be provided to you and can be referenced on the Credentials page.
  3. Connect your Ingenico terminal to the network. The terminal will automatically connect to the cloud—no IP configuration required.
  4. Use the WebSocket integration steps below to connect and process transactions. The XML request structure is documented in the XML Request Fields section.
  5. When development is complete, contact us for certification. Once certified, production credentials will be provided.




Step 1: Establish WebSocket Connection

The Ingenico SI Cloud solution communicates using a WebSocket connection. To establish a connection, include your terminal credentials as a merchantId query parameter.


Connection URL Format


Example Connection URL



ComponentDescription
9001-999999-1-1Your four-part key (CUST_NBR-MERCH_NBR-DBA_NBR-TERMINAL_NBR)
MAC123456789Your MAC or TIC value




Step 2: Send a Transaction

Once the WebSocket connection is established, send transactions as JSON objects with a message field containing the XML payload.


Request Format


Sale Transaction Example (CCR1)




Step 3: Handle the Response

The terminal will respond with XML messages. Validate transaction responses by checking for the AUTH_RESP field.


Transaction Response Example

A successful transaction response will include the AUTH_RESP field:


Key Response Fields

FieldDescription
AUTH_RESPResponse code. 00 indicates approval.
AUTH_RESP_TEXTHuman-readable response text (e.g., "APPROVAL")
AUTH_GUIDBRIC/token for the transaction. Use for voids, refunds, etc.
AUTH_CODEAuthorization code from the issuer
AUTH_AMOUNTAuthorized amount
AUTH_MASKED_ACCOUNT_NBRMasked card number for display/receipts




XML Request Fields

The XML payload is wrapped in a <DETAIL> element. The following fields can be included in your transaction requests:


Required Fields

FieldDescriptionExample
TRAN_TYPETransaction type code (see Transaction Types)CCR1
AMOUNTTransaction amount in dollars25.99



Optional Fields

FieldDescriptionExample
TRAN_NBRTransaction number (auto-incremented if not provided)1
BATCH_IDBatch identifier (typically YYYYMMDD format)20250108
INVOICE_NBRInvoice or order number for referenceINV-12345
TIP_AMTTip amount in dollars5.00
TAX_AMTTax amount in dollars2.08
CLERK_IDClerk or employee identifierEMP001



Example: Sale with Optional Fields


Example: Authorization Only (CCR2)


Example: Void (CCRX)

To void a transaction, include the AUTH_GUID (BRIC) from the original transaction:


Example: Refund (CCR9)




Transaction Types

The following transaction types are available. Change the TRAN_TYPE value in your XML message accordingly:

TRAN_TYPEDescription
CCR0Account Verification
CCR1Retail Purchase Authorization & Capture (Sale)
CCR2Retail Purchase Authorization Only
CCR7Retail Purchase Authorization Reversal
CCR9Retail Return Capture (Refund)
CCRXRetail Void
DB00PIN Debit Sale
DB01PIN Debit Return
DB0VPIN Debit Reversal
EB00Food Stamp Purchase
EB01EBT Return
EB02Food Stamp Balance Inquiry
EB05EBT Cash Benefits Purchase




Supported Hardware

The Ingenico SI Cloud API works with any Ingenico Tetra hardware line currently supported:

  • Ingenico DESK 2600 (WiFi and non-WiFi)
  • Ingenico LANE 3000
  • Ingenico LANE 5000
  • Ingenico LANE 7000
  • Ingenico MOVE 5000
  • Ingenico LINK 2500

Visit the Hardware page to order a test terminal.




Support

For further assistance with your integration, please contact our support team or visit the Resources page for additional documentation.



Top of Page
// Ingenico SI Cloud API - WebSocket Client Example

// Your terminal credentials
const fourPartKey = '9001-999999-1-1';
const macTic = 'MAC123456789';
const merchantId = `${fourPartKey}-${macTic}`;

// WebSocket URL with credentials
const wsUrl = `wss://epxpay-stg.nabancard.io/staging/?merchantId=${merchantId}`;

// Create WebSocket connection
const socket = new WebSocket(wsUrl);

socket.onopen = function(event) {
    console.log('Connected to Ingenico SI Cloud API');
    
    // Send a sale transaction
    const transaction = {
        action: 'sendMessage',
        message: `<DETAIL>
            <TRAN_TYPE>CCR1</TRAN_TYPE>
            <AMOUNT>1.00</AMOUNT>
            <TRAN_NBR>2</TRAN_NBR>
            <BATCH_ID>20250421</BATCH_ID>
        </DETAIL>`
    };
    
    socket.send(JSON.stringify(transaction));
};

socket.onmessage = function(event) {
    const response = event.data;
    
    // Check for AUTH_RESP to validate transaction response
    if (response.includes('<AUTH_RESP>')) {
        console.log('Transaction Response:', response);
        // Process your transaction response here
    }
};

socket.onerror = function(error) {
    console.error('WebSocket Error:', error);
};

socket.onclose = function(event) {
    console.log('Connection closed');
};
Get Started
Working With UsHardwareSecurityFAQsGlossaryTags by Topic
Products
In Person PaymentsOnline PaymentsFull FeaturedMerchant Management
Explore
About UsBlogNorth.comNorth HubNorth Exchange
More
Log InCreate AccountContact UsTerms of UsePrivacy PolicyCookies
©2026 North is a registered DBA of NorthAB, LLC. All rights reserved. North is a registered ISO of BMO Harris Bank N.A., Chicago, IL, Citizens Bank N.A., Providence, RI, The Bancorp Bank, Philadelphia, PA, FFB Bank, Fresno, CA, Wells Fargo Bank, N.A., Concord, CA, and PNC Bank, N.A.