This guide shows you how to use the Maast Payment Gateway API to process sale transactions for card payments or ACH. A sale transaction requests authorization and immediately captures the transaction if approved. The captured transaction will be included in the next batch close. Use a sale transaction in card-present environments as well as card-not-present environments where no physical goods are being shipped. See Sale (Auth + Capture) 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.)
Follow the steps in the API: Quick Start guide to set up a basic sale transaction.

Implement

The sections below describe the types of data you can include with your request to the API endpoint to implement a sale request. See Sale (Auth + Capture) in API Reference for field definitions.

Merchant and Integrator Information

Use the fields in the following sample code to add further merchant or integrator information to the body of the request. 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:

{
     "vendor_id": 212100026512,
     "profile_id": "21200001000300000978",
     "loc_id": "0001",
     "dba_name": "SHOE CO", 
     "developer_id": "CompanyV2.0"
}

Transaction Information

Use the fields in the sample code below to add transaction specifications to the body of the request. This can include fees and taxes, currency, permission for partial payments, and recurring transaction information.

For a recurring transaction, do the following:

Include moto_ecomm_ind set to 2. Do this for payments at all points in the subscription cycle, including startup fees and reduced trial periods.
If you are using any type of trial period, you must inform via the payload when the trial period is over by including dba_suffix with one of the following values: END DSCNT, END OFFER, END PROMO, or END TRIAL.

See the following sample code:

{
     "amt_tran": 1193.5,
     "amt_tran_fee": 2.35,
     "amt_convenience_fee": 2,
     "amt_tax": 93.5,
     "partial_auth": true,
     "amt_fbo": 1.5,
     "fbo_id": 999000000001,
     "tran_currency": 840,
     "moto_ecomm_ind": "2", 
     "dba_suffix": "END PROMO"
}

Tokenization

To save payment information, include tokenize set to true and one of the following:

card_number
card_swipe
tr_number and dda_number.

Include card_id to save the information to an existing card ID. Refer to Card or Bank Account Data Sources and Conditional Requirements for more information. See the sample code below:

{
     "tokenize": true,
     "card_number": "4111111111111111",
     "card_swipe": ";4111111111111111=08051010912345678901?8",
     "tr_number": "011111111",
     "dda_number": "3456776866",
     "card_id": "86e1b00d9b0811e68df3069d8f743581"
}

Saved Customer Data

Add fields to the body of the request that invoke previously tokenized payment information. See the sample code below:

{
     "customer_id": "JOECUSTOMER_12",
     "card_id": "86e1b00d9b0811e68df3069d8f743581",
     "subscription_id": 1234
}

Card Authorization

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",
     "customer_code": "PO # abc123",
     "avs_zip": "94402",
     "card_number": "4111111111111111",
     "exp_date": "0930",
     "cvv2": "152",
     "client_ip": "10.1.1.4",
     "duplicate_seconds": 300,
     "auth_code": "620376",
     "card_swipe": ";4111111111111111=08051010912345678901?8",
     "emv_tran_id": "ASNFZ4nwEjR1We3I85BI70V9nifASNFZ4jwHyL0U="
}

3-D Secure Values

To use 3-D Secure with the Maast Payment Gateway API, you must have a third-party MPI service.

Follow these steps to use 3-D Secure:

Make a service call to your MPI service. This returns values to include in an Authorization request.
Include the values in the appropriate fields in the body of your request.

See the following sample code for possible fields to include:

{
     "cavv_3ds": "ASNFZ4kBI0VniQEjRWeJASNFZ4k=",
     "xid_3ds": "ASNFZ4kBI0VniQEjRWeJASNFZ4k=",
     "mc_ucaf_data": "ASNFZ4nwEjRWeI8BI0VnifASNFZ4jwHyL0U=",
     "mc_ucaf_ind": "2"
}

ACH Authorization

Use the fields in the following sample code to add ACH authorization information to the body of the request. See ACH Sale Conventions for more information:

{
     "type_id": "S",
     "tr_number": "011111111",
     "dda_number": "3456776866"
}

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.

Customer Data

Add customer information to the payload using customer_id or a customer object with address information. See the sample code below:

{
     "customer_id": "JOECUSTOMER_12",
     "customer": {
          "billing_addr1": "123 Main Street",
          "billing_addr2": "Suite #1234",
          "billing_city": "San Mateo",
          "billing_country": "USA",
          "billing_country_code": "840",
          "billing_state": "CA",
          "billing_zip": "94402",
          "billing_zip4": "1234",
          "customer_email": "[email protected]",
          "customer_firm_name": "CompanyXYZ",
          "customer_first_name": "Joe",
          "customer_last_name": "Smith",
          "customer_phone": "6503885200",
          "shipping_addresses": [
               {
                    "primary": true,
                    "shipping_addr1": "1234 Main Street",
                    "shipping_addr2": "Ste 123",
                    "shipping_city": "San Mateo",
                    "shipping_country": "USA",
                    "shipping_country_code": "840",
                    "shipping_firm_name": "CompanyXYZ",
                    "shipping_first_name": "Joe",
                    "shipping_last_name": "Smith",
                    "shipping_state": "CA",
                    "shipping_zip": "94402",
                    "shipping_zip4": "1234"
               }
          ]
     }
}

Transaction Response Information

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

