Terminal Payment API

Start a payment or refund on a terminal and retrieve the final result.

Quick Start

Send requests to {gateway_endpoint}/ — see Development & Testing for test endpoints or Production for live endpoints.

{
  "TERMID": "your_termid",
  "PASS": "your_pass",
  "TYPE": "W",
  "ACTION": "StartSession",
  "INV": "INV1001",
  "AMT": "11.00",
  "REQUESTID": "4736823",
  "DEVICEID": "DEV001",
  "SUCCESSURL": "https://merchant.com/success"
}

How it Works

StartSession → Terminal → Callback → Final Result

  1. Call StartSession
  2. The terminal processes the transaction
  3. The gateway calls your SUCCESSURL
  4. Your system retrieves the final result

⚠️ Important: How Responses Work

This is an asynchronous API. Do not assume immediate transaction results.
If the request fails (CODE ≠ 0000), no callback will be triggered.

Each transaction has one or two responses, depending on the initial result.

1. StartSession Response (Immediate)

Returned right after calling StartSession.

  • CODE = 0000 → Request successfully sent to terminal
  • CODE ≠ 0000 → Request failed (terminal did not receive it)

2. Final Transaction Result (Only if StartSession CODE = 0000)

If StartSession returns 0000, the terminal will process the transaction.

You will then receive a second response via callback with the final result:

  • CODE = 0000 → Transaction approved
  • CODE = 8510 → Declined (NSF, fraud, etc.)
  • Other codes → Cancelled or failed. See Status Codes.

Key Behavior

  • If StartSession CODE ≠ 0000
    → Transaction failed immediately
    → No further response

  • If StartSession CODE = 0000
    → Transaction sent to terminal
    → Wait for final result

Think of StartSession as "request delivery" and the final result as "transaction outcome".


StartSession

Start a payment or refund.

Required Parameters

ParamDescription
TERMIDTerminal ID
PASSTerminal password
TYPEMust be W
ACTIONStartSession
AMTAmount
REQUESTIDUnique ID per request
DEVICEIDDevice ID
CUSTEMAILCustomer email

Optional Parameters

ParamDescription
SUCCESSURLCallback URL for approved transactions. Overrides the terminal's configured success URL for this session. Only honored if the terminal has DYNAMICURL enabled.
FAILUREURLCallback URL for declined or failed transactions. Overrides the terminal's configured failure URL for this session. Defaults to SUCCESSURL if omitted. Only honored if the terminal has DYNAMICURL enabled.
INVInvoice number
REFUNDRefund instead of sale
NOTERMPRINTDisable receipt printing
JSONReturn JSON response
LANGE (English), F (French)
DESCDescription

Refer to Terminal Payment API


Example Request

Sale

{
  "TERMID": "your_termid",
  "PASS": "your_pass",
  "TYPE": "W",
  "ACTION": "StartSession",
  "INV": "INV1001",
  "CUSTEMAIL": "[email protected]",
  "AMT": "11.00",
  "REQUESTID": "4736823",
  "DEVICEID": "DEV001",
  "SUCCESSURL": "https://merchant.com/success",
  "FAILUREURL": "https://merchant.com/failure"
}

Refund

{
  "TERMID": "your_termid",
  "PASS": "your_pass",
  "TYPE": "W",
  "ACTION": "StartSession",
  "INV": "INV1001",
  "CUSTEMAIL": "[email protected]",
  "AMT": "11.00",
  "REQUESTID": "4736823",
  "DEVICEID": "DEV001",
  "SUCCESSURL": "https://merchant.com/success",
  "FAILUREURL": "https://merchant.com/failure",
  "REFUND": "Y"
}

No Terminal Receipt

{
  "TERMID": "your_termid",
  "PASS": "your_pass",
  "TYPE": "W",
  "ACTION": "StartSession",
  "INV": "INV1001",
  "CUSTEMAIL": "[email protected]",
  "AMT": "11.00",
  "REQUESTID": "4736823",
  "DEVICEID": "DEV001",
  "SUCCESSURL": "https://merchant.com/success",
  "FAILUREURL": "https://merchant.com/failure",
  "NOTERMPRINT": "Y"
}

StartSession Response

FieldDescription
CODE0000 = request sent to terminal
TEXTStatus message
SECUREIDSession ID (save this)
CANCELURLURL to cancel the active terminal session (optional use)
HOSTN/A - Used for ecommerce transactions only
USERFEEN/A - Used for ecommerce transactions only
DATEDate of the request
TIMETime of the request
DURDuration of the request
⚠️

Do not treat this as payment success. This indicates the request was accepted. You must now wait for the final transaction result via callback.

❗️

CANCELURL can be used to cancel an in-progress transaction on the terminal if needed. If used after the transaction has been processed but before the batch has been settled, it will Void the transaction.

