Returns

openapi: 3.0.3 info: title: Automated Clearing House (ACH) API - Returns version: v1 description: | Automated Clearing House (JHPlatform ACH). contact: name: Platform Services - ACH url: https://www.jackhenry.com/ email: DC-Operations@jackhenry.com servers: - url: https://banno.com description: Production Endpoint security: [] components: securitySchemes: bearerAuth: description: OpenIDConnect JWT Token type: http scheme: bearer bearerFormat: JWT tags: - name: Returns description: APIs for returning posted ACH entries paths: /a/api/jh-ach/v1/{InstitutionUniversalId}/posted-entry-return/entry/{entryId}: post: operationId: CreatePostedEntryReturn tags: - Returns summary: Create posted entry return description: | Initiate a return against a posted incoming forward entry. The system verifies the original entry is in `posted` status, posts the receiver account reversal, and then creates the outgoing return entry. ## Authorization Requires **CreateACHReturn** permission set to Allow. ## Business rules - Only posted incoming entries are eligible. Entries in other states are rejected. - Return reason codes are limited to the V1 posted-entry allowlist (see request schema). - `dateOfDeath` is required for return reason codes R14 and R15 (YYMMDD). - The receiver account must not be closed or pending closed; otherwise the request fails before a return entry is created and the original entry remains `posted`. - On success, use Get Entry with the returned `returnEntryId` to retrieve return details. ## Representative errors - **400 Bad Request** — validation failures, disallowed return reason code, or missing/invalid `dateOfDeath`. - **400 Entry Not Posted** — original entry is not in `posted` status (detail includes current entry status). - **400 Posted Entry Return Cannot Be Prepared** — entry context cannot be mapped to a return or reversal request. - **400 Account closed** — receiver account status does not allow transactions. - **404 Entry Not Found** — no entry exists for the path `entryId`. parameters: - name: InstitutionUniversalId in: path description: A unique identifier to establish the identity of an Institution/Environment/Brand combination required: true schema: type: string - name: entryId in: path description: Unique identifier of the original posted forward entry to return required: true schema: type: string format: uuid - name: X-Request-ID description: "The `X-Request-Id` is used to track and identify individual requests as they traverse various systems to enable tracing and troubleshooting. If one is not provided in the request, the API generates this ID. A new ID is generated for each service call when a request requires calls to other services. Developers and system administrators use this ID to correlate logs and monitor the flow of requests through multiple systems. \n" in: header required: false schema: type: string format: uuid example: 368b8d8f-5d07-4612-9523-d92fd57b0341 - name: X-Correlation-ID description: | The `X-Correlation-ID` header is an optional header that can be included in REST API to track and correlate related requests and responses within a distributed system. This header allows clients to assign a unique identifier to a request, which servers or middleware components can then use to track and link subsequent requests and responses that are part of the same logical operation or transaction. in: header required: false schema: type: string format: uuid example: 8e87d005-f99f-40ab-a4e0-811f9263f1e7 - name: X-WorkflowCorrelationId description: | The `X-WorkflowCorrelationId` header correlates different requests or events as part of a workflow or process. It is used to track and manage the flow of requests throughout multiple systems. When a workflow client sends multiple related requests, they can include the `X-WorkflowCorrelationId` header with the same value to indicate that these requests are part of the same workflow to support the grouping and associating the requests together, thus enabling reporting systems to identify them as a single logical unit. Additionally, this header element can assist in monitoring and troubleshooting the workflow by allowing administrators or developers to trace and analyze the flow of requests using this common identifier. in: header required: false schema: type: string format: uuid example: 062e61c8-1d5f-41c6-9ddb-e00f35004e60 requestBody: description: Posted entry return request required: true content: application/json: schema: type: object description: | Request body for creating a return against a posted incoming entry. dateOfDeath is required when returnReasonCode is R14 or R15. addendaInformation is commonly used for R17 (e.g. QUESTIONABLE). required: - returnReasonCode - returnReasonDescription properties: returnReasonCode: type: string description: | V1 permitted RDFI return reason codes for posted-entry returns. enum: - R01 - R02 - R03 - R14 - R15 - R16 - R17 - R20 example: R01 returnReasonDescription: type: string maxLength: 1000 description: User-provided description of the return reason. example: Insufficient funds dateOfDeath: type: string minLength: 6 maxLength: 6 pattern: ^\d{6}$ description: | Date of death in NACHA YYMMDD format. Required for return reason codes R14 and R15. Must not be supplied for other return reason codes. example: '240115' addendaInformation: type: string maxLength: 44 description: Optional Addenda Type 99 information (e.g. QUESTIONABLE for R17). example: QUESTIONABLE additionalProperties: false examples: standardReturn: summary: Standard return (R01) value: returnReasonCode: R01 returnReasonDescription: Insufficient funds deceasedReturn: summary: Deceased return (R14) value: returnReasonCode: R14 returnReasonDescription: Account holder deceased dateOfDeath: '240115' questionableReturn: summary: Questionable return (R17) value: returnReasonCode: R17 returnReasonDescription: Questionable entry addendaInformation: QUESTIONABLE responses: '200': description: Success — return initiated; original entry is `return_pending` headers: X-Request-ID: description: "The `X-Request-Id` is used to track and identify individual requests as they traverse various systems to enable tracing and troubleshooting. If one is not provided in the request, the API generates this ID. A new ID is generated for each service call when a request requires calls to other services. Developers and system administrators use this ID to correlate logs and monitor the flow of requests through multiple systems. \n" required: false schema: type: string format: uuid example: 368b8d8f-5d07-4612-9523-d92fd57b0341 X-Correlation-ID: description: | The `X-Correlation-ID` header is used to correlate related requests and responses within a distributed system. This header allows clients to assign a unique identifier to a request, which servers or middleware components can then use to track and link subsequent requests and responses that are part of the same logical operation or transaction. required: false schema: type: string format: uuid example: 8e87d005-f99f-40ab-a4e0-811f9263f1e7 X-WorkflowCorrelationId: description: | The `X-WorkflowCorrelationId` header correlates different requests or events as part of a workflow or process. It is used to track and manage the flow of requests throughout multiple systems. When a workflow client sends multiple related requests, they can include the `X-WorkflowCorrelationId` header with the same value to indicate that these requests are part of the same workflow to support the grouping and associating the requests together, thus enabling reporting systems to identify them as a single logical unit. Additionally, this header element can assist in monitoring and troubleshooting the workflow by allowing administrators or developers to trace and analyze the flow of requests using this common identifier. required: false schema: type: string format: uuid example: 062e61c8-1d5f-41c6-9ddb-e00f35004e60 content: application/json: schema: type: object description: Response after a posted entry return is successfully initiated. required: - returnEntryId properties: returnEntryId: type: string format: uuid description: Unique identifier of the newly created outgoing return entry. example: 550e8400-e29b-41d4-a716-446655440000 additionalProperties: false examples: success: summary: Return entry created value: returnEntryId: 550e8400-e29b-41d4-a716-446655440000 '400': description: The server could not understand the request due to an invalid request. content: application/problem+json: schema: type: object required: - type - title - details properties: type: description: A string path which uniquely classifies the domain of the error. type: string nullable: false example: jackhenry/operation-failed title: description: A end-user readable string title of the error type. nullable: false type: string details: description: An array of end-user readable strings which provide additional details for the error message. type: array nullable: false items: type: string data: type: object description: | Additional data that could be useful to a developer or for handing the error programmatically. The schema for the data in this object is intentionally left undefined. nullable: true '401': description: Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. '403': description: The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the clients identity is known to the server. '404': description: The server can not find the requested resource. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 to hide the existence of a resource from an unauthorized client. '500': description: An unexpected internal server error occurred while processing the request. content: application/problem+json: schema: type: object required: - type - title - details properties: type: description: A string path which uniquely classifies the domain of the error. type: string nullable: false example: jackhenry/operation-failed title: description: A end-user readable string title of the error type. nullable: false type: string details: description: An array of end-user readable strings which provide additional details for the error message. type: array nullable: false items: type: string data: type: object description: | Additional data that could be useful to a developer or for handing the error programmatically. The schema for the data in this object is intentionally left undefined. nullable: true examples: internalServerError: summary: Internal server error value: type: general/internal-server-error title: Internal server error details: - Unexpected internal server error

Please ignore this field