Receiving Webhook Notifications

Overview
Setup
Endpoint Requirements
Format
Webhook Delivery Behaviour
Webhook Role by Integration Model
Parameters
Example Webhook Payload
Handling Different Transaction Statuses
Missing Webhook Handling
Best Practices

1. Overview

Mint uses outgoing webhooks to notify merchant systems of payment outcomes in real time. When a payment attempt is processed, Mint sends an asynchronous POST request to a pre-configured URL containing the result of that payment.

2. Setup

Company Webhook (Default)

An outgoing webhook URL can be set up by Mint admins for a merchant account in the admin setup. The domain must also be allowed out of the firewall.

Dynamic Webhook (Payment Links API)

The Payment Links API supports an optional webhook_url parameter that allows you to specify a custom webhook endpoint per payment link. This is useful for platforms that manage multiple sub-merchants or agents and need payment notifications routed to different endpoints.

When a webhook_url is provided on a payment link, Mint delivers the webhook to the custom URL in addition to any company-level webhook configured in the admin portal. If the same URL appears in both, Mint automatically deduplicates so you only receive one delivery.

Contact Mint support ([email protected]) to whitelist your webhook domains before using dynamic webhooks.

3. Endpoint Requirements

Your webhook endpoint must meet the following requirements:

Requirement	Detail
HTTP method	Accept `POST` requests with a JSON body
Response code	Return HTTP `200` to acknowledge receipt
Response time	Respond within 30 seconds — requests that exceed this will time out
Idempotency	Handle duplicate deliveries safely by checking `transaction_reference` before processing
Async processing	Acknowledge the webhook immediately and perform any heavy processing (order fulfilment, notifications, database writes) asynchronously

4. Format

The webhook is sent as a POST request to the specified URL in JSON format.

Your endpoint must return an HTTP 200 response to acknowledge receipt of the webhook.

5. Webhook Delivery Behaviour

Webhooks are delivered once per payment outcome — Mint does not retry failed deliveries
When both a company webhook and a dynamic webhook_url are configured, both endpoints receive the identical payload simultaneously
If the same URL is configured at both the company level and per-transaction, Mint automatically deduplicates and delivers only once
All webhook deliveries are fire-and-forget — a failure at one endpoint does not block delivery to others

6. Webhook Role by Integration Model

The role of webhooks differs depending on which integration model you use:

Hosted Payment Pages (HPP)

For HPP integrations, the webhook is the primary mechanism for confirming payment outcomes. Since the payment occurs on Mint's hosted page, your backend does not receive a synchronous API response. A payment link should be considered unpaid until a webhook with an APPROVED status is received.

Direct API & Embedded One Time Token

For Direct API and Embedded One Time Token integrations, the API response is the source of truth for the payment outcome — your server receives the result synchronously when the transaction is processed.

The webhook mirrors this outcome and can be used to ensure that other systems which did not receive the API response (e.g. fulfilment systems, accounting platforms, or notification services) are kept up to date.

Important Characteristics

Webhooks are triggered once per payment attempt, on the outcome of that attempt
Webhooks may arrive after the frontend payment flow completes
Mint does not retry failed webhook deliveries
Mint currently sends webhooks only for APPROVED and PRE_AUTHORISED statuses. DECLINED and PENDING outcomes do not trigger a webhook — use the Transaction Status endpoint to poll for these outcomes

7. Parameters

