Understanding Error Codes

Overview
Error Handling
HTTP Status Codes
Response Formats
Mint Error Code Reference

Overview

This page is the complete reference for errors and status codes returned by the mPay API. It covers HTTP status codes, response formats for both successful and failed transactions, and the full catalogue of Mint-specific error codes.

Error Handling

There are two categories of errors returned by the API:

200 OK — The HTTP request succeeded, but the transaction may have been declined. The status field in the response body determines the outcome.
Non-200 — The HTTP request itself failed due to validation, authentication, or server errors.

After every API call, check the HTTP response code first. For 200 responses, inspect the status field to distinguish APPROVED from DECLINED. All non-200 response codes indicate a request-level failure.

HTTP Status Codes

mPay uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the HTTP 2xx range indicate success. Codes in the HTTP 4xx range indicate an error given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the HTTP 5xx range indicate an error with Mint's servers.

Status Code	Description
`200`	OK — The request was processed successfully
`400`	Bad request — The request contains missing parameters, is in an incorrect shape, or failed another validation test
`401`	Unauthorized — Please verify that the authentication token is provided and is valid
`403`	Forbidden — Cases where customer does not have API enabled, service not enabled, etc.
`404`	Not found — The requested endpoint does not exist
`405`	Method not allowed
`500`	Server error — Something went wrong on our end; please let us know if you are receiving this error

Response Formats

`HTTP 200` — Purchase Successful

When a transaction is processed and approved, the response contains full card and purchase details:

{
    "card": {
        "brand": "visa",
        "funding": "credit",
        "country": "US",
        "number": "400000******0259",
        "holder_name": "John Doe"
    },
    "purchase": {
        "transaction_time_utc": "2020-03-26 02:08:38 AM",
        "status": "APPROVED",
        "purchase_reference": "846577135053848833",
        "amount": 110.2,
        "surcharge_amount": 0.0,
        "total_amount": 110.2,
        "currency": "AUD"
    },
    "response_code": "success",
    "response_message": "Your request has been successfully processed."
}

`HTTP 200` — Purchase Declined

When the HTTP response is 200 but the transaction was not approved, the status will be DECLINED. The response_code and response_message fields describe the reason.

In most cases the card is not suitable and the best approach is to use a different card rather than retrying, which will produce the same decline.

Generic Decline:

{
    "card": {
        "brand": "visa",
        "funding": "credit",
        "country": "US",
        "number": "400000******0002",
        "holder_name": "John Doe"
    },
    "purchase": {
        "transaction_time_utc": "2020-03-26 01:50:51 AM",
        "status": "DECLINED",
        "purchase_reference": "335287298017947771",
        "amount": 110.2,
        "surcharge_amount": 0.0,
        "total_amount": 0.0,
        "currency": "AUD"
    },
    "response_code": "generic_decline",
    "response_message": "The card has been declined. Please use a different card."
}

Stolen Card:

{
    "card": {
        "brand": "visa",
        "funding": "credit",
        "country": "US",
        "number": "400000******9979",
        "holder_name": "John Doe"
    },
    "purchase": {
        "transaction_time_utc": "2020-03-26 01:57:31 AM",
        "status": "DECLINED",
        "purchase_reference": "247915481936229025",
        "amount": 110.2,
        "surcharge_amount": 0,
        "total_amount": null,
        "currency": "AUD"
    },
    "response_code": "stolen_card",
    "response_message": "A stolen card is being used. Please use a different card."
}

Insufficient Funds:

{
    "card": {
        "brand": "visa",
        "funding": "credit",
        "country": "US",
        "number": "400000******9995",
        "holder_name": "John Doe"
    },
    "purchase": {
        "transaction_time_utc": "2020-03-26 02:06:39 AM",
        "status": "DECLINED",
        "purchase_reference": "864559968685000961",
        "amount": 110.2,
        "surcharge_amount": 0,
        "total_amount": null,
        "currency": "AUD"
    },
    "response_code": "insufficient_funds",
    "response_message": "The card has insufficient funds to process this transaction. Please use a different card."
}

Non-200 Errors

All non-200 errors use the following JSON structure:

{
    "timestamp_utc": "string",
    "error_code": "string",
    "error_message": "string",
    "request_uri": "string"
}

Based on the error_code and error_message you would need to take action based on the case. If mandatory fields are missing, passing all required values would solve the problem. If the date or amount is not in the expected format, checking the format of the passed values could correct the issue.

Mint Error Code Reference

The tables below list every Mint-specific error code that can appear in API responses.

Processing Errors

Errors that occur during transaction processing. These may be transient — retrying with a new transaction token may resolve the issue.

Error Code	Description
`processing_error`	Problems with processing of the transaction. Try re-running the transaction.
`processing_error`	An error occurred while processing your card. Try again later.
`processing_error`	Could not save mint card token or mint customer.
`processing_error`	No matches found for the reference. Invoice Number is already taken.
`processing_error`	Failed to process your request. Please try again later.
`processing_error`	Invoice Number is already taken.

