Sign in

v66

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-08-042174421.1 MB
Payment

Return payment

Return an ACH payment with a specified return reason code. Returns must be initiated within the time window specified by NACHA rules for each return code (typically 2 banking days for most codes, 60 calendar days for unauthorized debits). For a complete list of return codes and their meanings, see the ACH Return Reasons documentation.

Note:

  • This endpoint does not modify the state of the financial account associated with the payment. If you would like to change the account state, use the Update financial account status endpoint.
  • By default this endpoint is not enabled for your account. Please contact your implementations manager to enable this feature.
post/v1/payments/{payment_token}/return

Path parameters

payment_tokenstring uuid required

Request body

financial_account_tokenstring uuid required

Globally unique identifier for the financial account

return_reason_codestring required

ACH return reason code indicating the reason for returning the payment. Supported codes include R01-R53 and R80-R85. For a complete list of return codes and their meanings, see ACH Return Reasons

memostring nullable

Optional memo for the return. Limited to 10 characters

addendastring nullable

Optional additional information about the return. Limited to 44 characters

date_of_deathstring date nullable

Date of death in YYYY-MM-DD format. Required when using return codes R14 (representative payee deceased) or R15 (beneficiary or account holder deceased)

Example request

{
  "return_reason_code": "R01",
  "date_of_death": "2025-01-15"
}

Response

Accepted

status'PENDING' | 'SETTLED' | 'DECLINED' | 'REVERSED' | 'CANCELED' | 'RETURNED' required
tokenstring uuid required

Unique identifier for the transaction

createdstring date-time required

ISO 8601 timestamp of when the transaction was created

updatedstring date-time required

ISO 8601 timestamp of when the transaction was last updated

family'PAYMENT' required

PAYMENT - Payment Transaction

category'ACH' | 'WIRE' | 'STABLECOIN' | 'BALANCE_OR_FUNDING' | 'FEE' | 'REWARD' | 'ADJUSTMENT' | 'DERECOGNITION' | 'DISPUTE' | 'CARD' | 'EXTERNAL_ACH' | 'EXTERNAL_CHECK' | 'EXTERNAL_FEDNOW' | 'EXTERNAL_RTP' | 'EXTERNAL_TRANSFER' | 'EXTERNAL_WIRE' | 'MANAGEMENT_ADJUSTMENT' | 'MANAGEMENT_DISPUTE' | 'MANAGEMENT_FEE' | 'MANAGEMENT_REWARD' | 'MANAGEMENT_DISBURSEMENT' | 'HOLD' | 'PROGRAM_FUNDING' | 'PROGRAM_TRANSFER' required

Note: Inbound wire transfers are coming soon (availability varies by partner bank). The WIRE category is a preview. To learn more, contact your customer success manager.

currencystring

Currency of the transaction in ISO 4217 format

result'APPROVED' | 'DECLINED' required
financial_account_tokenstring uuid required

Financial account token

external_bank_account_tokenstring uuid nullable

External bank account token

direction'CREDIT' | 'DEBIT' required

Transfer direction

source'LITHIC' | 'EXTERNAL' | 'CUSTOMER' required

Transaction source

method'ACH_NEXT_DAY' | 'ACH_SAME_DAY' | 'WIRE' required

Transfer method

settled_amountinteger required

Settled amount in cents

pending_amountinteger required

Pending amount in cents

descriptorstring required

Transaction descriptor

user_defined_idstring nullable

User-defined identifier

expected_release_datestring date nullable

Expected release date for the transaction

type'ORIGINATION_CREDIT' | 'ORIGINATION_DEBIT' | 'RECEIPT_CREDIT' | 'RECEIPT_DEBIT' | 'WIRE_INBOUND_PAYMENT' | 'WIRE_INBOUND_ADMIN' | 'WIRE_OUTBOUND_PAYMENT' | 'WIRE_OUTBOUND_ADMIN' | 'WIRE_INBOUND_DRAWDOWN_REQUEST'
tagsTags

Key-value pairs for tagging resources. Tags allow you to associate arbitrary metadata with a resource for your own purposes.

Example response

{
  "family": "PAYMENT",
  "status": "PENDING",
  "token": "bd4efddb-771b-49e3-9af9-49b077ab5eb8",
  "created": "2025-10-27T20:12:22Z",
  "updated": "2025-10-27T20:12:25Z",
  "category": "ACH",
  "result": "APPROVED",
  "method_attributes": {
    "sec_code": "CCD",
    "return_reason_code": null,
    "ach_hold_period": 1,
    "retries": 0,
    "company_id": "1111111111",
    "receipt_routing_number": null,
    "recipient_name": null,
    "trace_numbers": [],
    "addenda": null
  },
  "financial_account_token": "35b0c466-a3e3-519a-9549-ead6a6a2277d",
  "external_bank_account_token": "feb4fee1-2414-4c38-a5f6-9deac293c8f4",
  "direction": "CREDIT",
  "source": "LITHIC",
  "method": "ACH_NEXT_DAY",
  "settled_amount": 0,
  "pending_amount": -1588,
  "currency": "USD",
  "events": [
    {
      "amount": -1588,
      "type": "ACH_ORIGINATION_INITIATED",
      "result": "APPROVED",
      "created": "2025-10-27T20:12:22Z",
      "token": "327dccc3-fe42-54d2-962c-7f8135805464",
      "detailed_results": [
        "APPROVED"
      ]
    },
    {
      "amount": -1588,
      "type": "ACH_ORIGINATION_REVIEWED",
      "result": "APPROVED",
      "created": "2025-10-27T20:12:25Z",
      "token": "f9165477-7cfc-53c6-98f1-84e9ec856a60",
      "detailed_results": [
        "APPROVED"
      ]
    }
  ],
  "descriptor": "ach_origination_credit",
  "user_defined_id": null,
  "expected_release_date": null,
  "related_account_tokens": null,
  "type": "ORIGINATION_CREDIT"
}