API Conventions

The sections below provide conventions for use in integrating Maast APIs. For instructions on implementing APIs, see About Our APIs as well as the relevant endpoints' implementation guides and API reference.

For API testing conventions, see Test Conventions. For instructions on testing your integration, see Test and Go Live.

Format

Note that we describe formatting for amount fields as follows: "Variable length, up to 12,2 N," or simply, "12,2 N." This means, "Up to 12 total digits, including two digits after the decimal point." The maximum amount for "5,2 N," for example, is 999.99. The decimal portion is always optional (e.g., $10.00 can be sent as '10' or '10.00').


Response Conventions

API HTTP Status Codes

When a request is successful, Maast's API provides an HTTP status code of 200 (OK). Unsuccessful requests receive a non-200 HTTP status code and a description in the body of the response message.

The table below shows all possible HTTP status codes:

CodeDescription
200Success - The request was successful.
400Bad request - The request failed validation. Check the data element for a more detailed list of validation failures.
401Unauthorized request - The API did not recognize the credentials provided.
402Declined - The request was valid, but the response from the card issuer was a decline. The field rcode will contain 0 followed by the two-character authorization response code. Applicable only to Payment Gateway API.
403No access - The API key being used does not have access to this resource. Access may be granted through the Maast Manager portal.
404Does not exist - The service you have called does not exist. Please check and verify the resource URL for your request.
409Conflict - The request failed due to the state of the transaction. For example, attempts to void a settled transaction would result in a conflict. Applicable only to Payment Gateway API.
500Server problem - There was a server problem processing the request. Maast developers are notified automatically of the issue when this API code occurs.
504Timeout - The authorization request timed out while waiting for the card issuer to respond. Applicable only to Payment Gateway API requests.

Payment Gateway API Response Codes

After any request, the Payment Gateway API responds with a description of the response in the rcode and rmsg fields.

The table below shows all possible Payment Gateway API responses:

CodeDescription
000Success - The authorization or sale transaction was approved by the card authorization system.
100Bad request - The message was invalid. The field rmsg shows details about the invalid or missing field(s).
101Invalid credentials - The merchant_id and security_key provided do not match a Maast account.
102Invalid pg_id - The pg_id value could not be linked to a valid transaction. This is used for Payment Gateway refunds.
103Missing cardholder data - The request lacked valid cardholder data. Requests requiring cardholder data need only one of the following combinations:
- card_number (only allowed for 'Force Credit' and 'Tokenize' requests)
- card_number, exp_date
- card_id
- card_id, exp_date
- card_swipe
- customer_id
104Invalid transaction amount - The request lacked the amt_tran, or you provided an invalid value. Verify requests require amt_tran to be zero or not present in the request message. Other messages require amt_tran to be numeric and greater than zero. Negative amounts are invalid.
105Missing auth_code - Force transactions require the field auth_code in the request message.
106Invalid AVS (Address Verification Service) data - If the field avs_address is provided in the request message, then the message must also contain the avs_zip field.
107Invalid expiration date - The exp_date in the request was not properly formatted.
108Invalid card number - The card_number field in the request message was non-numeric, or it contained too few or too many digits.
109Field length validation failed - At least one field exceeded the maximum allowed length. The rmsg field contains the name of the first field that failed validation.
110Dynamic DBA not allowed- The request message contained a dynamic DBA field, and the account is not configured for dynamic DBA.
111Credits not allowed - An unreferenced credit to a previous transaction was submitted, and the merchant is not currently authorized to process credits. For security reasons, we recommend performing a refund rather than a credit. Please email [email protected] to discuss enabling credits on your account.
112Invalid customer data - The message requested that a customer be added to the Maast Customer Vault; however, the customer ID already exists, or the required customer fields are not included.
113Declined due to merchant risk settings - The transaction was declined because of an AVS and/or CVV2 result.
114Invalid currency code - The tran_currency in the request should be the ISO numeric currency code.
115Invalid surcharge data - At least one of the following is the case:
- A surcharge is not allowed for the merchant.
- A surcharge is not allowed on the card.
- The surcharge amount exceeds 4% of the transaction amount.
116Invalid email address - The email_address in the request is invalid.
117Email address is required - The request is missing email_address.
118Invalid merchant logo URL - The logo_url in the request is invalid.
119Invalid ACH payment - The ACH payment is invalid. See ACH Response Code 119 Detail Codes and Descriptions.
120Not supported - The requested transaction is not supported.
121Invalid DBA Suffix - The DBA Suffix does not match a Maast-accepted concept of a description.
122Could not decrypt Google Pay™ payload - At least one of the following is the case:
- The specified merchant does not take Google Pay™.
- This payload was not created for you.
- The payload contains data that Maast was not expecting/cannot understand.
- The payload has expired.
401Void failed- The transaction has already been captured or voided.
402Refund failed- At least one of the following is the case:
- The transaction has already been refunded.
- The original transaction has not been captured.
- The total amount of all refunds exceeds the original transaction amount.
- The original transaction was not a sale.
403Capture failed - At least one of the following is the case:
- The amount exceeds the authorized amount. (This is only allowed when the merchant category code allows tips.)
- The transaction has already been captured.
- The authorization has been voided.
404Batch Close failed - The 'Batch Close' transaction failed.
405Tokenization failed - The 'Tokenize' transaction request failed.
406Email receipt failed
407Partial capture only, second transaction failed
408Recharge failed
409Token expiration failed
410Duplicate transaction
411Maximum attempts reached - The maximum number of transaction detail submission attempts have been reached within a specified time window. The source IP address will be blocked for 24 hours.
412Do not disturb - The 'Do Not Disturb' configuration option is enabled, and the request was sent within the 'Do Not Disturb' timeframe.
998Timeout- The authorization request timed out without returning a response. Timeouts occur when the authorization system does not receive a response from the host within 10 seconds.
999Internal error- The payment gateway application encountered an unexpected error while processing the request.

