To send a tokenize request with the Maast Payment Gateway API, see the guide below. Depending on its configuration, a tokenize request either (1) saves card or ACH payment information to a new card ID, or (2) updates information saved to an existing card ID. This is separate from Customer Vault storage; see Payment Method Storage for more information. See Tokenize in our 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 /pg/tokenize endpoint, including your sandbox merchant ID in the body. See the following sample code:

curl --request POST \
     --url https://api-test.maast.com/pg/tokenize \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
     "merchant_id": "<Provide merchant ID that links to API Key>"
}
'

Now you are ready to configure your request. The sections below describe the types of data you can include in your tokenize request. See Tokenize in API Reference for field definitions.

Merchant and Integrator Information

Use the fields in the following sample code to add information to the body of the request that associates the tokenized information with additional merchant information. This is helpful if you have more than one Payment Gateway profile or store location. If you are an integrator, you must include your integrator ID in the vendor_id field:

{
     "merchant_id": "210000000289",
     "profile_id": "21200001000300000978",
     "developer_id": "CompanyV1.2",
     "loc_id": "0001",
     "vendor_id": 212100026512
}

Card Information

Use the fields in the following sample code to add card authorization information to the body of the request:

{
     "cardholder_name": "JOHN CUSTOMER",
     "avs_address": "123 Main St",
     "avs_zip": "94402",
     "email_address": [
          "[email protected]",
          "[email protected]"
     ],
     "card_number": "4111111111111111",
     "exp_date": "0930"
     "cvv2": "152",
     "card_id": "86e1b00d9b0811e68df3069d8f743581",
     "card_swipe": ";4111111111111111=08051010912345678901?8",
     "client_ip": "10.1.1.4"
}

ACH Information

Use the fields in the following sample code to add ACH payment information to the body of the request:

{
     "tr_number": "011111111",
     "dda_number": "3456776866",
     "type_id": "S",
     "cardholder_name": "JOHN CUSTOMER"
}

Google Pay™ Authorization

Use the fields in the following sample code to add authorization information for Google Pay™ or Apple Pay™ to the body of the request:

{
     "payload_google_pay": "xxxxxxx",
     "payload_apple_pay": "xxxxxxx"
}

Note: If you wish to use Apple Pay™, please contact Maast Support.

Response Information

Use the fields in the following sample code to configure your transaction response:

{
     "single_use": true,
     "echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]",
     "session_id": "string",
     "user_id": 0,
     "report_data": "[ {\"shipping address\" : \"123 Main St.\"},{\"shipping city, state zip\" : \"San Mateo, CA 94402\"} ]"
}

Example Requests

Once configured, the code for your API tokenize request will resemble one of the following examples.

Below is a sample request to tokenize a new payment card:

curl --request POST \
     --url https://api-test.maast.com/pg/tokenize \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
  "exp_date": "0930",
  "merchant_id": "210000000289",
  "card_number": "4111111111111111",
  "cvv2": "152",
  "avs_address": "123 Main St",
  "avs_zip": "94402",
  "email_address": [
    "[email protected]",
    "[email protected]"
  ]
}
'

Below is a sample request to update the information on a payment card that is already tokenized:

curl --request POST \
     --url https://api-test.maast.com/pg/tokenize \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
  "exp_date": "0930",
  "merchant_id": "210000000289",
  "card_number": "4111111111111111",
  "card_id": "86e1b00d9b0811e68df3069d8f743581"
}
'

Below is a sample request to tokenize new ACH payment information:

curl --request POST \
     --url https://api-test.maast.com/pg/tokenize \
     --header 'Accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'Content-Type: application/json' \
     --data '
{
  "exp_date": "0930",
  "merchant_id": "210000000289",
  "tr_number": "011111111",
  "dda_number": "3456776866",
  "type_id": "S",
  "cardholder_name": "JOHN CUSTOMER"
}
'

Integrate

Send a POST request to the /pg/tokenize endpoint with your configurations in the body.

Maast will return a response like the code below:

{
  "rcode": "000",
  "rmsg": "Token request complete",
  "pg_id": "d24ac6189b0b11e6966ca68d5edbef41",
  "card_id": "86e1b00d9b0811e68df3069d8f743581",
  "card_number": "4111xxxxxx111111",
  "echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]"
}

Check the rcode field. 000 confirms a successful transaction. If rcode is a value other than 000, check Payment Gateway API Response Codes in Reference. See Tokenize 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.