Added Payment Returns API

Release Date

November 6, 2025

Products Affected

Lithic ACH Payments

Impact

ACH Returns endpoint added

Audience

All customers using ACH Receipts

Action Required

None

Overview

Lithic now offers an endpoint to be able to return ACH payments. https://docs.lithic.com/reference/getpaymentbytoken

This endpoint is capable of returning both ACH Credits (pushes) and ACH Debits (pulls). It requires specific permissions configured by Lithic Implementations, and a NACHA-approved return code to be able to be used.

Details

Users should specify the payment_token in the path params to indicate the payment they want to return
- Returning a RECEIPT_CREDIT pushes money back to the ODFI
- Return a RECEIPT_DEBIT pulls money back from the ODFI
Users must specify an approved return_reason_code in the body of the response.
- Each return_reason_code must be explicitly approved by Lithic implementation and configured
- Each return_reason_code must follow NACHA guidelines and timelines. See more information in our Return Reason Codes page

Example

If a user wants to return the following payment, retrieved via https://docs.lithic.com/reference/getpaymentbytoken

{
    "category": "ACH",
    "status": "SETTLED",
    "result": "APPROVED",
    "method_attributes": {
        "sec_code": "WEB",
        "return_reason_code": null,
        "retries": 0,
        "company_id": 5330903621,
        "receipt_routing_number": null
    },
    "financial_account_token": "6127238d-cb85-50bc-86aa-264654a11be9",
    "external_bank_account_token": null,
    "direction": "CREDIT",
    "source": "LITHIC",
    "method": "ACH_SAME_DAY",
    "token": "6d5a2718-9b79-4473-aa1e-6bbf7433ea6f",
    "type": "RECEIPT_DEBIT",
    "settled_amount": 10000,
    "pending_amount": 0,
    "currency": "USD",
    "events": [
        {
            "amount": 10000,
            "type": "ACH_RECEIPT_PROCESSED",
            "result": "APPROVED",
            "detailed_results": ["APPROVED"],
            "created": "2024-04-18T18:16:09Z",
            "token": "34c5b9d2-2d6a-540b-90fe-fa202b418242"
        },
        {
            "amount": 10000,
            "type": "ACH_RECEIPT_SETTLED",
            "result": "APPROVED",
            "detailed_results": ["APPROVED"],
            "created": "2024-04-18T18:17:40Z",
            "token": "5f6255f8-4016-5e66-aedf-2e3c76027e04"
        }
        
    ],
    "descriptor": "Test Technologies",
    "user_defined_id": "1234",
    "created": "2024-04-18T18:16:09Z",
    "updated": "2024-04-19T16:38:22Z"
}

They should call the payment return endpoint with the token seen above in the path. The below example request body is for an R10 - Customer Advises Originator is Not Known.

{
  "financial_account_token": "6127238d-cb85-50bc-86aa-264654a11be9",
  "return_reason_code": "R01",
}

For a successful payment return, they will see the payment in the body of the response, along with the new ACH_RETURN_INITIATED event:

{
    "category": "ACH",
    "status": "SETTLED",
    "result": "APPROVED",
    "method_attributes": {
        "sec_code": "WEB",
        "return_reason_code": R10,
        "retries": 0,
        "company_id": 5330903621,
        "receipt_routing_number": null
    },
    "financial_account_token": "6127238d-cb85-50bc-86aa-264654a11be9",
    "external_bank_account_token": null,
    "direction": "CREDIT",
    "source": "LITHIC",
    "method": "ACH_SAME_DAY",
    "token": "6d5a2718-9b79-4473-aa1e-6bbf7433ea6f",
    "type": "RECEIPT_DEBIT",
    "settled_amount": 10000,
    "pending_amount": 0,
    "currency": "USD",
    "events": [
        {
            "amount": 10000,
            "type": "ACH_RECEIPT_PROCESSED",
            "result": "APPROVED",
            "detailed_results": ["APPROVED"],
            "created": "2024-04-18T18:16:09Z",
            "token": "34c5b9d2-2d6a-540b-90fe-fa202b418242"
        },
        {
            "amount": 10000,
            "type": "ACH_RECEIPT_SETTLED",
            "result": "APPROVED",
            "detailed_results": ["APPROVED"],
            "created": "2024-04-18T18:17:40Z",
            "token": "5f6255f8-4016-5e66-aedf-2e3c76027e04"
        },
        {
            "amount": 10000,
            "type": "ACH_RETURN_INITIATED",
            "result": "APPROVED",
            "detailed_results": ["APPROVED"],
            "created": "2024-04-18T18:17:40Z",
            "token": "5f6255f8-4016-5e66-aedf-2e3c76027e04"
        }
    ],
    "descriptor": "Test Technologies",
    "user_defined_id": "1234",
    "created": "2024-04-18T18:16:09Z",
    "updated": "2024-04-19T16:38:22Z"
}

Release Timeline

Available now: November 6, 2025

User Impact

No impact, this change is additive only. Click here to learn more about ACH at Lithic

If you have any questions or concerns, please contact us via the HELP link in your Lithic Dashboard.

The Lithic changelog has an RSS feed! To monitor for new update announcements, subscribe with your preferred RSS reader.