ACH Return Overview - MX Documentation

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

Using our Platform API, you can securely submit ACH Returns to reduce your ACH return rates and automate your ACH return process. You can query the status and outcomes of your submitted ACH returns to track progress and access resolution details.

ACH Return Fields

Field	Data Type	Description
`account_guid`	String	The unique identifier for the account associated with the transaction. Defined by MX.
`account_number_last_four`	String	The last 4 digits of the account number used for the transaction by the Originating Depository Financial Institution (ODFI).
`account_type`	String	The type of account used for the transaction by the Originating Depository Financial Institution (ODFI) (for example, `CHECKING`, `SAVINGS`).
`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.
`client_guid`	String	The unique identifier for the client associated with the ACH return. Defined by MX.
`corrected_account_number`	String	The account number correction reported by the RDFI. Populate only if the `resolution_code` is `NOTICE_OF_CHANGE`.
`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.
`created_at`	String	Date and time when the ACH return record was created.
`external_customer_guid`	String	Your unique identifier as defined by a partner.
`guid`	String	The unique identifier for the ACH return record.
`id`	String	Client-defined identifier for this specific return submission. Allows you to track and reference your requests.
`institution_guid`	String	The MX-defined identifier for the institution associated with the ACH return.
`investigation_notes`	String	Notes added by Product Support during investigation.
`member_guid`	String	The unique identifier for the member associated with the transaction. Defined by MX.
`processing_errors`	String	Error messages encountered during processing.
`resolution_code`	String	A short, machine-readable code that categorizes the type of resolution or reason for the status. See Resolution Codes for a complete list.
`resolution_detail`	String	A more detailed, human-readable message providing context and next steps related to the `return_status` and `resolution_code`.
`resolved_status_at`	String	Date and time when the return was marked as resolved.
`return_account_number`	String	Incorrect account number used in the ACH transaction.
`return_code`	String	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.
`return_notes`	String	Notes that you set to inform MX on internal ACH processing.
`return_routing_number`	String	Incorrect routing number used in the ACH transaction.
`return_status`	String	The current processing status of the ACH return. See Return Status for a complete list of statuses.
`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.
`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.
`started_processing_at`	String	Date and time when MX started processing the return.
`submitted_at`	String	Date and time when the record was submitted through the API.
`transaction_amount`	Number	The amount of the transaction.
`transaction_amount_range`	Number	The transaction amount range, used for impact assessment.
`updated_at`	String	Date and time when the ACH return record was last updated.
`user_guid`	String	MX-defined identifier for the user associated with the event.

SEC Codes

Code	Data Type	Title
`SEC_CODE_UNSPECIFIED`	String	Used if no other SEC code is set.
`PPD`	String	Prearranged Payment and Deposit
`PPD_PLUS`	String	Prearranged Payment and Deposit, with addenda record
`CCD`	String	Corporate Credit or Debit
`CCD_PLUS`	String	Corporate Credit or Debit, with addenda record
`CTX`	String	Corporate Trade Exchange
`WEB`	String	Internet Initiated/Mobile Entry
`TEL`	String	Telephone-Initiated Entry
`ARC`	String	Accounts Receivable Entry
`BOC`	String	Back Office Conversion Entry
`POP`	String	Point-of-Purchase Entry
`IAT`	String	International ACH Transaction
`COR`	String	Notification of Change
`CIE`	String	Customer Initiated Entries
`RCK`	String	Re-presented Check Entries
`POS`	String	Point of Sale

Resolution Codes

Code	Data Type	Description
`DATA_UPDATED`	String	The resolution involved updating account data.
`JOB_REQUIRED`	String	A new Instant Account Verification aggregation is required for resolution.
`ACCOUNT_LIMITATION`	String	The return is due to an account-level limitation (for example, account type, transaction limits).
`NOTICE_OF_CHANGE`	String	The return is a Notice of Change (NOC) - informational, but contains corrected data.
`UNRESOLVABLE_RETURN`	String	The return could not be resolved by MX.
`CLIENT_ACTION_REQUIRED`	String	Client action is needed.
`INVALID_SUBMISSION`	String	The API submission was invalid.

Return Codes

Code	Data Type	Title
`RETURN_CODE_UNSPECIFIED`	String	Use to create an ACH return if you don’t have a return code for an ACH return.
`R01`	String	Insufficient Funds
`R02`	String	Account Closed
`R03`	String	No Account / Unable to Locate Account
`R04`	String	Invalid Account Number Structure
`R05`	String	Unauthorized Consumer Debit using Corporate SEC Code
`R06`	String	ODFI Requested Return
`R07`	String	Customer Revoked Authorization
`R08`	String	Payment Stopped
`R09`	String	Uncollected Funds
`R10`	String	Originator not known and/or not authorized to Debit Receiver’s Account
`R11`	String	Customer advises not within Authorization Terms
`R12`	String	Account Sold to Another DFI
`R13`	String	Invalid ACH Routing No.
`R14`	String	Representative Payee Deceased
`R15`	String	Beneficiary / Account Holder Deceased
`R16`	String	Account Frozen / Returned per OFAC
`R17`	String	File Record Edit Criteria / Suspicious Entry with Invalid Account No. / Return of Improperly-Initiated Reversal
`R18`	String	Improper Effective Date
`R19`	String	Amount Field Error
`R20`	String	Non-Transaction Account

Return Status

Status	Data Type	Description
`RETURN_STATUS_UNSPECIFIED`	String	Used if no other return status is set.
`SUBMITTED`	String	The initial status after you successfully submit ACH return data using the API.
`PENDING`	String	The submitted return is queued and awaiting automated processing.
`PROCESSING`	String	The return is currently being actively processed, either by the automated system or by manual review.
`RESOLVED_DATA_UPDATED`	String	The automated system successfully resolved the return by updating account data in the MX system.
`RESOLVED_JOB_REQUIRED`	String	The automated system determined that a new Instant Account Verification (IAV) aggregation is required to resolve the return.
`RESOLVED_INFORMATIONAL`	String	After automated or manual investigation, it’s determined that the return reason is due to client-side issues or informational (like account restrictions) and no MX data fix is needed.
`RESOLVED_UNRESOLVABLE`	String	After thorough automated and/or manual investigation, no resolution is found within MX systems or via data providers.
`PENDING_CLIENT_ACTION`	String	MX requires action from you to proceed with the return investigation or resolution. This could occur if there was missing data in the submission.
`REJECTED`	String	The initial API submission was rejected due to errors in the data you provided.

​ACH Return Fields

​SEC Codes

​Resolution Codes

​Return Codes

​Return Status

ACH Return Fields

SEC Codes

Resolution Codes

Return Codes

Return Status