Maast APIs offer a wide range of endpoints to set up a fully customized experience or simply support Hosted Checkout or embedded fields integrations. The documentation on this site guides you through API setup and testing.

This page holds general information relevant to any Maast API request. The Quick Start guide shows how to integrate and test a basic sale transaction. The remaining API guide sections give general information on each API resource and integration instructions for its most important functions. Embedded Fields--a separate developer docs category--contains information on the Embedded Fields API resource. API Reference provides field definitions and sample requests/responses for all API functions.

Maast offers two main APIs that allow access to our resources from within your app:

• Payment Gateway API - This supports submitting requests for authentication, payment, and many other common payments functions.
• Platform API - This includes endpoints for functions one can find in the Maast Manager portal, such as reporting, setting up account features, and managing customer information.

The Payment Gateway API is POST-based, and it mainly relies on a body payload to deliver data. The Platform API uses many GET-based endpoints and query parameters.

API requests are organized into 13 different resources:

• Payment Gateway - Send 16 different transaction requests.
• Checkout - Create Dynamic Checkout links and get Checkout transaction data.
• Recurring Billing - Set up and manage plans and subscriptions.
• Customer Vault - Securely store and manage customer billing details.
• Payee Vault - Securely store and manage payee details.
• Invoicing - Create and manage customized invoices.
• Reporting - Access a wide range of reports on demand.
• Account Updater - Create and manage Account Updater requests to keep card information up-to-date.
• Disputes - Receive and manage payment card disputes.
• Webhooks - Create and manage automatic notifications of various events.
• Application Boarding - Generate and manage merchant onboarding applications.
• Integrator - Create test accounts and get merchant account data.
• Embedded Fields - Get a transient key for embedded fields integration.

The Payment Gateway resource uses the Payment Gateway API. All other resources use the Platform API.

Using Our APIs

There are two primary methods for accessing our APIs:

• through the use of our Swagger-generated SDKs;
• through programmatic and/or command line access.

For either method, our SDK bundles include helpful README documents in various programming languages to assist with the necessary syntax. We also provide our Platform or Payment Gateway OpenAPI (Swagger) specifications.

Security

Maast forces HTTPS on all inbound connections. Calls to non-HTTPS resources result in a HTTP 302 URL redirection to the HTTPS equivalent. Maast is a PCI DSS certified Level 1 compliant Service Provider. See below for information on security keys and authentication.

Security Keys

You should use an HTTP Basic base64 encoded API Key as the password in the authorization header of all requests to our APIs.

See Authentication in API Reference to retrieve an API key, generate an API token, and use the token in an authorization header.

You can create separate security keys for different functions. For example, you might create one key with access to Maast Checkout for your shopping cart integration and a second key with access to the transaction report for your accounting software. You can label your keys to easily distinguish between them.

Functional code samples for a variety of languages, along with a list of endpoints, can be found in our Swagger-generated SDKs.

Card or Bank Account Data Sources and Conditional Requirements

The following Payment Gateway API requests require card or bank account data: 'Authorize Transaction,' 'Sale (Auth + Capture),' 'Force Transaction Approval,' 'Issue Credit to Cardholder,' 'Verify,' and 'Tokenize.' See below for information on sending and saving payment data. See our Payment Gateway API Reference for field definitions.

Sending Payment Data

You may use any of these direct or indirect sources to provide the data:

• Direct sources: card_number, card_swipe, and tr_number/dda_number. No more than one of these can be sent in a single request.
• Indirect sources: card_id and customer_id. These reference account data that Maast stores securely.

Below are guidelines for including exp_date in 'Authorize,' 'Sale,' or 'Verify' requests:

• If you include card_number in the request, then exp_date is generally recommended.
• If you include card_id in the request, then exp_date is optional. In this case, sending exp_date will update the saved card_id data. Sending exp_date is not recommended if you plan to use the Account Updater service. (Account Updater provides and updates expiration dates for you.)
• If you use card_swipe or tr_number/dda_number in the request, then exp_date is not applicable.

You can use customer_id as the source of account data, or you can use it along with any other direct or indirect source listed above to associate the transaction with a customer.

Saving Payment Data

The Payment Gateway API can tokenize payment method information, saving it without creating a customer profile. This is distinct from Customer Vault; see Payment Method Storage for more information.

To save new account data to an existing card_id, do one of the following:

• Send a 'Tokenize' request with the following:
  • the card_id of your choice, and
  • one of the direct sources listed above.
• Send an 'Authorize,' 'Sale,' 'Force,' 'Credit,' or 'Verify' request with the following:
  • the card_id of your choice, and
  • one of the direct sources listed above, and
  • the tokenize field, set to true.

