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
- Call
StartSession - The terminal processes the transaction
- The gateway calls your
SUCCESSURL - 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 terminalCODE ≠ 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 approvedCODE = 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
| Param | Description |
|---|---|
| TERMID | Terminal ID |
| PASS | Terminal password |
| TYPE | Must be W |
| ACTION | StartSession |
| AMT | Amount |
| REQUESTID | Unique ID per request |
| DEVICEID | Device ID |
| CUSTEMAIL | Customer email |
Optional Parameters
| Param | Description |
|---|---|
| SUCCESSURL | Callback URL for approved transactions. Overrides the terminal's configured success URL for this session. Only honored if the terminal has DYNAMICURL enabled. |
| FAILUREURL | Callback 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. |
| INV | Invoice number |
| REFUND | Refund instead of sale |
| NOTERMPRINT | Disable receipt printing |
| JSON | Return JSON response |
| LANG | E (English), F (French) |
| DESC | Description |
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
| Field | Description |
|---|---|
| CODE | 0000 = request sent to terminal |
| TEXT | Status message |
| SECUREID | Session ID (save this) |
| CANCELURL | URL to cancel the active terminal session (optional use) |
| HOST | N/A - Used for ecommerce transactions only |
| USERFEE | N/A - Used for ecommerce transactions only |
| DATE | Date of the request |
| TIME | Time of the request |
| DUR | Duration 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.
CANCELURLcan 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
SECUREIDfrom the StartSession response. - The same
SECUREIDwill 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
CANCELURLvalue 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 approvedFAILUREURL→ 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
| Field | Description |
|---|---|
| TEXT | APPROVED, DECLINED, VOIDED, or Description of decline |
| CODE | Final result code (refer to status codes below) |
| AMT | Transaction amount |
| SECUREID | Session ID |
| REFNUM | Transaction reference number provided by the terminal |
| REQUESTID | Original request ID |
| INV | Invoice |
| ACK | Y (confirms payment was captured) |
| RECEIPTS | Merchant and Customer copy of receipt from the terminal in HTML |
| REFUND | Y (only included if transaction was a Refund) |
| AUTH | Authorization Code (sent only if transaction was APPROVED) |
| CARDTYPE | Type of card used for the transaction (sent only if transaction was APPROVED) |
| CARDMASK | The masked card number - only last 4 digits available (sent only if transaction was APPROVED) |
| CUSTEMAIL | Customers 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.
| Code | Message | Meaning (StartSession) | Meaning (Final Result) |
|---|---|---|---|
| 0000 | SENT TO TERMINAL / APPROVED | Request sent to terminal | Approved |
| 8500 | PLATFORM FEE NOT ALLOWED | Platform Fee is not allowed; remove it from the request to continue | — |
| 8501 | USER FEE NOT ALLOWED | User Fee is not allowed; remove it from the request to continue | — |
| 8502 | INVALID DEVICEID | DEVICEID is missing or invalid | — |
| 8503 | NO RESPONSE | No response from the terminal | — |
| 8504 | NOT ALLOWED | Request not allowed (terminal settings or details) | — |
| 8505 | NOT CONNECTED | Terminal not connected | — |
| 8506 | NOT FOUND | Device not found | — |
| 8507 | NOT AVAILABLE | Terminal not available | — |
| 8508 | NOT IMPLEMENTED | Not implemented | — |
| 8509 | TERMINAL BUSY | Terminal busy | — |
| 8510 | DECLINED | — | Declined by card issuer |
| 8511 | CANCELLED | — | Cancelled on the terminal |
| 8512 | TERMINAL CONFIG ERR | Terminal configuration error | — |
| 8513 | GATEWAY ERR | — | Gateway error |
| 8514 | DEVICE ERR | — | Device error |
| 8515 | COMMUNICATION ERR | — | Communication error |
| 8516 | UNKNOWN ERR | — | Unknown error |
Recap
Sequence:
- Call StartSession
- If CODE ≠ 0000 → stop (request failed)
- If CODE = 0000 → wait for callback
- Read final result
- If CODE = 0000 → approved
Rules:
REQUESTIDmust be unique per transaction- Always store
SECUREID - Do not treat StartSession response of
0000as success for the transaction; always rely on the final result via callback - Use
REFUNDfor refunds - Use
NOTERMPRINTto disable receipt printing
Mental Model
StartSession = "Request delivered to terminal"
Final Result = "Transaction outcome"
Updated 1 day ago
