Embedded Components follows the same three-message lifecycle as Customized Checkout — StartSession, GetResult, and Ack — with two extra front-end pieces: rendering the returned payment URL in an iframe, and handling the return hand-off from the iframe back to your parent checkout page.

All examples below use {gateway_endpoint}/ as a placeholder. Replace it with your target gateway endpoint — see Development & Testing for test endpoints or Production for live endpoints.

Step 1 — StartSession

StartSession initiates a session to set up an embedded payment transaction. It is identical to the Customized Checkout StartSession except that you pass an EMBED= parameter telling the gateway which components to render.

Important: SECUREID is returned in the response — do not send one on the request. Including SECUREID on StartSession will be rejected.

Required parameters

TERMID and PASS — terminal credentials
TYPE=W — Web transaction
ACTION=StartSession
AMT — transaction amount
CUSTEMAIL — customer email
REQUESTID — unique identifier for this transaction. Must be unique per terminal — the gateway rejects a second StartSession with the same REQUESTID on the same terminal, which gives you built-in duplicate protection when retrying.

Embedded Components parameters

EMBED — one or more of W, C, H, I, A, S, P. See the Overview for what each letter suppresses. The B flag is reserved for a future release — leave it out for now so the built-in Pay and Cancel buttons stay visible.
SUCCESSURL — URL loaded inside the iframe on approval. Must be served from an origin you control so that your return page can post the result back up to the parent window.
FAILUREURL — URL loaded inside the iframe on decline or cancel (defaults to SUCCESSURL if omitted).

Optional parameters

LANG — E for English (default) or F for French.
DESC — short description shown on the payment page.
CUSTNAME, CUSTID — customer name and identifier.
REFNUM, INV — your internal reference and invoice numbers.
USERFEE, PLATFEE, PLATCHRG — see CustomerPay and Platform Billing.

For field formats (max length, allowed characters, decimal precision), see the API Reference.

Example request

curl --request POST \
  --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":     "your_termid",
    "PASS":       "your_pass",
    "TYPE":       "W",
    "ACTION":     "StartSession",
    "AMT":        "125.00",
    "CUSTEMAIL":  "[email protected]",
    "REQUESTID":  "1712864923456",
    "DESC":       "U13 Boys Select",
    "LANG":       "E",
    "EMBED":      "WCSP",
    "SUCCESSURL": "https://yoursite.com/checkout/return",
    "FAILUREURL": "https://yoursite.com/checkout/return",
    "JSON":       "Y"
  }'

Example response

{
  "CODE":     "0000",
  "TEXT":     "SUCCESS",
  "SECUREID": "1ef3a4c0-1234-6abc-b6f0-0607737344b4",
  "URL":      "https://svra.interpaypos.com/api/HOSTPYMT/pay/?SecureID=1ef3a4c0-1234-6abc-b6f0-0607737344b4",
  "HOST":     "https://svra.interpaypos.com",
  "USERFEE":  "0.00",
  "DATE":     "20260412",
  "TIME":     "14:23:01",
  "DUR":      "0.412"
}

Store the SECUREID on your server — you need it in Step 4.

Step 2 — Render the payment fragment

On your checkout page, mount the payment fragment using either the SportsPay JavaScript library (coming soon) or by embedding the returned URL directly into an <iframe>. Both methods produce the same result — the gateway serves the embedded payment form with components suppressed as requested by EMBED=. Choose whichever fits your front-end better.

Option A — Embed the URL in an `<iframe>`

Inject the URL from the StartSession response into an <iframe> sized for the payment fragment.

<div id="frame-wrap" style="max-width: 420px; min-height: 500px;">
  <iframe id="payframe"
          title="Payment"
          src="https://svra.interpaypos.com/api/HOSTPYMT/pay/?SecureID=..."
          style="width: 100%; height: 720px; border: 0;">
  </iframe>
</div>

Option B — Mount via the SportsPay JavaScript library - COMING SOON

Coming soon. A JavaScript library will let you mount the payment fragment into a <div> on your page rather than building the iframe yourself. The library handles the iframe injection internally — same PCI boundary, simpler integration. Until it ships, use Option A above.

Once available, the integration will look roughly like this:

<div id="payment-fragment"></div>
<script src="https://svra.interpaypos.com/embed/sportspay.js"></script>
<script>
  SportsPay.mount('#payment-fragment', sessionUrl);
</script>

Regardless of which mount method you use, the customer enters their card details inside the embedded fragment. No card data ever reaches your server or your parent page. The customer submits or cancels the transaction using the Pay and Cancel buttons rendered inside the fragment.

Coming soon. Support for driving the embedded form from your own parent-page buttons (via EMBED=B) is on the roadmap. Until it ships, keep the built-in buttons in place by omitting the B flag from EMBED=.

