curl --request POST \
--url https://int-api.mx.com/ach_returns \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"ach_return": {
"account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"account_number_last_four": "1234",
"ach_initiated_at": "2025-02-13T18:08:00+00:00",
"id": "client_ach_id_1234",
"member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
"return_code": "R01",
"returned_at": "2025-02-13T18:09:00+00:00",
"sec_code": "PPD",
"transaction_amount": 225.84,
"transaction_amount_range": 0,
"user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
}
}
'import requests
url = "https://int-api.mx.com/ach_returns"
payload = { "ach_return": {
"account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"account_number_last_four": "1234",
"ach_initiated_at": "2025-02-13T18:08:00+00:00",
"id": "client_ach_id_1234",
"member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
"return_code": "R01",
"returned_at": "2025-02-13T18:09:00+00:00",
"sec_code": "PPD",
"transaction_amount": 225.84,
"transaction_amount_range": 0,
"user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
} }
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({
ach_return: {
account_guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
account_number_last_four: '1234',
ach_initiated_at: '2025-02-13T18:08:00+00:00',
id: 'client_ach_id_1234',
member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
return_code: 'R01',
returned_at: '2025-02-13T18:09:00+00:00',
sec_code: 'PPD',
transaction_amount: 225.84,
transaction_amount_range: 0,
user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
}
})
};
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([
'ach_return' => [
'account_guid' => 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
'account_number_last_four' => '1234',
'ach_initiated_at' => '2025-02-13T18:08:00+00:00',
'id' => 'client_ach_id_1234',
'member_guid' => 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
'return_code' => 'R01',
'returned_at' => '2025-02-13T18:09:00+00:00',
'sec_code' => 'PPD',
'transaction_amount' => 225.84,
'transaction_amount_range' => 0,
'user_guid' => 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
]
]),
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("{\n \"ach_return\": {\n \"account_guid\": \"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1\",\n \"account_number_last_four\": \"1234\",\n \"ach_initiated_at\": \"2025-02-13T18:08:00+00:00\",\n \"id\": \"client_ach_id_1234\",\n \"member_guid\": \"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b\",\n \"return_code\": \"R01\",\n \"returned_at\": \"2025-02-13T18:09:00+00:00\",\n \"sec_code\": \"PPD\",\n \"transaction_amount\": 225.84,\n \"transaction_amount_range\": 0,\n \"user_guid\": \"USR-fa7537f3-48aa-a683-a02a-b18940482f54\"\n }\n}")
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("{\n \"ach_return\": {\n \"account_guid\": \"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1\",\n \"account_number_last_four\": \"1234\",\n \"ach_initiated_at\": \"2025-02-13T18:08:00+00:00\",\n \"id\": \"client_ach_id_1234\",\n \"member_guid\": \"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b\",\n \"return_code\": \"R01\",\n \"returned_at\": \"2025-02-13T18:09:00+00:00\",\n \"sec_code\": \"PPD\",\n \"transaction_amount\": 225.84,\n \"transaction_amount_range\": 0,\n \"user_guid\": \"USR-fa7537f3-48aa-a683-a02a-b18940482f54\"\n }\n}")
.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 = "{\n \"ach_return\": {\n \"account_guid\": \"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1\",\n \"account_number_last_four\": \"1234\",\n \"ach_initiated_at\": \"2025-02-13T18:08:00+00:00\",\n \"id\": \"client_ach_id_1234\",\n \"member_guid\": \"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b\",\n \"return_code\": \"R01\",\n \"returned_at\": \"2025-02-13T18:09:00+00:00\",\n \"sec_code\": \"PPD\",\n \"transaction_amount\": 225.84,\n \"transaction_amount_range\": 0,\n \"user_guid\": \"USR-fa7537f3-48aa-a683-a02a-b18940482f54\"\n }\n}"
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": "CHECKING",
"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": "2025-02-13T18:08:00+00:00",
"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"
}
}Create ACH Return
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.
curl --request POST \
--url https://int-api.mx.com/ach_returns \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"ach_return": {
"account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"account_number_last_four": "1234",
"ach_initiated_at": "2025-02-13T18:08:00+00:00",
"id": "client_ach_id_1234",
"member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
"return_code": "R01",
"returned_at": "2025-02-13T18:09:00+00:00",
"sec_code": "PPD",
"transaction_amount": 225.84,
"transaction_amount_range": 0,
"user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
}
}
'import requests
url = "https://int-api.mx.com/ach_returns"
payload = { "ach_return": {
"account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"account_number_last_four": "1234",
"ach_initiated_at": "2025-02-13T18:08:00+00:00",
"id": "client_ach_id_1234",
"member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
"return_code": "R01",
"returned_at": "2025-02-13T18:09:00+00:00",
"sec_code": "PPD",
"transaction_amount": 225.84,
"transaction_amount_range": 0,
"user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
} }
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({
ach_return: {
account_guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
account_number_last_four: '1234',
ach_initiated_at: '2025-02-13T18:08:00+00:00',
id: 'client_ach_id_1234',
member_guid: 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
return_code: 'R01',
returned_at: '2025-02-13T18:09:00+00:00',
sec_code: 'PPD',
transaction_amount: 225.84,
transaction_amount_range: 0,
user_guid: 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
}
})
};
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([
'ach_return' => [
'account_guid' => 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
'account_number_last_four' => '1234',
'ach_initiated_at' => '2025-02-13T18:08:00+00:00',
'id' => 'client_ach_id_1234',
'member_guid' => 'MBR-7c6f361b-e582-15b6-60c0-358f12466b4b',
'return_code' => 'R01',
'returned_at' => '2025-02-13T18:09:00+00:00',
'sec_code' => 'PPD',
'transaction_amount' => 225.84,
'transaction_amount_range' => 0,
'user_guid' => 'USR-fa7537f3-48aa-a683-a02a-b18940482f54'
]
]),
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("{\n \"ach_return\": {\n \"account_guid\": \"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1\",\n \"account_number_last_four\": \"1234\",\n \"ach_initiated_at\": \"2025-02-13T18:08:00+00:00\",\n \"id\": \"client_ach_id_1234\",\n \"member_guid\": \"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b\",\n \"return_code\": \"R01\",\n \"returned_at\": \"2025-02-13T18:09:00+00:00\",\n \"sec_code\": \"PPD\",\n \"transaction_amount\": 225.84,\n \"transaction_amount_range\": 0,\n \"user_guid\": \"USR-fa7537f3-48aa-a683-a02a-b18940482f54\"\n }\n}")
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("{\n \"ach_return\": {\n \"account_guid\": \"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1\",\n \"account_number_last_four\": \"1234\",\n \"ach_initiated_at\": \"2025-02-13T18:08:00+00:00\",\n \"id\": \"client_ach_id_1234\",\n \"member_guid\": \"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b\",\n \"return_code\": \"R01\",\n \"returned_at\": \"2025-02-13T18:09:00+00:00\",\n \"sec_code\": \"PPD\",\n \"transaction_amount\": 225.84,\n \"transaction_amount_range\": 0,\n \"user_guid\": \"USR-fa7537f3-48aa-a683-a02a-b18940482f54\"\n }\n}")
.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 = "{\n \"ach_return\": {\n \"account_guid\": \"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1\",\n \"account_number_last_four\": \"1234\",\n \"ach_initiated_at\": \"2025-02-13T18:08:00+00:00\",\n \"id\": \"client_ach_id_1234\",\n \"member_guid\": \"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b\",\n \"return_code\": \"R01\",\n \"returned_at\": \"2025-02-13T18:09:00+00:00\",\n \"sec_code\": \"PPD\",\n \"transaction_amount\": 225.84,\n \"transaction_amount_range\": 0,\n \"user_guid\": \"USR-fa7537f3-48aa-a683-a02a-b18940482f54\"\n }\n}"
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": "CHECKING",
"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": "2025-02-13T18:08:00+00:00",
"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"
}
}Authorizations
To authenticate with the Platform API, include your Base64-encoded client_id and api_key in the Authorization header of every request:
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'
Body
ACH return object to be created.
Hide child attributes
Hide child attributes
The unique identifier for the account associated with the transaction. Defined by MX.
"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1"
Client-defined identifier for this specific return submission. Allows you to track and reference you requests.
"client_ach_id_1234"
The unique identifier for the member associated with the transaction. Defined by MX.
"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b"
A short, machine-readable code that categorizes the type of resolution or reason for the status. See Resolution Codes for a complete list.
"R01"
MX-defined identifier for the user associated with the ACH return.
"USR-fa7537f3-48aa-a683-a02a-b18940482f54"
The last 4 digits of the account number used for the transaction by the Originating Depository Financial Institution (ODFI).
"1234"
The date and time when the transaction was initiated by the Originating Depository Financial Institution (ODFI) in ISO 8601 format without timestamp.
"2025-02-13T18:08:00+00:00"
The account number correction reported by the RDFI. Populate only if the resolution_code is NOTICE_OF_CHANGE.
null
The routing number correction reported by the RDFI. Populated only if the resolution_code is NOTICE_OF_CHANGE. Must be a valid 9-digit routing number format.
null
Incorrect account number used in the ACH transaction.
null
Notes that you set to inform MX on internal ACH processing.
null
Incorrect routing number used in the ACH transaction.
null
The date and time when the return was reported by the Receiving Financial Depository Institution (RDFI) in ISO 8601 format without timestamp.
"2025-02-13T18:09:00+00:00"
The amount of the transaction.
225.84
The transaction amount range, used for impact assessment.
0
Response
OK
Hide child attributes
Hide child attributes
The unique identifier for an account. Defined by MX.
"ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1"
The last 4 digits of the account number used for the transaction by the Originating Depository Financial Institution (ODFI).
"1234"
The type of account. Some account types may include subtypes.
ANY, CASH, CHECKING, CHECKING_LINE_OF_CREDIT, CREDIT_CARD, LOAN, LINE_OF_CREDIT, SAVINGS, INVESTMENT, MORTGAGE, INSURANCE, PREPAID, PROPERTY "CHECKING"
The date and time when the transaction was initiated by the Originating Depository Financial Institution (ODFI) in ISO 8601 format without timestamp.
"2025-02-13T18:08:00+00:00"
The unique identifier for the client associated with the insight. Defined by MX.
"CLT-abcd-1234"
The account number correction reported by the RDFI. Populate only if the resolution_code is NOTICE_OF_CHANGE.
null
The routing number correction reported by the RDFI. Populated only if the resolution_code is NOTICE_OF_CHANGE. Must be a valid 9-digit routing number format.
null
The date and time the ACH return was created, represented in ISO 8601 format with a timestamp.
"2025-02-13T18:08:00+00:00"
The unique identifier for the ACH return record. Defined by MX.
"ACH-d74cb14f-fd0a-449f-991b-e0362a63d9c6"
Client-defined identifier for this specific return submission. Allows you to track and reference your requests.
"client_ach_return_id_1234"
The unique identifier for an institution. Defined by MX.
"INS-34r4f44b-cfge-0f6e-3484-21f47e45tfv7"
Notes added by Product Support during investigation of the ACH return.
null
The unique identifier for the member. Defined by MX.
"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b"
Any errors that occurred during processing.
null
A short, machine-readable code that categorizes the type of resolution or reason for the status. See Resolution Codes for a complete list.
null
A more detailed, human-readable message providing context and next steps related to the return_status and resolution_code.
null
Date and time when the return was marked as resolved.
null
The associated ACH return codes and notice of change codes (for example, R02, R03, R04, R05, R20, NOC). See Return Codes for a complete list
"R01"
Notes that you set to inform MX on internal ACH processing.
null
Incorrect account number used in the ACH transaction.
null
Incorrect routing number used in the ACH transaction.
null
The current processing status of the ACH return. See Return Status for a complete list of statuses.
"SUBMITTED"
The date and time when the return was reported by the Receiving Financial Depository Institution (RDFI) in ISO 8601 format without timestamp.
"2025-02-13T18:09:00+00:00"
Date and time when MX started processing the return.
null
Date and time when the record was submitted through the API.
null
The amount of the transaction.
225.84
Date and time when the ACH return record was last updated.
null
The unique identifier for the user. Defined by MX.
"USR-fa7537f3-48aa-a683-a02a-b18940482f54"