Create ACH Return

curl --request POST \
  --url https://int-api.mx.com/ach_returns \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://int-api.mx.com/ach_returns"

payload = {}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://int-api.mx.com/ach_returns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://int-api.mx.com/ach_returns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://int-api.mx.com/ach_returns"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://int-api.mx.com/ach_returns")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://int-api.mx.com/ach_returns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "ach_return": {
    "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "account_number_last_four": "1234",
    "account_type": "CREDIT",
    "ach_initiated_at": "2025-02-13T18:08:00+00:00",
    "client_guid": "CLT-abcd-1234",
    "corrected_account_number": null,
    "corrected_routing_number": null,
    "created_at": null,
    "guid": "ACH-d74cb14f-fd0a-449f-991b-e0362a63d9c6",
    "id": "client_ach_return_id_1234",
    "institution_guid": "INS-34r4f44b-cfge-0f6e-3484-21f47e45tfv7",
    "investigation_notes": null,
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "processing_errors": null,
    "resolution_code": null,
    "resolution_detail": null,
    "resolved_status_at": null,
    "return_code": "R01",
    "return_notes": null,
    "return_account_number": null,
    "return_routing_number": null,
    "return_status": "SUBMITTED",
    "returned_at": "2025-02-13T18:09:00+00:00",
    "sec_code": "PPD",
    "started_processing_at": null,
    "submitted_at": null,
    "transaction_amount": 225.84,
    "updated_at": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

POST

ach_returns

Create ACH Return

curl --request POST \
  --url https://int-api.mx.com/ach_returns \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

url = "https://int-api.mx.com/ach_returns"

payload = {}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://int-api.mx.com/ach_returns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://int-api.mx.com/ach_returns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://int-api.mx.com/ach_returns"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://int-api.mx.com/ach_returns")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://int-api.mx.com/ach_returns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "ach_return": {
    "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
    "account_number_last_four": "1234",
    "account_type": "CREDIT",
    "ach_initiated_at": "2025-02-13T18:08:00+00:00",
    "client_guid": "CLT-abcd-1234",
    "corrected_account_number": null,
    "corrected_routing_number": null,
    "created_at": null,
    "guid": "ACH-d74cb14f-fd0a-449f-991b-e0362a63d9c6",
    "id": "client_ach_return_id_1234",
    "institution_guid": "INS-34r4f44b-cfge-0f6e-3484-21f47e45tfv7",
    "investigation_notes": null,
    "member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "processing_errors": null,
    "resolution_code": null,
    "resolution_detail": null,
    "resolved_status_at": null,
    "return_code": "R01",
    "return_notes": null,
    "return_account_number": null,
    "return_routing_number": null,
    "return_status": "SUBMITTED",
    "returned_at": "2025-02-13T18:09:00+00:00",
    "sec_code": "PPD",
    "started_processing_at": null,
    "submitted_at": null,
    "transaction_amount": 225.84,
    "updated_at": null,
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

The features documented here are in a beta state, and this documentation is considered draft material subject to frequent change.

Use this endpoint to create an ACH return in our system.

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json

ACH return object to be created.

ach_return

object

Hide child attributes

ach_return.account_guid

string

required

The unique identifier for the account associated with the transaction. Defined by MX.

Example:

"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1"

ach_return.id

string

required

Client-defined identifier for this specific return submission. Allows you to track and reference you requests.

Example:

"client_ach_id_1234"

ach_return.member_guid

string

required

The unique identifier for the member associated with the transaction. Defined by MX.

Example:

"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b"

ach_return.return_code

string

required

The associated ACH return code and notice of change code (for example, R02, R03, R04, R05, R20, NOC). See Return Codes for a complete list.

Example:

"R01"

ach_return.user_guid

string

required

MX-defined identifier for the user associated with the ACH return.

Example:

"USR-fa7537f3-48aa-a683-a02a-b18940482f54"

ach_return.account_number_last_four

string

The last 4 digits of the account number used for the transaction by the Originating Depository Financial Institution (ODFI).

Example:

"1234"

ach_return.ach_initiated_at

string

The date and time when the transaction was initiated by the Originating Depository Financial Institution (ODFI) in ISO 8601 format without timestamp.

Example:

"2025-02-13T18:08:00+00:00"

ach_return.corrected_account_number

string

The account number correction reported by the RDFI. Populate only if the resolution_code is NOTICE_OF_CHANGE.

Example:

null

ach_return.corrected_routing_number

string

The routing number correction reported by the RDFI. Populate only if the resolution_code is NOTICE_OF_CHANGE. Must be a valid 9-digit routing number format.

Example:

null

ach_return.return_account_number

string

Incorrect account number used in the ACH transaction.

Example:

null

ach_return.return_notes

string

Notes that you set to inform MX on internal ACH processing.

Example:

null

ach_return.return_routing_number

string

Incorrect routing number used in the ACH transaction.

Example:

null

ach_return.returned_at

string

The date and time when the return was reported by the Receiving Financial Depository Institution (RDFI) in ISO 8601 format without timestamp.

Example:

"2025-02-13T18:09:00+00:00"

ach_return.sec_code

string

The SEC code (Standard Entry Class Code)–a three-letter code describing how a payment was authorized (for example, WEB). See SEC Codes for a complete list.

Example:

"PPD"

ach_return.transaction_amount

number

The amount of the transaction.

Example:

225.84

ach_return.transaction_amount_range

number

The transaction amount range, used for impact assessment.

Example:

null

Response

200 - application/vnd.mx.api.v1+json

ach_return

object

Hide child attributes

ach_return.account_guid

string

Example:

"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1"

ach_return.account_number_last_four

string | null

Example:

"1234"

ach_return.account_type

string | null

Example:

"CREDIT"

ach_return.ach_initiated_at

string | null

Example:

"2025-02-13T18:08:00+00:00"

ach_return.client_guid

string

Example:

"CLT-abcd-1234"

ach_return.corrected_account_number

string | null

Example:

null

ach_return.corrected_routing_number

string | null

Example:

null

ach_return.created_at

string

Example:

null

ach_return.guid

string

Example:

"ACH-d74cb14f-fd0a-449f-991b-e0362a63d9c6"

ach_return.id

string

Example:

"client_ach_return_id_1234"

ach_return.institution_guid

string

Example:

"INS-34r4f44b-cfge-0f6e-3484-21f47e45tfv7"

ach_return.investigation_notes

string | null

Example:

null

ach_return.member_guid

string

Example:

"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b"

ach_return.processing_errors

string | null

Example:

null

ach_return.resolution_code

string | null

Example:

null

ach_return.resolution_detail

string | null

Example:

null

ach_return.resolved_status_at

string | null

Example:

null

ach_return.return_code

string

Example:

"R01"

ach_return.return_notes

string | null

Example:

null

ach_return.return_account_number

string | null

Example:

null

ach_return.return_routing_number

string | null

Example:

null

ach_return.return_status

string | null

Example:

"SUBMITTED"

ach_return.returned_at

string | null

Example:

"2025-02-13T18:09:00+00:00"

ach_return.sec_code

string | null

Example:

"PPD"

ach_return.started_processing_at

string | null

Example:

null

ach_return.submitted_at

string | null

Example:

null

ach_return.transaction_amount

number<double> | null

Example:

225.84

ach_return.updated_at

string

Example:

null

ach_return.user_guid

string

Example:

"USR-fa7537f3-48aa-a683-a02a-b18940482f54"

List ACH Returns