Embedding Payments with One Time Tokens

Overview
Where Embedded One Time Tokens Fit
PCI Compliance Characteristics
Responsibilities and Control Boundaries
Surcharging Behaviour
Payment Flow
Hosted JavaScript
Understanding the One Time Token Key
Step 1: Generate the Token on the Frontend
Step 2: Submit Payment via the Mpay API
Webhooks and Payment Confirmation
Frontend Failure Handling
Appendix: Error Codes
Best Practices

Overview

Mint's Embedded One Time Token service secures credit card payments by ensuring sensitive card data never passes through or is stored on the merchant's system. The OTT JavaScript intercepts the payment form in the customer's browser and sends card data directly to Mint. Mint returns a single-use token (OTT) to the merchant's front-end. The merchant then submits that token — instead of raw card data — to Mint's Mpay API for payment processing.

This enhances security and significantly reduces PCI compliance scope.

NOTE: The Embedded One Time Token service is for tokenising credit / debit cards only, and is not applicable for tokenising other payment types such as Alternate Payment Methods (APMs).

IMPORTANT — No Long-Term Tokenisation: The Embedded One Time Token model is designed for single-use, transactional tokenisation only. Each token can be used once and expires after being processed, or 1 hour after creation if unused. This integration path does not support long-term card-on-file tokenisation or stored card workflows. If you require persistent card tokens for recurring payments or repeat purchases, use the Direct API integration with store_card_permission enabled, or tokenise via the Hosted Payment Page with storeCardPermission.

The OTT is not a standalone API — the implementation is via the Web Services API which is used to transmit and process the payment.

The OTT library is a JavaScript plugin written in pure JavaScript with no CSS or third-party library dependencies. It generates a payload value (OTT) from the Payment Gateway tokenisation service based on encrypted card information, which the merchant passes through to the Web Services API.

Where Embedded One Time Tokens Fit

The Embedded One Time Token is one of three integration models supported by Mint Payments. It enables partners to embed a payment experience within their own application while ensuring sensitive card data does not enter partner-controlled systems.

This model balances user experience control with reduced PCI compliance scope.

It is commonly used by platforms, booking engines, and commerce applications that require a fully branded checkout experience but do not want to handle raw card data.

Integration Model	PCI Scope	UI Control
Hosted Payment Pages (HPP)	Minimal	Mint
Embedded One Time Token	Low	Partner
Direct API Integration	High	Partner

PCI Compliance Characteristics

The Embedded One Time Token model significantly reduces PCI DSS scope compared to direct card handling, provided it is implemented correctly.

Key characteristics:

Card data is collected in the customer's browser
Tokenisation occurs immediately using Mint-provided JavaScript
Partner servers receive only non-sensitive, single-use tokens
Cardholder data does not traverse partner backend systems

If raw card data is ever transmitted to partner systems, PCI scope increases materially and the integration no longer qualifies as an Embedded One Time Token integration.

Partners must ensure that raw card data is never logged, transmitted, or stored outside the browser context.

Responsibilities and Control Boundaries

Mint is responsible for:

Providing secure JavaScript libraries for card tokenisation
Securely handling and storing cardholder data
Determining card characteristics required for processing
Calculating Mint-applied surcharges when enabled
Executing payment authorisation and capture
Reporting definitive payment outcomes via webhooks

The integrating partner is responsible for:

Rendering the checkout experience
Collecting card details in the browser using Mint JavaScript
Ensuring card data does not reach partner backend systems
Managing frontend validation and UX
Orchestrating backend payment flows
Displaying customer-visible totals where applicable
Reconciling completed transactions

Surcharging Behaviour

The Embedded One Time Token model supports both Mint-applied surcharging and partner-applied surcharging, but the responsibilities differ from Hosted Payment Pages.

Key distinctions:

Mint does not render a hosted UI in this model
Mint does not automatically display surcharges to the customer
The integrating partner controls the checkout interface and must decide what is displayed

For a comprehensive explanation of surcharging concepts, see Handling Surcharges & Calculations.

Mint-Applied Surcharging

When Mint-applied surcharging is used:

The integrating partner supplies a base sale amount
Mint calculates any applicable surcharge based on merchant configuration
Mint exposes surcharge and total values via the surcharge calculation API
The integrating partner is responsible for displaying the surcharge and total to the customer

Important constraints:

The surcharge calculation API is a server-side API
It must not be called directly from browser-side code
Raw card details must never be transmitted from the browser to the partner backend

Partner-Applied Surcharging

Partners may choose to apply their own surcharge instead of using Mint-applied surcharging.

In this model:

The partner calculates the surcharge independently
The surcharge is embedded in the sale amount submitted to Mint
Mint treats the full amount as the sale amount
No surcharge is calculated or reported by Mint

