Follow this guide to tokenize a payment method and add it to a customer profile. This creates a card ID that you can use for Payment Gateway API requests in lieu of the card number. See Add a Payment Method in API Reference for field definitions.

Please note:

There is no limit to the number of payment methods you can add to a customer profile.
By default, Customer Vault designates the first payment method added as the primary payment method, which is used for subscription payments.
Use the Set Primary Payment Method request to change a customer's primary payment method.

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.)
Follow the steps in the Add a Customer guide to create a customer profile. Save the customer_id value from the request response.

Implement

Write a POST request. For the request endpoint, insert the customer_id value between customer/ and /billing. The resulting endpoint is /platform/vault/customer/{customer_id}/billing, where the value replaces {customer_id}.

See the url in the sample header below:

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

Payment Card Information

To add payment card information, add the fields below to the body of your request. Either a card_number or a card_id is required for this request. See the sample code below:

{
     "card_id": "86e1b00d9b0811e68df3069d8f743581",
     "card_number": "4111111111111111",
     "exp_date": "0420",
     "cvv2": "152"
}

ACH Information

To add ACH payment information, add the fields below to the body of your request. A card_id is required in this case. For more on adding ACH payment information, see Customer Vault Conventions for ACH.

See the sample code below:

{
     "card_id": "86e1b00d9b0811e68df3069d8f743581",
     "type_id": "S",
     "tr_number": "011111111",
     "dda_number": "3456776866"
}

Customer Billing Information

Use the fields below to add the customer's billing information, such as email and billing addresses. A billing name (first and last) is required when adding an ACH payment method. See the sample code below:

{
     "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"
}

Payment Settings

Use the fields below to add optional settings for the payment method you are adding. This includes requiring verification and setting this method as the customer's primary payment method. Add a merchant_id if you are sending this request on behalf of another merchant. See the sample code below:

{
     "verify": true,
     "primary": true,
     "merchant_id": 210000000289
}

Example Request

Once configured, your request will resemble the following code:

curl --request POST \
     --url https://api-test.maast.com/platform/vault/customer/{customer_id}/billing \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
     "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
}
'

Integrate

Send the configured request to your customized endpoint.

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 payment method to the customer's profile in Customer Vault. If the value is something other than 0, check Platform API Response Codes in Reference.

Please note:

You can use this payment method by specifying the card ID that you sent in this request.
If this is the customer's primary payment method, you can use this payment method by simply providing their customer ID.

See Add a Payment Method in API Reference for response field definitions.

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.