This guide shows you how to use API to add a customer to Customer Vault, creating a unique profile and customer ID. Maast securely stores all of the customer's data to their personal profile. You can use the customer ID to create invoice and subscription payments and to edit the customer's information. See Add a Customer in API Reference for field definitions.

Prerequisites

See Create a Sandbox Account to sign up and log in to the Maast Manager portal.
Follow the steps in Get Your API Credentials to save a sandbox ID and API key.
See Authentication to format the credentials and generate your API token. (Alternatively, use the credentials as-is to test this endpoint with our 'Try It!' feature.)

Implement

Write a POST request to send to the /platform/vault/customer endpoint. See the sample code below:

curl --request POST \
     --url https://api-test.maast.com/platform/vault/customer \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'Content-Type: application/json' \

Customer ID

Add a customer ID for the new profile to the body of the request. This is required. Do this one of two ways:

customer_id - Add the customer_id field with a unique alphanumeric ID.
auto_generate_customer_id - Add this boolean and set it to true, and Maast will generate a unique customer ID.

See the sample code below:

{
     "customer_id": "JOHNDOE",
     "auto_generate_customer_id": true
}

Customer Name or Firm Name

Either the customer's name or a firm name is required in the body of this request. You may include both. See the sample code below:

{
     "customer_first_name": "JOHN",
     "customer_last_name": "Doe",
     "customer_firm_name": "CompanyXYZ"
}

Customer Information

You can submit additional customer information in the body of this request, including shipping address and payment information. Note:

This is not required; you can add and edit information in the customer's profile later.
For more on adding ACH payment information, see Customer Vault Conventions for ACH.

See the sample code below:

{
     "customer_phone": "999-999-9999",
     "customer_email": "[email protected]",
     "shipping_addresses": [
          {
               "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_country": "United States",
               "shipping_country_code": "840",
               "shipping_zip": "94402",
               "shipping_zip4": "1234",
               "primary": true,
               "merchant_id": 210000000289
          }
     ],
     "billing_cards": [
          {
               "card_number": "4111111111111111",
               "exp_date": "0420",
               "cvv2": "152",
               "type_id": "S",
               "tr_number": "011111111",
               "dda_number": "3456776866",
               "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",
               "verify": true,
               "primary": true,
               "merchant_id": 210000000289
          }
     ],
}

Merchant Information

In the request body, you can include additional information of use to the merchant, and you can send a merchant_id value if you are sending this request on behalf of another merchant. See the sample code below:

{
     "reference_id": "678909",
     "comments": "Test comment",
     "developer_id": "CompanyV2.0",
     "merchant_id": 210000000289
}

Example Request

Once you have configured your request, it will resemble the sample code below:

curl --request POST \
     --url https://api-test.maast.com/platform/vault/customer \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'Content-Type: application/json' \
     --data '
{
     "customer_id": "JOHNDOE",
     "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",
     "shipping_addresses": [
          {
               "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_country": "United States",
               "shipping_country_code": "840",
               "shipping_zip": "94402",
               "shipping_zip4": "1234",
               "primary": true,
               "merchant_id": 210000000289
          }
     ],
     "billing_cards": [
          {
               "card_number": "4111111111111111",
               "exp_date": "0420",
               "cvv2": "152",
               "type_id": "S",
               "tr_number": "011111111",
               "dda_number": "3456776866",
               "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",
               "verify": true,
               "primary": true,
               "merchant_id": 210000000289
          }
     ],
     "merchant_id": 210000000289
}
'

Integrate

Send the request to the /platform/vault/customer endpoint with your configurations in the body.

Maast will return a response like the code below:

{
  "code": 0,
  "message": "Success",
  "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"
      }
    ]
  }
}

Check the code field in the request response: 0 confirms that you have successfully added the customer to Customer Vault. If the value is something other than 0, check Platform API Response Codes in Reference.

Check the customer_id field and save its value to your records. You can now use this customer ID to initiate payments for the customer, subscribe them to a Recurring Billing plan, add information to the customer's profile, and edit profile information.

See Add a Customer in API Reference for response field definitions.

🚧
Save the Customer ID
Be sure to save the customer_id value that appears in your request response. You will need it to interact with this customer's profile using Maast APIs.

Test and Go Live

See our Test and Go Live guide to test your API integration and to start transacting with an active production account.

Prerequisites

Implement

Customer ID

Customer Name or Firm Name

Customer Information

Merchant Information

Example Request

Integrate

🚧Save the Customer ID

Test and Go Live

🚧
Save the Customer ID