Filters

In many requests, you can use filter parameters to narrow the records that appear in the result. To do so, add ? to the end of the request endpoint, followed by the filter(s). If using multiple filters, use & to separate them.

Each filter contains three properties, packed together with commas:

• field name - All available fields are listed in the response model of your request's API reference.
• filter conditional - See the table below for supported conditionals.
• the value on which to filter

The example code below filters transactions within a date range:

https://app.maast.com/service/api/transactions?filter=tran_date,BETWEEN_DATES,2023-01-09,2024-01-10

You can combine multiple filters to narrow the results. The example below includes the date range filter shown above and also a filter to capture transactions for more than $100:

https://app.maast.com/service/api/transactions?filter=tran_date,BETWEEN_DATES,2016-01-09,2016-01-10&filter=amt_tran,GREATER,100

The table below shows all supported filter conditionals:

ACH Payments with API

This section provides information to assist in adding ACH payment capacity using our API.

APIs that Support ACH

Maast supports ACH payments in addition to credit card payments through the following API resources:

• Payment Gateway API
• Checkout API
• Invoicing API
• Recurring Billing API
• Embedded Fields API
• Customer Vault API

There is not a separate API for ACH payments. To add ACH payments, use one of the endpoints linked above and adjust the fields you send with your requests.

Supported ACH Features

Maast APIs support several features for ACH payments:

• Integration - Add ACH payments to your existing Maast Checkout, embedded fields, and Payment Gateway integration.
• Secure Storage - For repeat transactions, tokenize ACH payment information or save it to a customer profile in Customer Vault.
• Recurring Billing - Schedule recurring or installment ACH payments.
• Invoicing - Send invoices to your customers that can be paid with ACH or card payments.
• Notifications - Create webhooks to create automatic notifications for transaction status changes.
• Reporting - Use Maast’s Reporting API to extract your transaction, deposit, and reconciliation data from Maast’s system.

ACH Consent Statement Requirement

If you add ACH payments to your website using Maast's Payment Gateway API, Recurring Billing API resource, or embedded fields method, you must do the following:

• Add a consent statement to your website.
• Include a checkbox for your customer to indicate that they have read the statement and agree to the
  ACH payment.

If you use Maast Checkout or Invoicing API resources, Maast automatically adds the consent statement to your checkout page.

See a sample consent statement in ACH Conventions.

ACH Validation

Maast has integrated with a NACHA-certified provider to verify first-use account information per the NACHA WEB Debit Account Validation Rule. Note the following:

• Verification - Net-new requests to tokenize, verify, or transact with full ACH routing and account numbers collected via the internet will be sent for verification through our third-party provider.

• Authorization codes - Any ACH sale request will return the response from the NACHA-approved third-party in the auth_code field of the payment gateway response. An auth_code will not appear for sales on accounts that are not net-new because the accounts have already been validated. Details of ACH auth_codes are available in the ACH Authorization Code Responses table.

• Payment gateway response - After any request, the Payment Gateway API provides a description of the response in the rcode and rmsg fields. See the Payment Gateway API Response Codes table for responses to ACH transaction requests.

• Failure response - Most issues with ACH payments are reported to you with the payment gateway response code (rcode) of 119, "Invalid ACH payment." See ACH Response Code 119 Detail Codes and Descriptions for more information.

Configuring Your Deposit Account for ACH Payments

If you are using a deposit account at a bank that is not Maast, please note the following:

• You must ensure that your bank does not reject items due to account blocking and that it allows all potential debits and credits from the appropriate ACH payment identification numbers or company IDs.
• Once Maast has approved you for ACH payments, contact your bank to request that it enable debits against your account for the following company IDs: 1113358832 and 1880394610.
• A fee may be assessed if an attempt to debit your account fails due to missing company IDs.

Testing

Note the following information to test your API integration:

• Getting Started - Before testing your API integration, see Get Started to create a sandbox account and retrieve an API key, and then see Authentication in API Reference to generate an API token.
• Tools - You can test your API integration from your own system or through this site's 'Try It!' feature. Alternatively, you can use the Maast Manager sandbox portal to test portal functions like our Virtual Terminal.
• URLs - Find the base paths for testing Maast API requests below. Find the endpoint for each request in our API Reference. See API Conventions for test data.
• Go Live - Use our Test and Go Live guide to perform recommended tests, apply for a production account, and update your integration to go live.

Test Base Paths

Our two main APIs use distinct base paths. See the base paths here:

All Payment Gateway requests use the Payment Gateway API base path. All other requests use the Platform API base path.