Platform API Response Codes

After any request, the Platform API responds with a detailed description of the response in the code and message fields. Below is a list of all possible responses codes:

API CodeDescription
0The request was successful.
2Bad request. The request failed validation. Check the data element for a more detailed list of validation failures.
6The API key being used does not have access to this resource. You may grant access through the Maast Manager portal.
7The service you have called does not exist. Please check and verify the resource URL for your request.
11Unauthorized request. The API did not recognize the credentials provided, or the operation is not allowed for this merchant.
99There was a server problem processing the request. Maast developers are automatically notified of the issue when this API code occurs.

Account Updater Server Response Code

The Account Updater response code identifies whether the Account Updater service changed an account number and, if so, what change occurred. The table below shows the possible response codes:

CodeDescription
000New Card: No response was provided by the card brand, or this is a new account.
200No Update: Valid account
201Updated: Account expiration date
202Updated: Account number
203Account is closed
204Contact cardholder
205Error: Merchant not registered
206No match
300Invalid record type
315Invalid expiration date
320Invalid account number
328Card in question is already registered in ensure bill.
329Invalid card type
330Delete notification successful
340Notification not found on card record

Payment Card Conventions

Card Types

The table below shows supported card types:

Card TypeDescription
AMAmerican Express
DSDiscover
MCMastercard
VSVisa
APACH Payments

Card Authorization Responses

For 'Authorize Transaction,' 'Sale' and 'Verify' requests, the rcode field in the response message comprises three characters and begins with a zero (0). The last two characters are the response code returned by the authorization system. The table below provides descriptions of the authorization system response codes:

