Parameter Descriptions
This page describes the request and response fields used by Direct with Embedded Tokenization.
For which fields are required by each transaction type, see Transaction Types.
For complete field specifications — max length, allowed characters, decimal precision, date formats, and response fields — see the API Reference entry. Each Direct Payment endpoint has a dedicated reference page that documents every request and response field in full.
Request Fields
INV,REF,DESC,PROGRAM,PLAYER, andACCOUNTcan be used together to make transactions easily searchable and reconcilable in PaymentsHQ.
Identification
Field | Name | Description |
|---|---|---|
| Terminal ID | Identifies the merchant account the transaction belongs to. Assigned by SportsPay and tied to a specific merchant. |
| Password | Authenticates the request. Required on every call. |
| Transaction Type | Single letter identifying the transaction. See Transaction Types —
|
| Reference Number | Your reference for this transaction. Must be unique within the batch — if omitted on transactions that accept it, the gateway assigns one. Fully searchable in reporting. For Void / Refund / Refund Void and Force Post, |
| Authorization Number | The authorization number from a previous Auth Only, required when submitting a Force Post. |
| Card Token | The card identifier for the transaction. Accepts either a One-Time Token (OTT) from Embedded Tokenization or a permanent token returned by a previous transaction. The gateway handles both the same way — you don't need to tell it which kind you're sending. |
Transaction type=
Zis used for administrative calls such asGetAPIKey- refer to the Check UserFee Api Reference
Transaction Details
| Field | Name | Description |
|---|---|---|
AMT | Amount | Transaction amount. If the merchant is CustomerPay-enabled, send AMT and USERFEE as separate fields — the cardholder is charged AMT + USERFEE. |
USERFEE | CustomerPay Processing Fee | Processing fee passed to the cardholder at checkout. Required on Sale, Force Post, Pre-Auth, and Completion when the merchant is CustomerPay-enabled. See CustomerPay. |
PLATFEE | Platform Fee | Fee added to the transaction and paid by the cardholder. See [Platform Billing]. |
PLATCHRG | Platform Charge | Fee subtracted from the approved transaction amount and paid by the merchant. See Platform Billing. |
PLATFORM | Platform Billing | Gateway automatically applies as PLATFEE or PLATCHRG based on the merchant's pricing model. See Platform Billing . |
INV | Invoice Number | Invoice number shown in reporting. Acts as a transaction tag — does not need to be unique. Groups related transactions together (e.g. a Sale and its Refund). |
DESC | Description | Short description for reporting and receipts. |
Customer Information
| Field | Name | Description |
|---|---|---|
CUSTEMAIL | Customer Email | Customer email. Searchable in reporting. |
CUSTNAME | Customer Name | Customer name. Searchable in reporting. |
CUSTID | Customer Identifier | Your internal customer identifier. |
Reconciliation Detail (Optional)
These structured fields appear in the Deposit Report and let you split a single transaction into categories for reconciliation. Each can be sent independently or in combination — include all, some, or none.
| Field | Name | Description |
|---|---|---|
PROGRAM | Programs | Program- or fee-level detail. Each entry includes a Name (program description) and AMT. Entries are evaluated independently; if totals don't match the transaction amount, the remainder is assigned to an "Uncategorized" entry. |
PLAYER | Players | Player- or participant-level detail. Each entry includes an id (player identifier, name, or internal ID) and AMT. Same totalling rules as PROGRAM. |
ACCOUNT | Accounts | Account-level allocation (e.g. HST, Operating Account, Savings). Each entry includes a DESC and AMT. Same totalling rules as PROGRAM. |
For structured-field syntax (nested brackets in tag/value or arrays in JSON), see the API Reference.
Response Fields
Standard Envelope
These fields appear on every response. See Technical Specifications for the full envelope definition.
| Field | Name | Description |
|---|---|---|
CODE | Response Code | Four-digit result code. 0000 = success; any other value indicates a decline, validation error, or gateway issue. |
TEXT | Response Text | Human-readable result message. For approved transactions, includes the authorization number and approved amount. Common values: APPROVED 123456, KEY GENERATED, DECLINED TEST. |
DATE | Date | Date the response was generated. |
TIME | Time | Time the response was generated. |
DUR | Duration | Request processing duration in seconds. |
GetAPIKey Response
| Field | Name | Description |
|---|---|---|
APIKEY | API Key | Short-lived API key your browser passes to Interpay.tokenize() to tokenize card data. Valid for the current checkout only — do not cache or reuse. |
HOST | JavaScript Host | Origin your browser loads interpay_embed.min.js from. Always use the returned value rather than hard-coding a URL — the filename differs between test and production. |
USERFEE | CustomerPay Fee | Calculated processing fee for this transaction if you sent AMT and the merchant is CustomerPay-enabled. Display this to the cardholder and include it in your Sale request. Returns 0.00 otherwise. |
Transaction Response
| Field | Name | Description |
|---|---|---|
AUTH | Authorization | Authorization number from the card network. Only present on approved transactions. Required as an input when submitting a later Force Post. |
TOKEN | Permanent Token | Reusable token identifying this card. Safe to store on a customer profile and pass back in future TOKEN fields to charge the same card. Only present when card data was processed. |
HASH | Card Hash | Tokenized hash identifying the same card across transactions without exposing card data. Useful for deduplication or fraud-screening against prior activity. |
GATEREF | Gateway Reference | Globally unique identifier for this approved financial transaction. Store it for querying or tracing. Only present on approved financial transactions. |
CARDTYPE | Card Type | Single-letter card type code (V Visa, M Mastercard, A Amex, D Discover). |
CARDMASK | Card Mask | PCI-safe masked card number. |
CARDEXP | Card Expiration | Card expiration date. |
Settlement Response
| Field | Name | Description |
|---|---|---|
START | Batch Start | Timestamp of the first transaction in the settled batch. |
COUNT | Transaction Count | Number of transactions in the settled batch. |
BATCHSIZE | Batch Size | Total dollar amount of the settled batch. |
DETAIL | Batch Detail | Per-transaction breakdown of the settled batch. |
Updated 12 days ago