Guides
  1. DIRECT WITH EMBEDDED TOKENIZATION

Overview

Direct with Embedded Tokenization gives you full control over the checkout experience. Your platform builds its own payment UI; card data is tokenized in the browser using the InterPay JavaScript library; your server submits the transaction to the gateway with a short-lived token instead of raw card data.

Card data never touches your server, which keeps you out of PCI scope — but you own the UI, validation, branding, and flow. Use this method when the hosted payment pages don't fit your user experience or when you need to embed checkout in a native mobile app.

Note: All Direct transactions must use Embedded Tokenization. SportsPay no longer supports submitting raw card data directly to the gateway from your server.

When to Use Direct with Embedded Tokenization

Use Direct with Embedded Tokenization when you want:

  • Full control over checkout UI, layout, and validation
  • An in-page payment flow without an iframe
  • Native mobile app payment flows
  • Tight integration with your own frontend framework

Use Customized Checkout or Embedded Components instead when the lowest-lift integration is more important than UI control. The hosted methods also ship with a branded, maintained payment page for free, while Direct requires you to build and maintain the checkout UI yourself.

How It Works

Direct with Embedded Tokenization is a three-part flow:

  1. Get an API key. Your server calls GetAPIKey and receives a short-lived APIKEY plus a HOST to load the InterPay JavaScript library from.
  2. Tokenize the card in the browser. Your checkout page loads interpay_embed.min.js from the gateway and calls Interpay.Tokenize() with the cardholder's data. The gateway returns a One-Time Token (OTT) directly to the browser. Card data never reaches your server.
  3. Submit the transaction. Your server submits a Direct Payment request (Sale, Auth, Tokenize, etc.) using the OTT in place of card data. The gateway returns a response immediately — plus a permanent token you can store for future charges.

The OTT must be used within 10 minutes of being issued. After that it expires and you need a fresh one.

Reusing Cards for Future Charges

Every Direct Payment response that processes a card includes a permanent token you can safely store on a customer's profile. Subsequent charges use the permanent token as the card reference — no tokenization step is required.

This covers:

  • Recurring or scheduled billing against a saved card
  • One-click repeat purchases
  • Refunds against a prior transaction
  • Switching a customer between Customized Checkout or Embedded Components for their first payment and Direct for follow-up charges (the permanent token is shared across all three methods)

See Transaction Types for the specific request types that accept a permanent token.

CustomerPay with Direct

For merchants enabled for CustomerPay, USERFEE must be calculated before submitting a Sale.

  • If the customer is entering card data at checkout — Include AMT in your GetAPIKey call. The gateway returns the calculated USERFEE alongside the API key. Display it to the cardholder, then include it in the Sale request along with the OTT.
  • If you're charging a stored permanent token — Call Check UserFee (TYPE=Z&SUBTYPE=UF) with the transaction amount. The gateway returns USERFEE. Display it to the cardholder, then include it in the Sale request.

Either way, both AMT and USERFEE go into the Sale request as separate fields. The cardholder is charged AMT + USERFEE.

See CustomerPay for the broader CustomerPay contract.

Security

Card data flows directly from the browser to the gateway via Interpay.Tokenize(). It never transits your server.

  • Your server handles tokens only — the OTT during checkout, and the permanent token for future charges.
  • Your server calls GetAPIKey — the API key is short-lived and bound to the terminal, so even if it leaks it's useful only for the brief window it's valid.
  • Your browser code calls Interpay.Tokenize() with the API key and card data — the gateway validates the API key, issues the OTT, and sends it back to the browser.

This keeps your platform fully outside PCI scope.

Payment Sequence

flowchart TD
    A[Customer reaches checkout] --> B[Registration platform server calls GetAPIKey]
    B --> C[Gateway returns APIKEY and HOST]
    C --> D[Browser loads InterPay JS and displays payment form]
    D --> E[Customer enters card details]
    E --> F[Browser calls Interpay.Tokenize with APIKEY and card data]
    F --> G[Gateway returns One-Time Token OTT to browser]
    G --> H[Browser passes OTT to registration platform server]
    H --> I[Server submits Direct Payment using OTT]
    I --> J[Gateway processes transaction]
    J --> K[Gateway returns result + permanent token]
    K --> L[Server stores permanent token on customer profile]
    L --> M[Future charges use permanent token directly]

Updated 9 days ago