Version 1.0.3
Overview
This document explains how Mint’s One-Time Token (OTT) service secures credit card payments. Rather than storing or sending card details directly to the merchant’s server, the OTT JavaScript intercepts the payment form and sends sensitive data to Mint. Mint then provides a single-use token (OTT) back to the merchant’s front-end. The merchant subsequently submits that OTT (instead of raw card data) to Mint’s Mpay API for payment processing. This prevents raw card details from passing through or being stored on the merchant’s system, enhancing security and PCI compliance.
NOTE The OTT service is for tokenising credit / debit cards only, and is not applicable for
tokenising other payment types such as Alternate Payment Methods (APM’s).
The OTT is not a standalone API – the implementation is via the Web Services API which will be used
to transmit and process the payment.
The OTT library is a Javascript plugin written with pure Javascript and without any css or third party
library dependencies. The plugin will generate a payload value (OTT) from the Payment Gateway
tokenisation service based on encrypted card information. The merchant can then pass the OTT
through to the Web Services API. Note, each token can only be used once and each token expires
once it has been processed via the Web Services API or 1 hour ofter being created and not being used.
Process Flow
- Customer attempts a purchase, and requests the payment form hosted on the merchants website.
- Merchant website returns the form to the customers web browser.
- Customer enters card information into the payment form displayed in their web browser and clicks submit.
- The OTT Javascript either intercepts the form submission or is triggered manually by the merchants custom Javascript and submits the card information directly to the OTT Service from the customers web browser.
- The OTT service stores the card information in the Payment Gateway and returns a single use token to the web browser.
- The customers web browser submits the OTT to the merchant’s payment form. (Note: plain text card data must not be submitted (e.g.: card number, expiry, CVV) nor will be accepted.)
- The merchant’s payment form submits the OTT and additional information such as customer billing, shipping information and product information to the Mpay API. (Note: plain text card data must not be submitted (e.g.: card number, expiry, CVV) nor will be accepted.)
- 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 then displays a receipt or error message to the customer.
Hosted Javascript
Please use the appropriate URL for the mint hosted one time token JavaScript depending on the environment you’re integrating with:
Environment Value
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 one time token 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]
Sample Use
Step 1. Generate the OTT on the frontend
Method #1: onSubmit() Handler Implementa9on
IMPORTANT
The fields for collecting data (cc-pan,cc-cvv,cc-expmonth,cc-expyear) MUST NOT have the 'name' attribute. This will prevent 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"/>
<!--// Not Required to be Sent with Payment Information - For Merchant Information/Use Only --> <input type="hidden" id="cc-pan-bin" name="cc_bin"/>
<input type="submit" id="submit" value="Pay">
<p>Pressing the 'PAY' button, The payload field is populated by the One Time Token library. Once populated, the form is then posted to merchants script located at path/to/merchant/submit_action.php where the merchant can make a request to the Web Services API with the One Time Token, and additional customer information such as customer details, shipping address, product information etc.</p>
<p>Additional Fields can be added here to capture customer details</p>
<br/>
<hr/>
<h1>Errors raised by the One Time Token library (if any) will appear below</h1>
<div id="cc-errors"></div>
<hr/>
</form>
</body>
</html>
On form submit, the one time token payload will be available in the cc_payload field.
Method #2: getPayload() Implementa9on
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) { console.log(response); if(response.payload) {
// grab the payload to submit with other payment information document.getElementById('cc-payload').value = response.payload;
// grab the first 6 digits of the Card Number(BIN)
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'; console.log(message);
}
alert(message);
}
} );
return false;
}
| Option Name | Description | Required |
|---|---|---|
| cc-pan | The full card number | optional - required if cc-expmonth or cc-expyear is set or not an empty string |
| 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 or not an empty string |
| cc-expyear | Card Expiry year (2 Digits) | optional - required if cc-pan or cc-expmonth is set or not an empty string |
| merchantKey | The merchant Authentication Key for the OTT service. | mandatory - always required |
2. Make payment with the Mpay API Request
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 https://mintmpayv5.docs.apiary.io/#reference/restful-apireference/transaction-token/request-transaction-token for more details.
And then perform the purchase using the one time token payload e.g.
{
"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,
"should_mint_apply_surcharge": false,
"currency": "AUD"
}
}
See: https://mintmpayv5.docs.apiary.io/#reference/restful-apireference/purchase for more details and options on the purchase request.
Appendix: Error Codes
Possible Client Side Error Responses and Codes
Possible Client Side error responses and codes that can be generated from the OTT library:
| Error Code | Error Text/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. |
Possible OTT Service Response Errors and Codes
These will be returned via the OTT library if they occur:
| Error Code | Error Text/Description |
|---|---|
| 100010 | You are not authorised to access this service for this account |
Integration Best Practice
In order to minimize the changes required to your integration and the potential impact future API
changes to your integration would have, we strongly recommend the following:
- Stay informed by periodically checking the change log of the latest API version
- Keep your integration in line with the latest API changes as much as possible
- Raise undocumented API behavior with your account manager
- Implement reconciliation processes to handle uncertain results
- Periodically test your integration against the test environment
- Monitor the relevant contact channels established with your account manager regarding non
backwards-compatible changes