This page will help you get started with Mint mPay API Reference - v5.
Getting Started
This page will help you get started with Mint mPay API Reference - v5.
Table of Contents
- Introduction
- Intended Audience
- Integration Models
- Environments
- Sandbox Test Cards
- Authentication
- Authorization
- Company Identifiers
- Surcharging and Market Variability
- Transaction Status
- Errors & Status Codes
- Versions
Introduction
Welcome to the Mint Payments developer portal. You'll find here instructions and documentation to help you start the integration with our API.
Mint mPay API fully supports REST. To use a REST API, your application needs to make an HTTP request and process the response. The response format is JSON.
Intended Audience
This documentation is intended for teams responsible for designing, implementing, and operating payment flows that process customer payments via Mint, including:
- Travel businesses
- Independent Software Vendors (ISVs)
- Platforms and marketplaces
- Mid-office, ERP, and back-office system providers
- Enterprise engineering and payments teams
It assumes the reader is familiar with:
- REST APIs
- Webhooks and asynchronous event processing
- Payment authorisation and settlement concepts
- PCI DSS fundamentals
Integration Models
Mint supports three distinct integration models, each designed to address different trade-offs between user experience control, implementation complexity, compliance scope, and operational responsibility.
| Integration Model | Best For | PCI Scope | UI Control | Complexity |
|---|---|---|---|---|
| Hosted Payment Pages (HPP) | Invoices, payment links | Minimal | Mint | Low |
| Embedded One Time Token | Branded checkout | Low | Partner | High |
| Direct API Integration | ERP / billing platforms | High | Partner | High |
Payment links (Hosted Payment Page)
A Mint-hosted payment experience where customers complete payment on a secure Mint page accessed via a link. This is the fastest integration path with the lowest PCI compliance scope.
Embedded One Time Token
An embedded integration model where card details are tokenised in the customer's browser This enables a fully branded checkout experience while keeping PCI scope low. This uses Mint-provided JavaScript, producing a single-use token for payment processing. This needs to be used in conjunction with our Direct API integration.
Direct API Integration
A fully programmatic integration model where partners orchestrate the full payment lifecycle — payment creation, authorisation, capture, reconciliation, and refunds — directly via Mint APIs. This carries the highest PCI compliance burden unless you also use Embedded one time token.
Recommended Reading
If you are integrating for the first time:
- Use Hosted Payment Pages for the fastest implementation
- Use Embedded One Time Token if you require a branded checkout experience
- Use Direct API Integration if your system must orchestrate the full payment lifecycle
Continue to the page corresponding to your chosen integration model.
Environments
| Environment | URL | Purpose |
|---|---|---|
| Sandbox | https://secure-uatsb.mintpayments.net/mpay/ | Development and integration testing |
| Production | https://secure.mintpayments.com/mpay/ | Live transactions |
Note: The Sandbox environment (
secure-uatsb) is available for initial development and integration testing.
Sandbox Test Cards
Use the following test cards in the Sandbox environment. Any future expiry date and any 3-digit CVV (4-digit for Amex) are accepted.
| Card Number | Brand | Outcome |
|---|---|---|
4000 0000 0000 0259 | Visa | Approved |
5100 0000 0000 0259 | Mastercard | Approved |
3782 8224 6310 005 | Amex | Approved |
4000 0000 0000 0002 | Visa | Declined (generic) |
4000 0000 0000 9995 | Visa | Declined (insufficient funds) |
4000 0000 0000 9979 | Visa | Declined (stolen card) |
For the full list of test cards and APM simulation options, see the RESTful API Reference.
Authentication
mPay uses API keys to uniquely authenticate requests. Your API key will be issued by Mint during the onboarding process. Your API keys are very important as using them will allow you to interact with mPay. Please make sure that you store the API keys with caution and never share them publicly to third parties.
API keys must be included in the request header:
Authorization: Bearer {your-api-key}
API keys must never be exposed in client-side code.
Authorization
Using the API key, mPay will allow you to obtain a transaction token.
Transaction Token is issued by mPay for single use only. Once a token is used it will be invalidated and cannot be used anymore. If e.g. your 'purchase' transaction timed out for some reason, you need to request a new token before retrying the 'purchase' again. Calling mPay with the same token twice will result in an error.
Company identifiers
Mint identifies clients via 2 key identifiers
The Company Token & The business unit ID
Company Token
The Company Token is an alphanumeric identifier issued by Mint during onboarding. It uniquely identifies your business within the mPay platform and must be passed as a body parameter on most API requests (e.g. token.company_token or company_token).
Unlike the API Key (which authenticates the HTTP request via the Authorization header), the Company Token identifies which merchant account the operation applies to and is included in the JSON request body.
Business unit ID
The business unit ID is issued by the Mint team and is an additional identifier for companies & is required on newer APIs. It is intended to link merchants across Mint products.
Note: Both the company token & business unit ID are unique per environment, new ones will need to be issued on moving into production.
Surcharging and Market Variability
Mint operates across multiple jurisdictions. Some markets permit payment surcharging, while others prohibit it entirely.
As a result:
- Surcharging behaviour is not universal
- The presence, calculation, and display of surcharges depend on:
- Local regulatory rules
- Merchant configuration
- The chosen integration model
For detailed surcharging guidance, see Handling Surcharges & Calculations.
Transaction Status
Many endpoints will return transaction status. The following table lists all transaction outcomes:
| Status | Description |
|---|---|
APPROVED | Transaction was approved by the bank |
DECLINED | Transaction was declined by the bank |
FAILED | Transaction failed |
REQUIRES_AUTHENTICATION (3DS only) | User needs to complete authentication (e.g. OTP) in order to proceed with transaction |
PRE_AUTHORISED | Transaction is pre-authorised. Bank will put a hold on the funds |
PRE_AUTHORISED_REVERSED | Pre-authorisation is released/reversed/cancelled. Bank will release hold on the authorised amount |
PENDING | Transaction is pending final confirmation |
Errors & Status Codes
For full details on HTTP status codes, response formats, example payloads, and the complete list of Mint-specific error codes, see Understanding Error Codes.
Versions
mPay, as all common APIs, uses versioning to guarantee seamless version upgrades and backward compatibility.
What is the current version?
The current version of mPay is 5.0