{
     "echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]",
     "line_items": "[{\"quantity\": \"1\",\"description\": \"Traffic Cones\", \"unit_of_measure\": \"each\", \"product_code\": \"SKU-123\", \"debit_credit_ind\": \"D\", \"unit_cost\": \"14.99\"},{\"quantity\": \"3\", \"description\": \"Spray Paint\", \"unit_of_measure\": \"EA\", \"product_code\": \"SKU-456\", \"debit_credit_ind\": \"D\", \"unit_cost\": \"5.00\"}]", 
     "purchase_id": "55-1212",
     "email_receipt": true,
     "email_address": [
          "[email protected]",
          "[email protected]"
     ],
     "customer_email": "[email protected]",
     "merch_ref_num": "ITEM 16126 Purchased 12-15-2016",
     "report_data": "[ {\"shipping address\" : \"123 Main St.\"},{\"shipping city, state zip\" : \"San Mateo, CA 94402\"} ]",
     "session_id": "string", 
     "user_id": 0
}

Example Request

Once configured, the code for your API sale request will resemble the following sample:

curl --request POST \
     --url https://api-test.maast.com/pg/sale \
     --header 'Accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'Content-Type: application/json' \
     --data '
{
     "merchant_id": "210000000289",
     "amt_convenience_fee": 2,
     "amt_fbo": 1.5,
     "amt_tax": 93.5,
     "amt_tran": 1193.5,
     "amt_tran_fee": 2.35,
     "auth_code": "620376",
     "avs_address": "123 Main St",
     "avs_zip": "94402",
     "card_id": "86e1b00d9b0811e68df3069d8f743581",
     "card_number": "4111111111111111",
     "card_swipe": ";4111111111111111=08051010912345678901?8",
     "cardholder_name": "JOHN CUSTOMER",
     "cavv_3ds": "ASNFZ4kBI0VniQEjRWeJASNFZ4k=",
     "client_ip": "10.1.1.4",
     "customer": {
          "billing_addr1": "123 Main Street",
          "billing_addr2": "Suite #1234",
          "billing_city": "San Mateo",
          "billing_country": "USA",
          "billing_country_code": "840",
          "billing_state": "CA",
          "billing_zip": "94402",
          "billing_zip4": "1234",
          "customer_email": "[email protected]",
          "customer_firm_name": "CompanyXYZ",
          "customer_first_name": "Joe",
          "customer_last_name": "Smith",
          "customer_phone": "6503885200",
          "shipping_addresses": [
               {
                    "primary": true,
                    "shipping_addr1": "1234 Main Street",
                    "shipping_addr2": "Ste 123",
                    "shipping_city": "San Mateo",
                    "shipping_country": "USA",
                    "shipping_country_code": "840",
                    "shipping_firm_name": "CompanyXYZ",
                    "shipping_first_name": "Joe",
                    "shipping_last_name": "Smith",
                    "shipping_state": "CA",
                    "shipping_zip": "94402",
                    "shipping_zip4": "1234"
               }
          ]
     },
     "customer_code": "PO # abc123",
     "customer_email": "[email protected]",
     "customer_id": "JOECUSTOMER_12",
     "cvv2": "152",
     "dba_name": "SHOE CO",
     "developer_id": "CompanyV2.0",
     "duplicate_seconds": 300,
     "echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]",
     "email_address": [
          "[email protected]",
          "[email protected]"
     ],
     "email_receipt": true,
     "emv_tran_id": "ASNFZ4nwEjR1We3I85BI70V9nifASNFZ4jwHyL0U=",
     "exp_date": "0930",
     "fbo_id": 999000000001,
     "line_items": "[{\"quantity\": \"1\",\"description\": \"Traffic Cones\", \"unit_of_measure\": \"each\", \"product_code\": \"SKU-123\", \"debit_credit_ind\": \"D\", \"unit_cost\": \"14.99\"},{\"quantity\": \"3\", \"description\": \"Spray Paint\", \"unit_of_measure\": \"EA\", \"product_code\": \"SKU-456\", \"debit_credit_ind\": \"D\", \"unit_cost\": \"5.00\"}]",
     "loc_id": "0001",
     "mc_ucaf_data": "ASNFZ4nwEjRWeI8BI0VnifASNFZ4jwHyL0U=",
     "mc_ucaf_ind": "2",
     "merch_ref_num": "ITEM 16126 Purchased 12-15-2016",
     "moto_ecomm_ind": "1",
     "partial_auth": true,
     "payload_google_pay": "xxxxxxx",
     "payload_apple_pay": "xxxxxxx",
     "pg_id": "d24ac6189b0b11e6966ca68d5edbef41",
     "profile_id": "21200001000300000978",
     "purchase_id": "55-1212",
     "report_data": "[ {\"shipping address\" : \"123 Main St.\"},{\"shipping city, state zip\" : \"San Mateo, CA 94402\"} ]",
     "session_id": "string",
     "subscription_id": 1234,
     "tokenize": true,
     "tran_currency": 840,
     "user_id": 0,
     "xid_3ds": "ASNFZ4kBI0VniQEjRWeJASNFZ4k=",
     "dba_suffix": "END PROMO",
     "dda_number": "3456776866",
     "tr_number": "011111111",
     "type_id": "S",
     "vendor_id": 212100026512
}
'

Integrate

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

Maast will return a response like the code below:

{
  "merchant_advice_code": "M001",
  "pg_id": "d24ac6189b0b11e6966ca68d5edbef41",
  "rcode": "000",
  "rmsg": "Approved T37500",
  "card_id": "86e1b00d9b0811e68df3069d8f743581",
  "auth_code": "T37500",
  "auth_avs_result": "X",
  "auth_cvv2_result": "M",
  "echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]",
  "amt_tran": 62.87
}

Check the rcode field. 000 confirms a successful transaction. If rcode is a value other than 000, check Payment Gateway API Response Codes in API Conventions, and see the Maast Knowledge Base for Visa and Mastercard decline codes. Be aware of decline codes that trigger extra fees, especially if you plan to retry the request.

🚧
Be aware of transaction decline codes that trigger extra fees, and note the number of times you retry a declined request.

See Sale (Auth + Capture) 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.