CodeResponse TextDescription
00ApprovedApproved and completed successfully
01Refer to issuerContact the card issuer
02Refer to issuerContact the card issuer, special condition
03Invalid merchantThe issuer has restricted the merchant or MCC
04Pick up cardHold the card (no fraud)
05DeclineDo not accept payment
06ErrorUnspecified error
07Pick up card fraudHold the card, special condition (fraudulent)
08Honor with IDHonor with identification
10Partial ApprovalThe card issuer accepts a part of the payment but blocks the rest
11Approved VIPApproved (V.I.P.)
12Invalid transactionInvalid transaction
13Invalid amountInvalid amount or currency conversion field overflow
14Bad card numberInvalid account number (no such number)
15No such issuerNo such issuer
17Cardholder cancelledCardholder canceled the transaction after an 'Authorize' request was sent (Mastercard non-debit reversal)
19Re-enterRe-enter transaction
21No action takenNo action taken
25Unable to locateUnable to locate record in file
28File temporarily unavailableFile temporarily not available for update or inquiry
30Format errorFormat Error - Decline (Mastercard, Discover and PayPal)
32Partial reversalThe reversal request amount is less than the original transaction (Mastercard)
34Fraud reversalSuspect fraud, indicating an approved eCommerce transaction is canceled by the merchant (Mastercard reversal)
39No credit accountNo credit account
41Pick up - LostLost card, pick up (fraud account)
43Pick up - StolenStolen card, pick up (fraud account)
46Closed accountClosed account
51Insufficient fundsThe account has insufficient funds
52No checking accountNo checking account
53No savings accountNo savings account
54Expired cardExpired card or expiration date is missing
55Invalid PINIncorrect PIN or PIN is missing
57Not permittedTransaction not permitted to cardholder (not allowed for the product or card type)
58Not allowed at terminalTransaction not allowed at terminal
59Suspected fraudSuspected fraud
61Exceeds amount limitExceeds approval amount limit
62Restricted cardRestricted card (card invalid in this region or country)
63Security violationSecurity violation (source is not the correct issuer)
64AML requirement not fulfilledTransaction does not fulfill AML requirement
65Activity limit exceededExceeds withdrawal frequency limit
68ReversalUsed in Mastercard reversal requests and Discover and PayPal responses
6PVerification data failedVerification data failed
70Call issuerContact card issuer
71PIN not changedPIN not changed
75PIN entry attempts exceededThe allowable number of PIN entry tries was exceeded
76RRN not foundReversal: Unable to locate previous message (no match on Retrieval Reference Number)
77Invalid reversal dataPrevious message located for a repeat or reversal, but repeat or reversal data are inconsistent with original message
78New card, not properly unblockedTransaction from new cardholder, and card was not properly unblocked
79Already reversedAlready reversed (by Switch)
80No financial impactNo financial impact (reversal for declined debit)
81PIN cryptographic errorCryptographic error found in PIN
82Incorrect CVVNegative online CAM, dCVV, iCVV, CVV, or CAVV results, or the offline PIN authentication was interrupted
83Unable to verify PINUnable to verify PIN
84DeclineInvalid authorization life cycle: Decline (Mastercard) or duplicate transaction detected (Visa)
85No reason to declineIssuer has no reason to decline the transaction, but the transaction didn't go through.
86Cannot verify PINCannot verify PIN; for example, no PVV
87Approved (purch amt, not cashback)Approved for purchase amount only, no cash back allowed (Mastercard)
88Cryptographic failureCryptographic failure
89IneligibleIneligible to receive financial position information (GIV)
91Issuer unavailableOne of the following has occurred:
- Issuer or switch is inoperative and STIP is not applicable or not available for this transaction.
- Time-out when no stand-in
- POS check service: destination unavailable
- Credit voucher and merchandise return authorizations: V.I.P. sent the transaction to the issuer, but the issuer was unavailable.
92Destination not foundFinancial institution or intermediate network facility cannot be found for routing (receiving institution ID is invalid).
93Transaction cannot completeTransaction cannot be completed - violation of law.
94Duplicate transmissionDuplicate transmission detected (Integrated debit and Mastercard).
96System malfunctionSystem malfunction
B1Surcharge not permittedSurcharge amount is not permitted on Visa cards or EBT food stamps (U.S. acquirers only).
B2Surcharge not supportedSurcharge amount is not supported by debit network issuer.
N0Force STIPForce STIP
N3Not availableCash service not available
N4Exceeds issuer limitCash request exceeds issuer or approved limit
N5Ineligible for resubmissionIneligible for resubmission
N7Decline CVV2 failureDecline CVV2 failure
N8Preauthorized amount exceededTransaction amount exceeds preauthorized approval amount
Q1Card authentication failedCard authentication failed
R0Stop payment orderCardholder canceled this specific recurring/installment payment
R1Revocation of authorizationCardholder canceled all recurring/installment payments for this merchant
R2Transaction not qualifiedThe transaction does not qualify for Visa PIN
R3Revocation of authorizationCanceled all recurring payments
T0First time checkFirst time check
T1Check valid - not convertedCheck is OK but cannot be converted
T2Invalid transit routingOne of the following:
- Invalid routing transit number or check belongs to a category that is not eligible for conversion;
- Transaction failed ABA check digit validation.
T3Amount exceeds service limitAmount greater than established service limit
T4Unpaid itemsUnpaid items, failed negative file check
T5Duplicate check numberDuplicate check number
T6MICR errorMICR error
T7Check limit exceededToo many checks (over merchant or bank limit)
XAForward to issuerForward to issuer
XDForward to issuerForward to issuer
Y1Offline approvedOffline approved
Y3Offline approvedUnable to go online; offline-approved
Z1Offline declinedOffline declined
Z3Offline declinedUnable to go online; offline-declined
CVCard type verification errorCard type verification error
D3Invalid 3D-Secure cryptogramTransaction failure due to missing or invalid 3D-Secure cryptogram
ECCID verification errorCID verification error
M0Transaction not allowedCanada Domestic debit transaction not allowed (Mastercard)
P2Invalid biller informationInvalid biller information
V1Daily threshold exceededDaily threshold exceeded