Store the SECUREID

  • Save the SECUREID from the StartSession response.
  • The same SECUREID will be returned in the final transaction result
  • This is required to match the final transaction result to the original request.

Example StartSession Response

{
  "TEXT": "SENT TO TERMINAL",
  "CODE": "0000",
  "SECUREID": "abc123",
  "CANCELURL": "https://payment.interpaypos.com/api/HOSTPYMT/cancel/?SecureID=abc123",
  "HOST": "https://payment.interpaypos.com",
  "USERFEE": "0.00",
  "DATE": "2026-03-25",
  "TIME": "15:45:52",
  "DUR": "3.737"
}

Note: Use the CANCELURL value returned by the gateway. Don't hard-code the host; it can change.


Callback

After the terminal completes the transaction, the gateway will call one of your URLs:

  • SUCCESSURL → Transaction approved
  • FAILUREURL → Transaction declined or failed

The callback indicates that processing is complete.
You must use the response data to determine the final result.

Final Transaction Result

FieldDescription
TEXTAPPROVED, DECLINED, VOIDED, or Description of decline
CODEFinal result code (refer to status codes below)
AMTTransaction amount
SECUREIDSession ID
REFNUMTransaction reference number provided by the terminal
REQUESTIDOriginal request ID
INVInvoice
ACKY (confirms payment was captured)
RECEIPTSMerchant and Customer copy of receipt from the terminal in HTML
REFUNDY (only included if transaction was a Refund)
AUTHAuthorization Code (sent only if transaction was APPROVED)
CARDTYPEType of card used for the transaction (sent only if transaction was APPROVED)
CARDMASKThe masked card number - only last 4 digits available (sent only if transaction was APPROVED)
CUSTEMAILCustomers email address (sent only if transaction was APPROVED)

Refer to Terminal Transaction Callback Specs

Approved

{
  "CODE": "0000",
  "TEXT": "APPROVED",
  "SECUREID": "ur32e7683kmr5y6o853d",
  "AMT": "1.23",
  "REQUESTID": "2082440",
  "REFNUM": "WP5420PQ23000423",
  "INV": "",
  "AUTH": "182886",
  "CARDTYPE": "I",
  "CARDMASK": "****3259",
  "CUSTEMAIL": "[email protected]",
  "ACK": "Y",
  "RECEIPTS": {
    "Customer": "<HTML receipt content>",
    "Merchant": "<HTML receipt content>"
  }
}

Device error

{
  "CODE": "8514",
  "TEXT": "Force(Ticket) Transaction Disabled",
  "SECUREID": "8j0310lxej7jrp0aruje",
  "REFUND": "Y",
  "AMT": "1.23",
  "REQUESTID": "3718563",
  "REFNUM": "",
  "INV": "",
  "ACK": "Y",
  "RECEIPTS": {
    "Customer": "<HTML receipt content>",
    "Merchant": "<HTML receipt content>"
  }
}

Status Codes

On the final result, TEXT can carry the terminal's own description of the problem instead of the message below, so always use CODE to decide what happened.

CodeMessageMeaning (StartSession)Meaning (Final Result)
0000SENT TO TERMINAL / APPROVEDRequest sent to terminalApproved
8500PLATFORM FEE NOT ALLOWEDPlatform Fee is not allowed; remove it from the request to continue—
8501USER FEE NOT ALLOWEDUser Fee is not allowed; remove it from the request to continue—
8502INVALID DEVICEIDDEVICEID is missing or invalid—
8503NO RESPONSENo response from the terminal—
8504NOT ALLOWEDRequest not allowed (terminal settings or details)—
8505NOT CONNECTEDTerminal not connected—
8506NOT FOUNDDevice not found—
8507NOT AVAILABLETerminal not available—
8508NOT IMPLEMENTEDNot implemented—
8509TERMINAL BUSYTerminal busy—
8510DECLINED—Declined by card issuer
8511CANCELLED—Cancelled on the terminal
8512TERMINAL CONFIG ERRTerminal configuration error—
8513GATEWAY ERR—Gateway error
8514DEVICE ERR—Device error
8515COMMUNICATION ERR—Communication error
8516UNKNOWN ERR—Unknown error

Recap

Sequence:

  1. Call StartSession
  2. If CODE ≠ 0000 → stop (request failed)
  3. If CODE = 0000 → wait for callback
  4. Read final result
  5. If CODE = 0000 → approved

Rules:

  • REQUESTID must be unique per transaction
  • Always store SECUREID
  • Do not treat StartSession response of 0000 as success for the transaction; always rely on the final result via callback
  • Use REFUND for refunds
  • Use NOTERMPRINT to disable receipt printing

Mental Model

StartSession = "Request delivered to terminal"
Final Result = "Transaction outcome"


Did this page help you?