Step 3 — Handle the redirect inside your return page

When the customer completes (or cancels) the transaction, the gateway redirects the iframe to your SUCCESSURL / FAILUREURL, appending SecureID and Status to the query string. Because the redirect happens inside the iframe, your return page runs inside the embedded frame — not in the top-level window.

Your return page should:

Call GetResult server-side using the SecureID (see Step 4).
Post the result up to the parent window so the outer checkout page can take over.

A minimal return page:

<!DOCTYPE html>
<html>
<body>
<p>Completing…</p>
<script>
  // Result JSON rendered server-side after calling GetResult
  var data = <?= json_encode($result) ?>;
  if (window.parent && window.parent !== window
      && typeof window.parent.onEmbedPayResult === 'function') {
    window.parent.onEmbedPayResult(data);
  }
</script>
</body>
</html>

In your parent checkout page, define onEmbedPayResult to close the iframe and render the outcome:

window.onEmbedPayResult = function (payload) {
  document.getElementById('frame-wrap').style.display = 'none';
  var ok = payload && (payload.approved === true || String(payload.code) === '0000');
  // update your UI with payload.message, payload.refnum, etc.
};

Warning: Do not send a GetResult message until after the iframe has been redirected to your Return URL. Calling GetResult before the customer has completed payment will cancel the session.

Step 4 — GetResult

GetResult retrieves the outcome of the transaction after the customer has completed their actions in the embedded payment fragment.

Required parameters

TERMID, PASS
TYPE=W
ACTION=GetResult
SECUREID — the value returned in Step 1

Optional

ACK=Y — combines the acknowledgement into this call (recommended). When set, the transaction is captured as part of this response and you can skip Step 5.

Example request

curl --request POST \
  --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":   "your_termid",
    "PASS":     "your_pass",
    "TYPE":     "W",
    "ACTION":   "GetResult",
    "SECUREID": "1ef3a4c0-1234-6abc-b6f0-0607737344b4",
    "ACK":      "Y",
    "JSON":     "Y"
  }'

Example response

{
  "CODE":      "0000",
  "TEXT":      "APPROVED",
  "SECUREID":  "1ef3a4c0-1234-6abc-b6f0-0607737344b4",
  "CARDTYPE":  "V",
  "CARDMASK":  "************1111",
  "CARDEXP":   "1229",
  "AMT":       "125.00",
  "USERFEE":   "0.00",
  "REQUESTID": "1712864923456",
  "REFNUM":    "102512003U13BOYS",
  "AUTH":      "T12345",
  "TOKEN":     "4xxxxxxxxxxx1111",
  "GATEREF":   "20260412-000182",
  "ACK":       "Y",
  "CUSTNAME":  "Sample Customer",
  "CUSTEMAIL": "[email protected]",
  "DATE":      "20260412",
  "TIME":      "14:24:17",
  "DUR":       "0.308"
}

For CustomerPay-enabled merchants, the AMT returned here is the base transaction amount and USERFEE is the processing fee added on the hosted page. The total the customer paid is AMT + USERFEE.

Important: Always check that the GetResult response returns ACK=Y if you passed ACK=Y in the call. If ACK comes back as N, the transaction has not been captured and you must resolve it before the session times out.

Step 5 — Acknowledge (Ack)

Send an Ack message only if you did not pass ACK=Y in Step 4. If no acknowledgement is received within 3 minutes of the transaction being approved, the gateway will automatically reverse the transaction.

Required parameters

TERMID, PASS
TYPE=W
ACTION=Ack
SECUREID or REFNUM
ACK=Y

Example request

curl --request POST \
  --url {gateway_endpoint}/ \
  --header 'Content-Type: application/json' \
  --data '{
    "TERMID":   "your_termid",
    "PASS":     "your_pass",
    "TYPE":     "W",
    "ACTION":   "Ack",
    "SECUREID": "1ef3a4c0-1234-6abc-b6f0-0607737344b4",
    "ACK":      "Y",
    "JSON":     "Y"
  }'

Example response

{
  "CODE": "0000",
  "TEXT": "CAPTURED",
  "ACK":  "Y",
  "DATE": "20260412",
  "TIME": "14:26:12",
  "DUR":  "0.087"
}

The transaction is now captured and the session is closed. Your parent checkout page can continue its normal post-payment flow.

Step 1 — StartSession

Step 2 — Render the payment fragment

Option A — Embed the URL in an <iframe>

Option B — Mount via the SportsPay JavaScript library - COMING SOON

Step 3 — Handle the redirect inside your return page

Step 4 — GetResult

Step 5 — Acknowledge (Ack)

Option A — Embed the URL in an `<iframe>`