INTRODUCTION

Welcome to 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.To integrate with Mint’s UAT system please use the following context root:

<https://secure-uatsb.mintpayments.net/mpay/>

Authentication

mPay uses an API keys to uniquely authenticate requests. Your API key will be issued by Mint during the on-boarding 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.

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.

Transaction Status

Many endpoints will return transaction status. Following a list with 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 enter 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-Authorised is released/reversed/cancelled. Bank will release hold on the amount that were authorised

Errors / Status Codes

In terms of error handling there will be 2 cases of errors

`200 OK` - Purchase Successful - not an ERROR
`200 OK` - Purchase Declined ERRORs
Non 200 ERRORs

After a call of an endpoint checking the HTTP response code will indicate if the transaction was OK or not.

In case of the 200 response, the status has to be checked to determine APPROVED from DECLINED.
All non 200 response codes indicate a failure.

`HTTP 200` Purchase Successful

That is not an error but just an example of the response you can expect if transaction was processed correctly

{  
    "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` Error - Purchase Declined

With all ‘200 errors’ the status of the transaction will be ‘declined’. The response of the ‘200 errors’ will contain the pair response_code and response_message which will have a detailed description of the problem.

"response_code": "generic_decline",
"response_message": "The card has been declined. Please use a different card."

In the most cases here the credit card is not suitable to be used and the best approach would be to use a different card rather then re-trying which will result in the same declined transaction.

Examples

/** Sample : 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."
}

/** Sample : 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."
}

/** Sample : 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’ will have the following JSON structure

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

Based on the error_code and error_message in the table below ‘List of Mint Errors’ you would have to take action based on the case. So if the 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.

List of HTTP Errors

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 that failed 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.

HTTP Status Codes

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 do 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.

List of Mint Errors

Error Code	Description
`processing_error`	Problems with processing of the transaction. Try re- run 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.
`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
`invalid_customer_id_received`	Customer_id is not valid
`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`	Company token is missing
`mandatory_fields_missing`	Token is missing
`authentication_failed`	Bad token
`authentication_failed`	Bad card token
`authentication_failed`	Invalid card token
`invalid_amount_format`	Amount format is incorrect. Valid amount should round to 2 decimal places
`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
`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
`invalid_card_token`	The card token do not belong to this company
`invalid_customer_ip`	Customer IP address is invalid
`mandatory_values_missing`	Customer Reference is missing
`insufficient_funds`	The card has insufficient funds to process this transaction. Please use a different card
`duplicate_input`	Customer Reference is already taken
`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
`invalid_company_token`	The purchase reference do not belong to this company
`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

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