ACH Returns

ACH returns can be used to return a transaction that has been processed incorrectly. This can occur for a variety of reasons, but the most common relate to administrative errors like an incorrect account number or insufficient funds. If you are using ACH processing, the RDFI (receiving bank) can return the transaction to the sender (you) and it is the sender's responsibility to correct the error and submit a new transaction. Your institution will automatically reverse the transaction that was returned and correct your balance accordingly.

If you are managing a Virtual Account program, you will need to act as the receiver and programmatically create ACH Returns for transactions that you do not wish to honor.

See the ACH Return Codes documentationfor a full list of possible return codes.

Data Types

AchReturnResponse

Key	Value	Notes
type	ach-returns
id	UUID
Attributes
code	String	Standard ACH Return Code (RO1,R02, etc ...)
reason	String	A human readable description of the return reason
status	String	pending, processing, processed, or processing_failed
metadata	Metadata
created-at	Timestamp
updated-at	Timestamp
Relationships
ach-batch-entry	AchBatchEntryRelationship
transaction	TransactionRelationship or RefundRelationship

AchReturnResponse

{
  "data": {
    "type": "ach-returns",
    "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0",
    "attributes": {
      "code": "RO1",
      "reason": "INSUFFICIENT FUNDS",
      "status": "processed",
      "metadata": {},
      "created-at": "2022-06-21T23:34:04Z",
      "updated-at": "2022-06-21T23:34:04Z"
    },
    "relationships": {
      "ach-batch-entry": {
        "data": {
          "type": "ach-batch-entries",
          "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
        }
      },
      "transaction": {
        "data": {
          "type": "transactions",
          "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
        }
      }
    }
  }
}

AchReturnRequest

Key	Value		Notes
type	ach-returns	Required
Attributes
code	String	Required	Standard ACH Return Code (RO1,R02, etc ...)
metadata	Metadata
Relationships
ach-batch-entry	AchBatchEntryRelationship
transaction	TransactionRelationship

Either ach-batch-entry or transaction must be provided.

AchReturnRequest

{
  "data": {
    "type": "ach-returns",
    "attributes": {
      "code": "RO1",
      "metadata": {}
    },
    "relationships": {
      "ach-batch-entry": {
        "data": {
          "type": "ach-batch-entries",
          "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
        }
      }
    }
  }
}

GET/v1/ach-returns

List ACH returns

This endpoint retrieves all ACH returns. By default, a maximum of thirty ACH returns are shown per page.

This endpoint returns an array of AchReturnResponse objects.

Filters

Name
created_between
Type
object
Description
See documentation for filtering by timestamps.
Name
updated_between
Type
object
Description
See documentation for filtering by timestamps.
Name
metadata
Type
object
Description
See documentation for filtering by metadata.
Name
page
Type
object
Description
See documentation for pagination.

Request

GET

/v1/ach-returns

curl --request GET \
--url 'https://api.opentransact.com/v1/ach-returns' \
--header 'Authorization: Basic {API_KEY}'

Response

{
  "data": [
    {
      "type": "ach-returns",
      "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0",
      "attributes": {
        "code": "RO1",
        "reason": "INSUFFICIENT FUNDS",
        "metadata": {},
        "status": "processed",
        "created-at": "2022-06-21T23:34:04Z",
        "updated-at": "2022-06-21T23:34:04Z"
      },
      "relationships": {
        "ach-batch-entry": {
          "data": {
            "type": "ach-batch-entries",
            "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
          }
        },
        "transaction": {
          "data": {
            "type": "transactions",
            "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
          }
        }
      }
    },
    ...
  ],
  "meta": {
    "page-count": 2,
    "count": 38,
    "current-page": 1
  },
  "links": {
    "self": "https://api.opentransact.com/v1/ach-returns?page=1&limit=30",
    "next": "https://api.opentransact.com/v1/ach-returns?page=2&limit=30",
    "first": "https://api.opentransact.com/v1/ach-returns?page=1&limit=30",
    "last": "https://api.opentransact.com/v1/ach-returns?page=2&limit=30"
  }
}

POST/v1/ach-returns

Create an ACH return

This endpoint creates a new ACH return.

This endpoint accepts an AchReturnRequest object and returns an AchReturnResponse object.

Request

POST

/v1/ach-returns

curl --request POST \
--url https://api.opentransact.com/v1/ach-returns \
--header 'Authorization: Basic {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
        "data": {
          "type": "ach-returns",
            "attributes": {
              "code": "R01",
              "metadata": {
                "program": "virtual-account"
              }
            },
            "relationships": {
              "transaction": {
                "data": {
                  "type": "transactions",
                  "id": "{TRANSACTION_ID}"
                }
              }
            }
        }
}'

Response

{
  "data": {
    "type": "ach-returns",
    "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0",
    "attributes": {
      "code": "RO1",
      "reason": "INSUFFICIENT FUNDS",
      "metadata": {},
      "status": "pending",
      "created-at": "2022-06-21T23:34:04Z",
      "updated-at": "2022-06-21T23:34:04Z"
    },
    "relationships": {
      "ach-batch-entry": {
        "data": {
          "type": "ach-batch-entries",
          "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
        }
      },
      "transaction": {
        "data": {
          "type": "transactions",
          "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
        }
      }
    }
  }
}