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:
Code | Description |
---|---|
200 | Success - The request was successful. |
400 | Bad request - The request failed validation. Check the data element for a more detailed list of validation failures. |
401 | Unauthorized request - The API did not recognize the credentials provided. |
402 | Declined - 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. |
403 | No access - The API key being used does not have access to this resource. Access may be granted through the Maast Manager portal. |
404 | Does not exist - The service you have called does not exist. Please check and verify the resource URL for your request. |
409 | Conflict - 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. |
500 | Server problem - There was a server problem processing the request. Maast developers are notified automatically of the issue when this API code occurs. |
504 | Timeout - 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:
Code | Description |
---|---|
000 | Success - The authorization or sale transaction was approved by the card authorization system. |
100 | Bad request - The message was invalid. The field rmsg shows details about the invalid or missing field(s). |
101 | Invalid credentials - The merchant_id and security_key provided do not match a Maast account. |
102 | Invalid pg_id - The pg_id value could not be linked to a valid transaction. This is used for Payment Gateway refunds. |
103 | Missing 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 |
104 | Invalid 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. |
105 | Missing auth_code - Force transactions require the field auth_code in the request message. |
106 | Invalid 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. |
107 | Invalid expiration date - The exp_date in the request was not properly formatted. |
108 | Invalid card number - The card_number field in the request message was non-numeric, or it contained too few or too many digits. |
109 | Field 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. |
110 | Dynamic DBA not allowed- The request message contained a dynamic DBA field, and the account is not configured for dynamic DBA. |
111 | Credits 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. |
112 | Invalid 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. |
113 | Declined due to merchant risk settings - The transaction was declined because of an AVS and/or CVV2 result. |
114 | Invalid currency code - The tran_currency in the request should be the ISO numeric currency code. |
115 | Invalid 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. |
116 | Invalid email address - The email_address in the request is invalid. |
117 | Email address is required - The request is missing email_address . |
118 | Invalid merchant logo URL - The logo_url in the request is invalid. |
119 | Invalid ACH payment - The ACH payment is invalid. See ACH Response Code 119 Detail Codes and Descriptions. |
120 | Not supported - The requested transaction is not supported. |
121 | Invalid DBA Suffix - The DBA Suffix does not match a Maast-accepted concept of a description. |
122 | Could 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. |
401 | Void failed- The transaction has already been captured or voided. |
402 | Refund 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. |
403 | Capture 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. |
404 | Batch Close failed - The 'Batch Close' transaction failed. |
405 | Tokenization failed - The 'Tokenize' transaction request failed. |
406 | Email receipt failed |
407 | Partial capture only, second transaction failed |
408 | Recharge failed |
409 | Token expiration failed |
410 | Duplicate transaction |
411 | Maximum 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. |
412 | Do not disturb - The 'Do Not Disturb' configuration option is enabled, and the request was sent within the 'Do Not Disturb' timeframe. |
998 | Timeout- 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. |
999 | Internal 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 Code | Description |
---|---|
0 | The request was successful. |
2 | Bad request. The request failed validation. Check the data element for a more detailed list of validation failures. |
6 | The API key being used does not have access to this resource. You may grant access through the Maast Manager portal. |
7 | The service you have called does not exist. Please check and verify the resource URL for your request. |
11 | Unauthorized request. The API did not recognize the credentials provided, or the operation is not allowed for this merchant. |
99 | There 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:
Code | Description |
---|---|
000 | New Card: No response was provided by the card brand, or this is a new account. |
200 | No Update: Valid account |
201 | Updated: Account expiration date |
202 | Updated: Account number |
203 | Account is closed |
204 | Contact cardholder |
205 | Error: Merchant not registered |
206 | No match |
300 | Invalid record type |
315 | Invalid expiration date |
320 | Invalid account number |
328 | Card in question is already registered in ensure bill. |
329 | Invalid card type |
330 | Delete notification successful |
340 | Notification not found on card record |
Payment Card Conventions
Card Types
The table below shows supported card types:
Card Type | Description |
---|---|
AM | American Express |
DS | Discover |
MC | Mastercard |
VS | Visa |
AP | ACH 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:
Code | Response Text | Description |
---|---|---|
00 | Approved | Approved and completed successfully |
01 | Refer to issuer | Contact the card issuer |
02 | Refer to issuer | Contact the card issuer, special condition |
03 | Invalid merchant | The issuer has restricted the merchant or MCC |
04 | Pick up card | Hold the card (no fraud) |
05 | Decline | Do not accept payment |
06 | Error | Unspecified error |
07 | Pick up card fraud | Hold the card, special condition (fraudulent) |
08 | Honor with ID | Honor with identification |
10 | Partial Approval | The card issuer accepts a part of the payment but blocks the rest |
11 | Approved VIP | Approved (V.I.P.) |
12 | Invalid transaction | Invalid transaction |
13 | Invalid amount | Invalid amount or currency conversion field overflow |
14 | Bad card number | Invalid account number (no such number) |
15 | No such issuer | No such issuer |
17 | Cardholder cancelled | Cardholder canceled the transaction after an 'Authorize' request was sent (Mastercard non-debit reversal) |
19 | Re-enter | Re-enter transaction |
21 | No action taken | No action taken |
25 | Unable to locate | Unable to locate record in file |
28 | File temporarily unavailable | File temporarily not available for update or inquiry |
30 | Format error | Format Error - Decline (Mastercard, Discover and PayPal) |
32 | Partial reversal | The reversal request amount is less than the original transaction (Mastercard) |
34 | Fraud reversal | Suspect fraud, indicating an approved eCommerce transaction is canceled by the merchant (Mastercard reversal) |
39 | No credit account | No credit account |
41 | Pick up - Lost | Lost card, pick up (fraud account) |
43 | Pick up - Stolen | Stolen card, pick up (fraud account) |
46 | Closed account | Closed account |
51 | Insufficient funds | The account has insufficient funds |
52 | No checking account | No checking account |
53 | No savings account | No savings account |
54 | Expired card | Expired card or expiration date is missing |
55 | Invalid PIN | Incorrect PIN or PIN is missing |
57 | Not permitted | Transaction not permitted to cardholder (not allowed for the product or card type) |
58 | Not allowed at terminal | Transaction not allowed at terminal |
59 | Suspected fraud | Suspected fraud |
61 | Exceeds amount limit | Exceeds approval amount limit |
62 | Restricted card | Restricted card (card invalid in this region or country) |
63 | Security violation | Security violation (source is not the correct issuer) |
64 | AML requirement not fulfilled | Transaction does not fulfill AML requirement |
65 | Activity limit exceeded | Exceeds withdrawal frequency limit |
68 | Reversal | Used in Mastercard reversal requests and Discover and PayPal responses |
6P | Verification data failed | Verification data failed |
70 | Call issuer | Contact card issuer |
71 | PIN not changed | PIN not changed |
75 | PIN entry attempts exceeded | The allowable number of PIN entry tries was exceeded |
76 | RRN not found | Reversal: Unable to locate previous message (no match on Retrieval Reference Number) |
77 | Invalid reversal data | Previous message located for a repeat or reversal, but repeat or reversal data are inconsistent with original message |
78 | New card, not properly unblocked | Transaction from new cardholder, and card was not properly unblocked |
79 | Already reversed | Already reversed (by Switch) |
80 | No financial impact | No financial impact (reversal for declined debit) |
81 | PIN cryptographic error | Cryptographic error found in PIN |
82 | Incorrect CVV | Negative online CAM, dCVV, iCVV, CVV, or CAVV results, or the offline PIN authentication was interrupted |
83 | Unable to verify PIN | Unable to verify PIN |
84 | Decline | Invalid authorization life cycle: Decline (Mastercard) or duplicate transaction detected (Visa) |
85 | No reason to decline | Issuer has no reason to decline the transaction, but the transaction didn't go through. |
86 | Cannot verify PIN | Cannot verify PIN; for example, no PVV |
87 | Approved (purch amt, not cashback) | Approved for purchase amount only, no cash back allowed (Mastercard) |
88 | Cryptographic failure | Cryptographic failure |
89 | Ineligible | Ineligible to receive financial position information (GIV) |
91 | Issuer unavailable | One 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. |
92 | Destination not found | Financial institution or intermediate network facility cannot be found for routing (receiving institution ID is invalid). |
93 | Transaction cannot complete | Transaction cannot be completed - violation of law. |
94 | Duplicate transmission | Duplicate transmission detected (Integrated debit and Mastercard). |
96 | System malfunction | System malfunction |
B1 | Surcharge not permitted | Surcharge amount is not permitted on Visa cards or EBT food stamps (U.S. acquirers only). |
B2 | Surcharge not supported | Surcharge amount is not supported by debit network issuer. |
N0 | Force STIP | Force STIP |
N3 | Not available | Cash service not available |
N4 | Exceeds issuer limit | Cash request exceeds issuer or approved limit |
N5 | Ineligible for resubmission | Ineligible for resubmission |
N7 | Decline CVV2 failure | Decline CVV2 failure |
N8 | Preauthorized amount exceeded | Transaction amount exceeds preauthorized approval amount |
Q1 | Card authentication failed | Card authentication failed |
R0 | Stop payment order | Cardholder canceled this specific recurring/installment payment |
R1 | Revocation of authorization | Cardholder canceled all recurring/installment payments for this merchant |
R2 | Transaction not qualified | The transaction does not qualify for Visa PIN |
R3 | Revocation of authorization | Canceled all recurring payments |
T0 | First time check | First time check |
T1 | Check valid - not converted | Check is OK but cannot be converted |
T2 | Invalid transit routing | One 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. |
T3 | Amount exceeds service limit | Amount greater than established service limit |
T4 | Unpaid items | Unpaid items, failed negative file check |
T5 | Duplicate check number | Duplicate check number |
T6 | MICR error | MICR error |
T7 | Check limit exceeded | Too many checks (over merchant or bank limit) |
XA | Forward to issuer | Forward to issuer |
XD | Forward to issuer | Forward to issuer |
Y1 | Offline approved | Offline approved |
Y3 | Offline approved | Unable to go online; offline-approved |
Z1 | Offline declined | Offline declined |
Z3 | Offline declined | Unable to go online; offline-declined |
CV | Card type verification error | Card type verification error |
D3 | Invalid 3D-Secure cryptogram | Transaction failure due to missing or invalid 3D-Secure cryptogram |
EC | CID verification error | CID verification error |
M0 | Transaction not allowed | Canada Domestic debit transaction not allowed (Mastercard) |
P2 | Invalid biller information | Invalid biller information |
V1 | Daily threshold exceeded | Daily 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:
Code | Response Text | Description |
---|---|---|
X | Match | Street address and 9-digit ZIP code both match |
Y | Match | Street address and 5-digit ZIP code both match |
A | Partial Match | Street address matches, but both 5-digit and 9- digit ZIP code do not match |
W | Partial Match | Street address does not match, but 9-digit ZIP code matches |
Z | Partial Match | Street address does not match, but 5-digit ZIP code matches |
N | No Match | None of the following matches: street address, 5-digit ZIP code, or 9-digit ZIP code |
U | System Unavailable | Address information unavailable. Returned if non-U.S. AVS is not available or if the AVS in a U.S. bank is not functioning properly. |
R | System Unavailable | Retry - Issuer's system is unavailable or timed out. |
E | Invalid | AVS data is invalid |
S | Not Supported | U.S. issuing bank does not support AVS |
D | Match | Street address and postal code match for international transaction |
M | Match | Street address and postal code match for international transaction |
B | Partial Match | Street address matches for international transaction. Postal code not verified due to incompatible formats. |
P | Partial Match | Postal codes match for international transaction, but street address not verified due to incompatible formats. |
C | No Match | Street address and postal code not verified for international transaction due to incompatible formats. |
I | No Match | Address information not verified by the international issuer |
G | Not Supported | Non-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:
Code | Description |
---|---|
M | CVV2 Match |
N | CVV2 No Match |
P | Not Processed |
S | Issuer indicates that CVV2 data should be present on the card, but the merchant has indicated the data is not present on the card. |
U | Issuer 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:
Code | Description |
---|---|
01 | Manual entry |
02 | Magnetic strip |
03 | Bar code |
04 | OCR entry |
05 | Chip card, CVV available |
07 | Contactless card |
09 | E-commerce |
90 | Magnetic stripe (track 2) |
91 | Contactless card |
95 | Chip card, no CVV |
Updated 12 months ago