Developer Guide: Mint Payments Payment Links

A comprehensive integration guide for creating, processing, and verifying transactions using Mint Payments Payment Links.

This guide provides step-by-step instructions for integrating with the Mint Payments API to create payment links, allow customers to pay, and receive transaction notifications.

The Payment Link Lifecycle

The integration process follows a simple, three-step lifecycle:

Create The Link (Server-to-Server API call): Your server makes a request to the Mint API to generate a unique payment link.
Customer Pays (On Mint's Hosted Payment Page): The customer uses the link to access a secure payment page and complete the transaction.
Get Notification (Via Webhook): Mint's server sends a notification to your server to confirm the transaction's outcome.

Step 1: Create The Payment Link

Your server makes a secure, server-to-server POST request to the Mint API. This call includes the amount, currency, and your internal order ID or booking terence.

For more detailed information, refer to the official Mint Payments API documentation: Create a Payment Link

Endpoint: POST https://secure.mintpayments.com/mpay/v5/payment-links

Customer Information (Optional)

Including the customer object is highly recommended:

With Customer Info: The payment form is pre-populated, leading to a better user experience and higher conversion rates.
Without Customer Info: The customer must enter all their details manually on the payment page.

Payment Link Modes (In Response)

The API response will contain two different URLs for two different use cases:

url (Standard Mode): This is the customer-facing link. It's designed for self-service, supports all payment methods (including digital wallets and 3D Secure), and is what you should send to your customer.
virtual_terminal_url (VT Mode): This is an agent-assisted link for your staff to process payments manually (e.g., for phone orders). It disables customer-interactive methods.

Step 2: Customer Pays

This part of the process is handled entirely by Mint's Hosted Payment Page (HPP).

Send Link: Your system receives the url from the API response and sends it to the customer (via email, SMS, invoice, etc.).
Pay on HPP: The customer opens the link, sees Mint's secure payment page (pre-populated if you sent customer data), and enters their payment details.
Get Confirmation: Mint processes the payment, handles 3D Secure (if needed), and shows a real-time success or failure message to the customer.

Hosted Payment Page Example

Below is an example of Mint's Hosted Payment Page showing the customer experience:

The HPP displays:

Customer details (pre-populated when provided via the API)
Payment method selection (Apple Pay, Google Pay, Credit Card, Zip)
Order summary with subtotal, surcharge, and total due
Billing address fields for card payments

Step 3: Get The Webhook Notification

As soon as the transaction is complete, Mint's server sends an asynchronous POST request to your pre-configured Webhook URL.

This payload is the definitive source of truth. It confirms the transaction status so you can update the order in your database and fulfill the purchase.

For more detailed information on integrating webhooks, refer to the official Mint Payments documentation: Mint Webhook Integration Guide

Example Full Webhook Payload

This is a more complete example of the JSON data your endpoint will receive.

POST /your-webhook-endpoint
Content-Type: application/json

{
  "transaction_reference": "123456789123456789",
  "customer_reference": "Ref987654",
  "invoice_number": "Inv123456",
  "transaction_time_utc": "2023-08-30 04:36:08 AM",
  "status": "APPROVED",
  "amount": "101.00",
  "currency": "AUD",
  "masked_card_number": "411111******1111",
  "card_brand": "visa",
  "card_holder_name": "John Smith",
  "card_expiry": "05/2026",
  "email_address": "[email protected]",
  "mid": "12345678",
  "trading_name": "ABC Travel Co",
  "sale_amount": "100.00",
  "surcharge": "1.00",
  "webhook_type": "HPP",
  "payment_type": "CreditCard"
}

Key Webhook Fields Explained

Parameter	Description
`status`	Crucial. The result of the transaction. Handle all possible values: `APPROVED`, `DECLINED`, `PENDING`, `PRE_AUTHORISED`.
`transaction_reference`	Mint's unique ID for the transaction. Store this for refunds and reconciliation.
`amount`	The total amount charged to the customer (`sale_amount` + `surcharge`).
`sale_amount`	The original sale amount (excluding surcharge).
`surcharge`	The fee (if any) that was applied.
`webhook_type`	The source of the transaction. For payment links, this will be `HPP`. Other values: `VT`, `API`, `CARD_PRESENT`.
`payment_type`	The method used (e.g., `CreditCard`, `POLi`, `BankAccount`).
`card_brand`	The brand used (e.g., `visa`, `mastercard`, `amex`).

API Sequence Flow (Text-based)

Here is the step-by-step data flow for a successful transaction:

Merchant Server to Mint API: The Merchant Server sends a POST /payment-links request to the Mint API to create a payment link, including the amount and merchantReference.
Mint API to Merchant Server: The Mint API responds with a success message, including the customer-facing url.
Merchant Server to Customer: The Merchant Server sends this url to the Customer (e.g., via email or SMS).
Customer to Mint HPP: The Customer clicks the url, which opens Mint's Hosted Payment Page (HPP). The Customer enters their payment details.
Mint HPP to Customer: The Mint HPP processes the payment and displays a "Payment Successful" message to the Customer.
Mint API to Merchant Server (Webhook): The Mint API sends an asynchronous POST request to the Merchant Server's pre-configured webhook endpoint, notifying it of the transaction's status (e.g., "APPROVED").
Merchant Server to Mint API: The Merchant Server responds to the webhook with a 200 OK status to acknowledge receipt.
Merchant Server to Customer: After processing the webhook, the Merchant Server sends a confirmation (e.g., an email) to the Customer, indicating that their order is paid.