Follow the guide below to use the Maast Payment Gateway API to send a refund request, which returns money to the cardholder from a previously captured payment card transaction. See Refund Previously Captured Transaction in our API Reference for field definitions.

Please note:

You may request multiple refunds per captured transaction as long as the sum of all refunds does not exceed the original captured transaction amount.
Refund requests made before batch close time in the same amount of the original sale transaction will be processed as a Void.
Refund requests made before batch close time in an amount less than the original sale transaction will receive a 'Capture Amount Reduced' response.
If your batch has already closed and you wish to request a refund, you must wait until your original Sale transaction's status is 'Deposit Sent.'
Vendor accounts need special permissions to use this operation; contact Maast Support to enable it.

See ACH Refund Conventions for information on ACH refund requests.

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.)
Identify the Payment Gateway ID of the transaction you wish to refund:
- 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 refund request, this value will be entered into the pgIdOrig field.
- If you do not have a transaction to refund but wish to test this function, follow the steps in the API: Quick Start guide to set up a basic Sale transaction to refund.

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 refund to the end of /pg/refund/. The resulting endpoint is /pg/refund/pgIdOrig , where the pg_id value (found in the response to the original transaction) replaces pgIdOrig. See the sample code below:

curl --request POST \
     --url https://api-test.maast.com/pg/refund/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 refund request. See Refund Previously Captured 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",
     "loc_id": "0001",
     "developer_id": "CompanyV1.2",
     "vendor_id": 212100026512
}

Refund Information

Use the field in the following sample code to add the refund amount to the body of the request:

{
     "amt_tran": 1193.5
}

Response Information

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

{
     "echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]",
     "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 refund request will resemble the following sample:

curl --request POST \
     --url https://api-test.maast.com/pg/refund/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>",
     "amt_tran": 1193.5,
     "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 the POST request to the /pg/refund/pgIdOrig endpoint with your configurations in the body.

Maast will return a response like the code below:

{
  "rcode": "000",
  "rmsg": "Transaction voided",
  "pg_id": "d24ac6189b0b11e6966ca68d5edbef41"
}

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 Refund Previously Captured 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.