API Reference

Authentication

Maast uses HTTP Authentication to control access to our APIs. This page describes how to obtain API credentials and use them to authenticate your requests to our endpoints.

Here's an overview of the process:

  1. Get your credentials - Obtain your API credentials from the Maast Manager portal. You will need your merchant ID and your API key. If you are a Maast Partner, you will need your vendor ID and vendor API key.
  2. Format your API key - Put a colon in front of your API key. The result looks like :api_key.
  3. Generate your API token - Base 64 the formatted key from step 2 to create your authentication token. The result looks like OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz.
  4. Send a test request - Send your token in the Authorization header of your API request, as in Authorization:Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz.

See the sections below for details on each step.


1. Get Your Credentials

The steps below show you how to create a sandbox account and use it to obtain your merchant ID and API key.

Sign Up

Follow the steps in Create a Sandbox Account to set up and sign into a sandbox account in the Maast Manager portal, where you will get your API credentials. You can create a sandbox account for the Maast Merchant portal or the Maast Partner portal.

This sends you to your open sandbox portal, where you can access merchant or vendor test credentials.

Merchant ID and API Key

Follow the instructions in Merchant API Credentials to generate an API security key and obtain your sandbox merchant ID.

You can use this merchant ID and API key to test all Maast API functions that the API key can access:

  • For the 'Try It!' feature, use your merchant ID and API key as-is; no need to encode them.

  • To send a request from your own system, you must format and base 64 encode these credentials for the API token you will use. See steps 2-4 below to do so.

Vendor ID and API Key

To test Maast Partner tools, follow the steps in Partner API Credentials to create a vendor API security key and a vendor ID (also referred to as an integrator ID).

You can use this vendor ID and vendor API key to test all Maast API functions that your vendor API key can access:

  • For the 'Try It!' feature, use your vendor ID and API key as-is; no need to encode them. Put your vendor API key in the 'password' field (not the merchant API key).

  • To send a request from your own system, you must format and base 64 encode your vendor ID and vendor API key for the token you will use. See steps 2-4 below to do so, substituting your vendor ID and vendor API key wherever it calls for merchant ID and API key, respectively.


2. Format Your Credentials

Format your merchant API key by putting a colon in front of it. The result reads :api_key, where your key replaces api_key.

See an example of the credentials and formatting below:

✅

Example

API key 9edec21a31c0xyz789e30a3416abc123
Formatted API key :9edec21a31c0xyz789e30a3416abc123


3. Generate Your API Token

Base 64 the formatted key to create your authentication token.

To keep your credentials secure, you can use Powershell in Windows or Terminal in Mac to encode the string. Using the example from above, the entry looks like this:

  • In Powershell: return [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":9edec21a31c0xyz789e30a3416abc123"))
  • In Terminal echo -n ':9edec21a31c0xyz789e30a3416abc123' | base64

Capture the result and use it in the next section to send a test request to the API.

Continuing the example from above:

✅

Example

API key 9edec21a31c0xyz789e30a3416abc123
Formatted API key :9edec21a31c0xyz789e30a3416abc123
Token OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz


4. Send a Test Request

Add your authentication token to the request below and paste it in to your terminal to test your API authentication. See the sample code below:

curl --request GET \
     --url 'https://api-test.maast.com/platform/vault/customer?count=10&order_on=customer_id&order_by=desc&page=0&merchant_id=0' \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz'

You should get a response that looks like this:

{
  "code": 0,
  "message": "Success",
  "totalPages": 10,
  "totalRecords": 100,
  "data": [
    {
      "customer_id": "JOHNDOE",
      "rec_id": 0,
      "node_id": 210000000289,
      "customer_first_name": "JOHN",
      "customer_last_name": "Doe",
      "customer_firm_name": "CompanyXYZ",
      "customer_phone": "999-999-9999",
      "customer_email": "[email protected]",
      "reference_id": "678909",
      "comments": "Test comment",
      "developer_id": "CompanyV2.0",
      "primary_card_number": "411111xxxxxx1111",
      "shipping_addresses": [
        {
          "shipping_id": 12345,
          "shipping_first_name": "John",
          "shipping_last_name": "John",
          "shipping_firm_name": "CompanyXYZ",
          "shipping_addr1": "123 Main Street",
          "shipping_addr2": "#1234",
          "shipping_city": "San Mateo",
          "shipping_state": "CA",
          "shipping_zip": "94402",
          "shipping_zip4": "1234",
          "shipping_country": "United States",
          "shipping_country_code": "840",
          "primary": true
        }
      ],
      "billing_cards": [
        {
          "card_number": "411111xxxxxx1111",
          "exp_date": "0420",
          "card_id": "86e1b00d9b0811e68df3069d8f743581",
          "billing_first_name": "John",
          "billing_last_name": "Doe",
          "billing_firm_name": "CompanyXYZ",
          "billing_email": [
            "[email protected]",
            "[email protected]"
          ],
          "billing_addr1": "123 Main Avenue",
          "billing_addr2": "#1234",
          "billing_city": "San Mateo",
          "billing_state": "CA",
          "billing_zip": "94402",
          "billing_zip4": "1234",
          "billing_country": "United States",
          "billing_country_code": "840",
          "primary": true,
          "card_type": "VS",
          "verified_date": "20160530000000"
        }
      ]
    }
  ]
}

Once you are satisfied with your API integration, see our Test and Go Live guide to perform recommended tests, apply for a production account, and update your integration to start transacting.