Card Validation Errors

Errors returned when the supplied card details are invalid or incomplete.

Error Code	Description
`invalid_card_details_received`	Invalid card details received
`invalid_card_details_received`	Invalid card number or pan
`invalid_card_details_received`	Your card's security code is incorrect
`invalid_card_details_received`	Card's expiration month is missing
`invalid_card_details_received`	Card's expiration year is missing
`invalid_card_details_received`	Card's security code (cvv) is missing
`invalid_card_details_received`	Card holder name is missing
`invalid_card_details_received`	Your card has been declined

Customer Validation Errors

Error Code	Description
`invalid_customer_id_received`	Customer_id is not valid
`invalid_customer_ip`	Customer IP address is invalid

Mandatory Field Errors

Errors returned when required request parameters are missing.

Error Code	Description
`mandatory_fields_missing`	Mandatory fields like card details are missing
`mandatory_fields_missing`	Company token is missing
`mandatory_fields_missing`	Transaction token is missing
`mandatory_fields_missing`	customer.store_card_permission is missing
`mandatory_fields_missing`	Customer IP address is missing
`mandatory_fields_missing`	Timezone is missing
`mandatory_fields_missing`	Card token is missing
`mandatory_fields_missing`	Card token or card details are missing
`mandatory_fields_missing`	Currency is missing
`mandatory_fields_missing`	Token is missing
`mandatory_values_missing`	Customer Reference is missing

Authentication Errors

Errors returned when the supplied tokens are invalid or expired.

Error Code	Description
`authentication_failed`	Bad token
`authentication_failed`	Bad card token
`authentication_failed`	Invalid card token

Amount and Format Errors

Error Code	Description
`invalid_amount_format`	Amount format is incorrect. Valid amount should round to 2 decimal places

Access and Limit Errors

Error Code	Description
`resource_access_denied`	This service is not enabled for you
`resource_access_denied`	Transaction cannot be routed or company is not active
`daily_limit_exceeded`	Merchant's daily limit exceeded

Decline Errors

Errors returned when the issuing bank declines the transaction. In most cases the customer should use a different card rather than retrying.

Error Code	Description
`insufficient_funds`	The card has insufficient funds to process this transaction. Please use a different card
`generic_decline`	The card has been declined. Please use a different card
`lost_card`	A lost card is being used. Please use a different card
`stolen_card`	A stolen card is being used. Please use a different card
`purchase_decline`	The card has been declined. Please verify the token used
`purchase_decline`	Your card has expired
`purchase_decline`	Your card has been declined
`duplicate_input`	Customer Reference is already taken

Refund Errors

Errors returned when a refund request is invalid.

Error Code	Description
`invalid_refund`	Transaction is not authorised for refund, refund amount exceeds authorised amount
`invalid_refund`	Refund amount exceeds authorised amount
`invalid_refund`	Refunds can only be made to the same card as the original purchase

Token Errors

Error Code	Description
`invalid_card_token`	The card token does not belong to this company
`invalid_company_token`	The purchase reference does not belong to this company

Capture and Cancel Errors

Errors related to pre-authorisation capture and cancellation operations.

Error Code	Description
`invalid_capture`	Capture not allowed on already APPROVED purchase
`invalid_capture`	Capture allowed only on PRE_AUTHORISED purchase
`invalid_capture`	Capture not allowed on CANCELLED purchase
`invalid_capture`	Capture amount exceeds pre-authorised amount
`invalid_cancel`	Cancel allowed only on PRE_AUTHORISED purchase
`invalid_cancel`	Cancel not allowed on APPROVED purchase
`invalid_cancel`	Cancel not allowed on already CANCELLED purchase

Understanding error codes

Understanding Error Codes

Table of Contents

Overview

Error Handling

HTTP Status Codes

Response Formats

`HTTP 200` — Purchase Successful

`HTTP 200` — Purchase Declined

Non-200 Errors

Mint Error Code Reference

Processing Errors

Card Validation Errors

Customer Validation Errors

Mandatory Field Errors

Authentication Errors

Amount and Format Errors

Access and Limit Errors

Decline Errors

Refund Errors

Token Errors

Capture and Cancel Errors

Understanding Error Codes

Table of Contents

Overview

Error Handling

HTTP Status Codes

Response Formats

HTTP 200 — Purchase Successful

HTTP 200 — Purchase Declined

Non-200 Errors

Mint Error Code Reference

Processing Errors

Card Validation Errors

Customer Validation Errors

Mandatory Field Errors

Authentication Errors

Amount and Format Errors

Access and Limit Errors

Decline Errors

Refund Errors

Token Errors

Capture and Cancel Errors

`HTTP 200` — Purchase Successful

`HTTP 200` — Purchase Declined