When using partner-applied surcharging:

Mint-applied surcharging should be suppressed (set should_mint_apply_surcharge to false)
The partner is fully responsible for pricing logic and customer disclosure
The partner must ensure totals displayed match the submitted sale amount

Tokenisation vs Surcharge Calculation

It is important to distinguish clearly between tokenisation and surcharge calculation:

Card tokenisation occurs via Mint-provided JavaScript in the browser
The surcharge calculation API does not tokenise cards
The surcharge calculation API does not create or return reusable tokens

Payment Flow

Typical Flow

Customer enters card details into embedded payment fields
Mint JavaScript tokenises the card in the browser
A single-use token (OTT payload) is returned to the partner application
The partner backend receives the token
(Optional) The partner calls the surcharge calculation API
The partner displays applicable surcharge and total to the customer
The partner creates a purchase using Mint APIs
Mint authorises and captures the payment
Mint sends a webhook confirming the final outcome

Detailed Process

Customer attempts a purchase and requests the payment form hosted on the merchant's website
Merchant website returns the form to the customer's web browser
Customer enters card information into the payment form and clicks submit
The OTT JavaScript intercepts the form submission (or is triggered manually) and submits the card information directly to the OTT Service from the customer's web browser
The OTT service stores the card information in the Payment Gateway and returns a single-use token to the web browser
The customer's web browser submits the OTT to the merchant's payment form (plain text card data must not be submitted)
The merchant's payment form submits the OTT and additional information (billing, shipping, product info) to the Mpay API (plain text card data must not be submitted)
The Payment Gateway retrieves the card information assigned to the token and submits to the acquirer for processing. The OTT is then purged.
The Mpay API provides a response to the merchant's payment form (success or failure)
The merchant's payment form displays a receipt or error message to the customer

Hosted JavaScript

Use the appropriate URL for the Mint-hosted one-time token JavaScript depending on the environment:

Environment	URL
Sandbox	`https://hpp-uatsb.mintpayments.net/resources/js/original/ott-mint-sandbox.js`
Production	`https://hpp.mintpayments.com/resources/js/ott-mint.js`

Understanding the One Time Token Key

The one-time token key is required ahead of processing requests. This key is given by Mint to the merchant or developer during onboarding.

If you have not received a one-time token key, please contact [email protected].

Step 1: Generate the Token on the Frontend

Method #1: onSubmit() Handler Implementation

IMPORTANT: The fields for collecting data (cc-pan, cc-cvv, cc-expmonth, cc-expyear) MUST NOT have the name attribute. This prevents these fields from being submitted with the form. The contents of these elements should NOT be posted or stored on your payment form or website/application under any circumstances. Doing so is in breach of acceptable use and will lead to failure in processing.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Mint Demo One Time Token</title>
    <script src="{{mint hosted one time token JavaScript}}" type="text/javascript"></script>
</head>
<body>
<form action="https://localhost/processTransaction" method="post"
      onSubmit="return ottcc.handleForm('{{one time token key}}');">
    <p>The following fields have no 'NAME' property set.</p>
    <input type="text" value="4000000000000010" id="cc-pan" size="25"/>
    <label for="cc-pan"> Card Number</label>
    <br/>
    <input type="text" value="12" id="cc-expmonth" size="2"/>
    <label for="cc-expmonth"> Expiry Month</label>
    <br/>
    <input type="text" value="24" id="cc-expyear" size="2"/>
    <label for="cc-expyear"> Expiry Year</label>
    <br/>
    <input type="text" value="123" id="cc-cvv" size="4"/>
    <label for="cc-cvv">CVV</label>
    <br/>
    <input type="hidden" id="cc-payload" name="cc_payload"/>
    <input type="hidden" id="cc-pan-bin" name="cc_bin"/>
    <input type="submit" id="submit" value="Pay">
</form>
</body>
</html>

On form submit, the one-time token payload will be available in the cc_payload field.

Method #2: getPayload() Implementation

IMPORTANT: The fields for collecting data (cc-pan, cc-cvv, cc-expmonth, cc-expyear) MUST NOT be submitted, transmitted, posted, or stored on your payment form or website/application under any circumstances. Doing so is in breach of acceptable use and will lead to failure in processing.

