This page describes the request and response fields used by the three Embedded Components gateway messages: StartSession, GetResult, and Ack.
Embedded Components uses the same message lifecycle as Customized Checkout, with one extra request parameter — EMBED — and stricter requirements on the return URLs.
For field formats (max length, allowed characters, decimal precision, date formats), see the API Reference.
📘
| Field | Name | Used On | Description |
|---|
TERMID | Terminal ID | All | Identifies the merchant account the transaction belongs to. Assigned by SportsPay and tied to a specific merchant. |
PASS | Password | All | Authenticates the request. Required on every call. |
TYPE | Transaction Type | All | W for all Embedded Components messages. |
ACTION | Action | All | The message being sent: StartSession, GetResult, or Ack. |
REQUESTID | Request ID | StartSession | Unique identifier you generate for this transaction. Must be unique per terminal — the gateway uses it for duplicate protection, so a second StartSession with the same REQUESTID on the same terminal is rejected. Does not appear in reports. |
SECUREID | Secure ID | GetResult, Ack | Session identifier returned by StartSession. Use it to retrieve the result and acknowledge the transaction. |
REFNUM | Reference Number | StartSession (optional), Ack (alternative to SECUREID) | Your internal reference. Must be unique within the batch — if omitted, the gateway assigns one. Fully searchable in reporting. |
| Field | Name | Used On | Description |
|---|
EMBED | Embed Flags | StartSession | One or more letters controlling which visual components render on the embedded page. See the Overview for the full flag list. The B flag is reserved for a future release — leave it out for now. |
| Field | Name | Used On | Description |
|---|
AMT | Amount | StartSession | Transaction amount. If the merchant is CustomerPay-enabled, send AMT and USERFEE as separate fields — the gateway adds them on the hosted page. |
DESC | Description | StartSession | Short description shown on the payment page and searchable in reporting. For example: "U13 Boys Select" or "Fall Tryouts". |
INV | Invoice Number | StartSession | Invoice number shown in reporting and on the payment page. Acts as a transaction tag — does not need to be unique. Groups related transactions together (e.g. a Sale and its Refund, or a declined Sale retried successfully). |
USERFEE | CustomerPay Processing Fee | StartSession (CustomerPay merchants only) | Processing fee passed to the cardholder at checkout. See CustomerPay. |
PLATFEE | Platform Fee | StartSession | Fee added to the transaction and paid by the cardholder. See Platform Billing. |
PLATCHRG | Platform Charge | StartSession | Fee subtracted from the approved transaction amount and paid by the merchant. See Platform Billing . |
PLATFORM | Platform Billing | StartSession | Gateway automatically applies as PLATFEE or PLATCHRG based on the merchant's pricing model. See Platform Billing . |
| Field | Name | Used On | Description |
|---|
CUSTEMAIL | Customer Email | StartSession | Customer email. Searchable in reporting. |
CUSTNAME | Customer Name | StartSession | Customer name. Searchable in reporting. |
CUSTID | Customer Identifier | StartSession (optional) | Your internal customer identifier. When provided, the payment page switches to the Wallet variant, allowing returning customers to select a previously used card instead of re-entering their details. |
| Field | Name | Used On | Description |
|---|
LANG | Language | StartSession | E for English (default) or F for French. Controls the language of the embedded payment fragment. |
| Field | Name | Used On | Description |
|---|
SUCCESSURL | Success Return URL | StartSession | URL loaded inside the iframe after a successful transaction. Must be served from an origin you control so your return page can post the result up to the parent window. Only honored if the terminal has DYNAMICURL enabled. See Return URLs. |
FAILUREURL | Failure Return URL | StartSession | URL loaded inside the iframe after a decline or cancel. Defaults to SUCCESSURL if omitted. Same origin requirement as SUCCESSURL. Only honored if the terminal has DYNAMICURL enabled. See Return URLs. |
| Field | Name | Used On | Description |
|---|
ACK | Acknowledge | GetResult (optional), Ack | Pass ACK=Y on GetResult to capture the transaction in the same call. Otherwise, send a separate Ack message with ACK=Y within 3 minutes of approval, or the transaction will be reversed. |
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 | Used On | Description |
|---|
PROGRAM | Programs | StartSession | 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 | StartSession | 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 | StartSession | 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.
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. Common values: SUCCESS, APPROVED, CAPTURED, REVERSED, DECLINED TEST. |
DATE | Date | Date the response was generated. |
TIME | Time | Time the response was generated. |
DUR | Duration | Request processing duration in seconds. |
| Field | Name | Description |
|---|
SECUREID | Secure ID | Session identifier. Store this on your server — you need it to call GetResult and Ack. |
URL | Embedded Page URL | URL to load in the <iframe> on your checkout page. The gateway renders the payment fragment with the components suppressed according to the EMBED= flags you sent. |
HOST | Gateway Host | Origin of the gateway serving this session. |
USERFEE | CustomerPay Fee | Processing fee that will be added to the amount on the embedded page, for CustomerPay-enabled merchants. Returns 0.00 otherwise. |
| Field | Name | Description |
|---|
AMT | Amount | Base transaction amount. For CustomerPay-enabled merchants, add USERFEE to get the total the customer paid. |
USERFEE | CustomerPay Fee | Processing fee added on the hosted page (CustomerPay only). |
REQUESTID | Request ID | The REQUESTID you sent on StartSession. |
REFNUM | Reference Number | The reference number for this transaction (provided by you on StartSession, or assigned by the gateway). |
CARDTYPE | Card Type | Single-letter card type code (e.g. V for Visa, M for Mastercard). |
CARDMASK | Card Mask | PCI-safe masked card number. |
CARDEXP | Card Expiration | Card expiration date. |
CARDHASH | Card Hash | Tokenized hash identifying the same card across transactions without exposing card data. |
AUTH | Authorization | Authorization number from the card network. Only present on approved transactions. |
TOKEN | Token | Permanent token for reusing this card on future transactions. Only present when card data was processed. |
GATEREF | Gateway Reference | Globally unique identifier for this approved financial transaction. Store it for querying or tracing. Only present on approved financial transactions. |
ACK | Acknowledgement | Y if the transaction was captured (whether via ACK=Y on GetResult or a separate Ack call), N otherwise. |
CUSTNAME | Customer Name | Customer name from StartSession. |
CUSTEMAIL | Customer Email | Customer email from StartSession. |
CUSTID | Customer ID | Customer identifier if passed on StartSession. |
| Field | Name | Description |
|---|
ACK | Acknowledgement | Y if the transaction was captured, N if the capture failed. |
GATEREF | Gateway Reference | Returned when the capture succeeded. |