Payment Result Codes for AVS

The Address Verification Service (AVS) is a program operated by the issuers via the card brands to help provide a way to validate additional information on record with the issuers. The following table describes the responses you can anticipate:

CodeResponse TextDescription
XMatchStreet address and 9-digit ZIP code both match
YMatchStreet address and 5-digit ZIP code both match
APartial MatchStreet address matches, but both 5-digit and 9- digit ZIP code do not match
WPartial MatchStreet address does not match, but 9-digit ZIP code matches
ZPartial MatchStreet address does not match, but 5-digit ZIP code matches
NNo MatchNone of the following matches: street address, 5-digit ZIP code, or 9-digit ZIP code
USystem UnavailableAddress information unavailable. Returned if non-U.S. AVS is not available or if the AVS in a U.S. bank is not functioning properly.
RSystem UnavailableRetry - Issuer's system is unavailable or timed out.
EInvalidAVS data is invalid
SNot SupportedU.S. issuing bank does not support AVS
DMatchStreet address and postal code match for international transaction
MMatchStreet address and postal code match for international transaction
BPartial MatchStreet address matches for international transaction. Postal code not verified due to incompatible formats.
PPartial MatchPostal codes match for international transaction, but street address not verified due to incompatible formats.
CNo MatchStreet address and postal code not verified for international transaction due to incompatible formats.
INo MatchAddress information not verified by the international issuer
GNot SupportedNon-U.S. issuer does not participate

Payment Result Codes for CVV2

The Card Verification Value 2 (CVV2) is a program operated by the issuers via the card brands to help validate that the credit card data being used is in the hands of the owner. The following table describes the responses you can anticipate:

CodeDescription
MCVV2 Match
NCVV2 No Match
PNot Processed
SIssuer indicates that CVV2 data should be present on the card, but the merchant has indicated the data is not present on the card.
UIssuer has not certified for CVV2, or issuer has not provided Visa with the CVV2 encryption keys.

POS Entry Mode

The POS entry mode is a two-digit code that identifies the method used to enter the cardholder's account number and card expiration date. The table below shows POS entry modes:

CodeDescription
01Manual entry
02Magnetic strip
03Bar code
04OCR entry
05Chip card, CVV available
07Contactless card
09E-commerce
90Magnetic stripe (track 2)
91Contactless card
95Chip card, no CVV