Parameter	Description	Example	Response Values
`transaction_reference`	Mint transaction reference number	`123456789123456789`
`customer_reference`	Customer reference provided on the HPP	`Ref987654`
`invoice_number`	Invoice number provided on the HPP	`Inv123456`
`transaction_time_utc`	UTC time of the transaction	`2026-03-20 07:30:27 AM`
`status`	Status of the transaction	`APPROVED`	`APPROVED`, `PRE_AUTHORISED`
`amount`	Total amount of the transaction including surcharge	`101.00`
`currency`	Currency of the transaction	`AUD`
`masked_card_number`	Masked card number	`411111******1111`
`card_brand`	Brand of the card used, or APM identifier	`visa`	`mastercard`, `visa`, `amex`, `POLi`, `Pay By Bank`
`card_holder_name`	The name associated with the payment method	`John Smith`
`card_expiry`	Card expiry date	`05/2026`
`email_address`	Email address entered in the HPP	`[email protected]`
`mid`	Mint company ID	`12345678`
`trading_name`	Merchant's trading name	`ABC Travel Co`
`sale_amount`	Amount of the original sale (excludes surcharge if applied)	`100.00`
`surcharge`	Surcharge applied to the transaction	`1.00`
`webhook_type`	Source of the transaction	`VT` (Virtual Terminal)	`VT`, `HPP`, `CARD_PRESENT`, `API`, `APM`
`payment_type`	The payment type used during the transaction	`CreditCard`	`POLi`, `CreditCard`, `BankAccount`
`booking`	Mint Booking ID if payment was attached to bookings	`BK.9p64FIO7Vhmq1r0ov9Hje`	Nullable
`business_unit`	Mint Business Unit ID	`BU.a8E`	Nullable
`payment_link`	Payment Link ID if payment was made via payment link	`PL.9x8AVs72UhLTR6oZlMyCA`	Nullable
`presentment_amount`	Amount customer was charged in `presentment_currency` if customer elected to pay in own currency	`0.50`	Nullable
`presentment_currency`	Currency customer was charged in if customer elected to pay in own currency	`EUR`	ISO 4217 currency code. Nullable

8. Example Webhook Payload

{
  "transaction_reference": "123456789123456789",
  "customer_reference": "Ref987654",
  "invoice_number": "Inv123456",
  "transaction_time_utc": "2026-03-20 07:30:27 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",
  "booking": null,
  "business_unit": "BU.a8E",
  "payment_link": "PL.9x8AVs72UhLTR6oZlMyCA",
  "presentment_amount": null,
  "presentment_currency": null
}

9. Handling Different Transaction Statuses

Mint currently sends webhooks only for the following statuses:

Status	Recommended Action
`APPROVED`	Fulfil the order. Store `transaction_reference` for reconciliation and potential refunds.
`PRE_AUTHORISED`	Funds are held. Capture or cancel as required within 7 days (auto-cancel after 7 days).

Note: DECLINED and PENDING statuses do not trigger a webhook. If a payment attempt is not followed by a webhook, poll the Transaction Status endpoint to confirm the outcome before taking any action.

10. Missing Webhook Handling

Mint does not retry webhook deliveries. If your endpoint is unavailable or does not receive the webhook, you will not receive a second attempt.

If you have made a payment attempt and do not receive a webhook, you should manually poll for the transaction status using the Transaction Status endpoint:

POST /v5/purchase/{invoice_number|purchase_reference}

Pass your company_token in the request body to retrieve the current status of the transaction.

POST /v5/purchase/763433087819768193

{
  "company_token": "7qmtV8nn621vX5ptbUbFGUXj6EFzQbB"
}

Response:

{
  "transaction_time_utc": "2026-03-20 07:30:27 AM",
  "status": "APPROVED",
  "amount": 100.50,
  "currency": "AUD",
  "response_code": "success",
  "response_message": "Your request has been successfully processed."
}

You can query by either the invoice_number (your internal reference, passed as purchase.invoice_number when creating the transaction) or the purchase_reference (Mint's transaction reference returned in the API response or webhook).

To check the status of a refund, use the equivalent refund endpoint:

POST /v5/refund/{invoice_number|purchase_reference}

See the RESTful API Reference — Transaction Status for full details.

11. Best Practices

Implement webhook processing before going live
Log all incoming webhook payloads for debugging and audit
Return HTTP 200 as quickly as possible; perform heavy processing asynchronously
Use transaction_reference to correlate webhooks with transactions in your system
For HPP integrations, do not treat a payment as successful until you receive an APPROVED webhook
If a webhook is not received, fall back to polling the Transaction Status endpoint
Design systems to handle multiple failed payment attempts against the same payment link

Below is an example of the JSON payload sent in the webhook:

{
  "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_expiry": "05/2026",
  "email_address": "[email protected]",
  "mid": "12345678",
  "trading_name": "ABC Travel Co",
  "sale_amount": "100.00",
  "surcharge": "1.00",
  "webhook_type": "VT"
}