function getThePayload() {
    var form_data = {};
    form_data['cc-pan'] = document.getElementById('cc-pan').value;
    form_data['cc-cvv'] = document.getElementById('cc-cvv').value;
    form_data['cc-expmonth'] = document.getElementById('cc-expmonth').value;
    form_data['cc-expyear'] = document.getElementById('cc-expyear').value;
    form_data['merchantKey'] = 'XXXXXXXXXXXX';

    ottcc.getPayload(
        form_data,
        function (response) {
            if (response.payload) {
                document.getElementById('cc-payload').value = response.payload;
                document.getElementById('cc-pan-bin').value = response.cc_pan_bin;
                // Other merchant logic...
            } else {
                var message = 'There were ' + response.error.length + ' errors.\n';
                for (var i = 0; i < response.error.length; i++) {
                    message = message + '(error code: ' + response.error[i].errorCode + ') '
                            + response.error[i].errorMessage + '\n';
                }
                alert(message);
            }
        }
    );
    return false;
}

Option Name	Description	Required
`cc-pan`	The full card number	Optional — required if `cc-expmonth` or `cc-expyear` is set
`cc-cvv`	Card CVV number	Mandatory — always required
`cc-expmonth`	Card expiry month (2 digits)	Optional — required if `cc-pan` or `cc-expyear` is set
`cc-expyear`	Card expiry year (2 digits)	Optional — required if `cc-pan` or `cc-expmonth` is set
`merchantKey`	The merchant authentication key for the OTT service	Mandatory — always required

Step 2: Submit Payment via the Mpay API

On your backend server, use the Mpay APIs to make a transaction request using the one-time token payload.

First, make a request to /mpay/v5/transaction_token to get a transaction token. See the RESTful API Reference for more details.

Then perform the purchase using the one-time token payload:

{
  "token": {
    "company_token": "{{mPay API company_token}}",
    "transaction_token": "{{transaction token from previous request}}"
  },
  "customer": {
    "reference": "123456789",
    "email": "[email protected]",
    "accepted_terms_conditions": "true",
    "ip_address": "123.123.1.123",
    "timezone": "Australia/Sydney",
    "store_card_permission": false,
    "should_mint_apply_authentication": false,
    "authentication_redirect_url": ""
  },
  "card": {
    "ott_payload": "{{one time token payload from step 1}}",
    "holder_name": "John Doe"
  },
  "purchase": {
    "invoice_number": "5234234-John-Doe",
    "amount": 100.00,
    "should_mint_apply_surcharge": false,
    "currency": "AUD"
  }
}

See the RESTful API Reference for more details and options on the purchase request.

Webhooks and Payment Confirmation

For the Embedded One Time Token integration, the synchronous API response is the primary source of payment outcome. The API response confirms whether the transaction was approved, declined, or requires further action.

Webhook notifications complement the API response and are useful for updating systems that may not have received the direct response — such as fulfilment platforms, accounting systems, or notification services.

Webhook notifications include:

Payment success or failure
Final charged amount
Any Mint-applied surcharge
Transaction identifiers required for reconciliation

Do not rely on frontend state to determine payment outcomes. Always use the API response or webhook data. See Receiving Webhook Notifications for full details.

Frontend Failure Handling

Tokenisation failures may occur in the browser due to invalid card data, JavaScript execution errors, or network failures.

These failures must be handled entirely by the partner's frontend application
No webhook is emitted for tokenisation failures because no payment attempt occurs
Frontend systems must detect tokenisation failures and prevent submission of invalid tokens to backend systems

Backend Failure Handling

Payment execution failures occur after a token is submitted to Mint APIs.

Failures are communicated via the synchronous API response
Retry logic must use idempotency keys and must not reuse expired or invalid tokens

Appendix: Error Codes

Client-Side Error Responses

Error Code	Error Description
`1`	Card number is invalid
`2`	CVV is invalid
`4`	Expiry date is invalid
`8`	Invalid Input (positive number expected)
`16`	Communications failure. Server returned an empty response.
`32`	Communications failure. Response from server could not be parsed.
`64`	Communications failure. Failed to establish communications.
`0`	An unexpected error occurred. We are unable to process your request
`10011`	Could Not Retrieve Token. Token not found
`10021`	Failed to generate after X attempts
`10003`	The Merchant Token Service Auth Key provided is invalid. We could not locate what you are looking for
`10004`	Unable to generate a unique Merchant ServiceToken AuthKey after X attempts
`128`	Communications failure. Unexpected response.

OTT Service Response Errors

Error Code	Error Description
`100010`	You are not authorised to access this service for this account

Best Practices

Monitor the relevant contact channels established with your account manager regarding non-backwards-compatible changes
Periodically test your integration against the test environment
Implement reconciliation processes to handle uncertain results
Raise undocumented API behaviour with your account manager
Keep your integration in line with the latest API changes as much as possible
Stay informed by periodically checking the change log of the latest API version
Never transmit raw card data to partner backend systems
Never call the surcharge calculation API directly from client-side code
Use Mint-calculated values when Mint-applied surcharging is enabled
Suppress Mint-applied surcharging if partner-applied surcharging is used

Embedding Payments with One Time Token (OTT)