Void

Void a transaction with our Payment Gateway API.

Suggest Edits

This guide shows you how to send a void request with the Maast Payment Gateway API to cancel a previously authorized transaction. See Void a Previously Authorized Transaction in our API Reference for field definitions.

Please note:

  • You can void an authorized transaction at any time until Maast automatically voids it at 28 days.
  • You can void a captured transaction until its batch is closed.
  • The default batch close time is 9 p.m. PST (U.S.), but you can configure it to any time.
  • If your batch closes and you did not void the transaction in time, you may make a Refund request.
  • Vendor accounts need special permissions to use this operation; contact Maast Support to enable it.

See ACH Void Conventions for information on void requests for ACH payments.


Prerequisites

  1. See Create a Sandbox Account to sign up and log in to the Maast Manager portal.

  2. Follow the steps in Get Your API Credentials to save a sandbox ID and API key.

  3. 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.)

  4. Identify the Payment Gateway ID of a transaction you wish to void:

    • The Payment Gateway ID is listed as pg_id in the response to the original transaction, as in the API: Quick Start example response.
    • In the void request, this value will be entered as the path parameter pgIdOrig.
    • If you do not have a transaction to void but wish to test this function, follow the steps in API: Quick Start to set up a basic sale transaction to void.

Implement

Write a POST request and include your sandbox merchant ID in the body.

For the request endpoint, append the Payment Gateway ID of the transaction you wish to void to the end of /pg/void/. The resulting endpoint is /pg/void/pgIdOrig, where the ID number replaces pgIdOrig. See the sample code below:

curl --request POST \
     --url https://api-test.maast.com/pg/void/efgbe295c41611edb32402171867ecb2 \
     --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 void request. See Void a Previously Authorized Transaction in our API Reference for field definitions.

Merchant and Integrator Information

Use the fields in the following sample code to add further merchant information to the body of the request. If you are an integrator, you must include your integrator ID in the vendor_id field:

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

Response Information

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

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

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

curl --request POST \
     --url https://api-test.maast.com/pg/void/efgbe295c41611edb32402171867ecb2 \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-Type: application/json' \
     --data '
{
     "merchant_id": "<Provide merchant id that links to API Key>",
     "developer_id": "CompanyV1.2",
     "echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]",
     "loc_id": "0001",
     "profile_id": "21200001000300000978",
     "report_data": "[ {\"shipping address\" : \"123 Main St.\"},{\"shipping city, state zip\" : \"San Mateo, CA 94402\"} ]",
     "session_id": "string",
     "user_id": 0,
     "vendor_id": 212100026512
}
'

Integrate

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

Maast will return a response like the code below:

{
  "pg_id": "d24ac6189b0b11e6966ca68d5edbef41",
  "rcode": "000",
  "rmsg": "Transaction Voided",
  "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 Void a Previously Authorized Transaction 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.


Updated 4 months ago