> ## Documentation Index > Fetch the complete documentation index at: https://docs.lead.bank/llms.txt > Use this file to discover all available pages before exploring further. # Return an ACH > Issue a return against an incoming ACH. ## OpenAPI ````yaml POST /v1/ach/{ach_id}/return openapi: 3.0.1 info: title: Lead Bank description: Lead Bank's APIs version: v1.0 servers: - url: https://api.sandbox.lead.bank - url: https://api.lead.bank security: - bearerAuth: [] tags: - name: ACH - name: Account Number - name: OAuth - name: Events - name: Instant Payments - name: Lending - name: Simulation - name: Internal Transfer - name: Disbursement - name: Entity - name: Wire - name: Originator - name: Funding - name: Balances - name: Compliance - name: UserAccount - name: Blockchain Payment paths: /v1/ach/{ach_id}/return: post: tags: - ACH summary: Return an ACH description: Issue a return against an incoming ACH. operationId: return-an-ach parameters: - name: Idempotency-Key in: header description: Idempotency key required: false schema: type: string maxLength: 255 - name: ach_id description: ID of the ACH object to be returned. example: ach_xyz001 in: path required: true schema: type: string pattern: ^ach_\w+$ requestBody: content: application/json: schema: type: object required: - return_code properties: return_code: $ref: '#/components/schemas/OutgoingReturnCode' metadata: $ref: '#/components/schemas/Metadata' responses: '200': description: The now-returned original ACH object. content: application/json: schema: $ref: '#/components/schemas/Ach' '400': description: Your request parameters did not validate. content: application/json: schema: $ref: '#/components/schemas/APIError' '404': description: ach_id passed in is not a valid external ACH object. content: application/json: schema: $ref: '#/components/schemas/APIError' components: schemas: OutgoingReturnCode: type: string description: | The NACHA Return code under which to initiate this return. R0x–R5x initiate a standard return against the original ACH origination. R61, R62, R67, R68, R69, R70 dishonor an existing return. R71–R77 contest an existing dishonored return. The return code must match the current state of the return chain. example: R02 enum: - R01 - R02 - R03 - R05 - R07 - R08 - R09 - R10 - R11 - R14 - R15 - R16 - R17 - R22 - R23 - R29 - R61 - R62 - R67 - R68 - R69 - R70 - R71 - R72 - R73 - R74 - R75 - R76 - R77 Metadata: type: object additionalProperties: type: string description: >- A set of key-value pairs that can be used to store additional information related to this object. Ach: type: object properties: id: type: string description: id of the ACH object example: ach_xyz001 pattern: ^ach_\w+$ created_at: type: string format: date-time description: The ISO-8601 timestamp at which the ACH object was created. example: '2022-06-27T11:22:33Z' updated_at: type: string format: date-time description: The ISO-8601 timestamp at which the ACH object was last updated. example: '2022-06-27T11:22:33Z' status: $ref: '#/components/schemas/AchStatus' amount: $ref: '#/components/schemas/Amount' account_id: $ref: '#/components/schemas/AccountID' account_number_id: $ref: '#/components/schemas/AccountNumberID' direction: $ref: '#/components/schemas/Direction' delivery_type: $ref: '#/components/schemas/DeliveryType' transaction_type: $ref: '#/components/schemas/TransactionType' sec_code: $ref: '#/components/schemas/SecCode' currency_code: $ref: '#/components/schemas/CurrencyCode' statement_descriptor: $ref: '#/components/schemas/StatementDescriptor' record_details: type: object properties: transaction_code: $ref: '#/components/schemas/TransactionCode' company_name: type: string description: >- The company that initiated the outgoing ACH. - For outgoing ACH, this value is set from the Account Number object. - For incoming ACH, this value is what we receive from the sender. example: Acme Inc. company_id: type: string description: >- A 10-digit unique identifier used for identify companies collecting payments via ACH debit. If you would like to use a specific company ID when sending outgoing ACH, please contact us. - For outgoing ACH, this value is set from the Account Number object. - For incoming ACH, this value is what we receive from the sender. example: '1234' company_discretionary_data: type: string description: Additional information from the ACH sender on incoming ACHes. example: Acme Inc. effective_date: type: string description: >- The date the ACH transaction is expected to settle with the financial institution. - For outgoing ACH, the date is set by Lead based on the delivery_type field. - For incoming ACH, this value is what we receive from the sender. example: '2022-06-27' settlement_date: type: string description: >- Date by which funds must be posted to the counterparty's account. example: '2022-06-27' individual_id: $ref: '#/components/schemas/IndividualId' receiver_name: $ref: '#/components/schemas/ReceiverName' descriptive_date: $ref: '#/components/schemas/DescriptiveDate' additional_information: $ref: '#/components/schemas/AdditionalInformation' trace_number: type: string description: >- The unique number assigned to every ACH entry by an ODFI which identifies that entry within a specific ACH file. - For outgoing ACH, this is generated by Lead when we submit the ACH. - For incoming ACH, this value is what we receive from the sender. example: '123456789012345' counterparty: $ref: '#/components/schemas/Counterparty' returns: type: array description: Associated returns. items: $ref: '#/components/schemas/Return' reversal: type: object description: A reversal associated with this object. properties: reversal_reason: $ref: '#/components/schemas/ReversalReason' linked_ach_id: type: string description: Id of the reversal object. rejection: $ref: '#/components/schemas/RejectionReason' correction: $ref: '#/components/schemas/AchCorrection' metadata: $ref: '#/components/schemas/Metadata' iat_details: $ref: '#/components/schemas/IatDetails' APIError: type: object properties: code: type: string description: The error code. title: type: string description: The error title. detail: type: string description: A detailed error description. status: type: string description: The HTTP status code. invalid_parameters: type: array description: Invalid request parameters with reasons, if applicable. items: $ref: '#/components/schemas/InvalidParameterDetail' instance: type: string description: >- The object causing this specific occurrence of the error, if applicable. AchStatus: description: The current status of the ACH object. type: string example: submitted enum: - scheduled - processing - submitted - posted - canceled - under_review - approved - rejected - pending_return - returned - pending_dishonored_return - return_dishonored - pending_contested_return - return_contested Amount: description: The amount of the transaction in cents. type: integer format: int64 example: 5000 minimum: 0 maximum: 9900000000 AccountID: type: string description: The ID of the Account object. example: account_xyz123 pattern: ^account_\w+$ AccountNumberID: type: string description: The ID of the Lead Bank Account Number object. example: account_number_xyz123 pattern: ^account_number_\w+$ Direction: type: string description: |- Who is initiating the transaction. outgoing: You are sending a transaction to a counterparty. incoming: You are receiving a transaction from a counterparty. example: outgoing enum: - outgoing - incoming DeliveryType: type: string example: same_business_day description: "How fast you want the counterparty to receive the ACH.\n* `same_business_day`: if the ACH request is submitted before the cutoff window with the same business day option, funds will settle on the same day.\_\n* `next_business_day`: standard ACH processing, for funds to settle on the next business day." enum: - same_business_day - next_business_day TransactionType: type: string description: ACH transaction type. example: credit enum: - credit - debit SecCode: type: string description: >- Standard Entry Class (SEC) code to use for this ACH object. Lead currently only supports `CCD`, `PPD`, `WEB`, and `TEL` for outgoing ACHes. example: WEB enum: - PPD - CCD - ARC - BOC - CIE - CTX - IAT - POP - POS - RCK - TEL - WEB - ADV - DNE - ENR - MTE - SHR - TRC - TRX - COR CurrencyCode: description: A three-letter currency code as defined in ISO 4217. type: string example: USD enum: - USD StatementDescriptor: type: string description: >- The description you would like to appear on your customers’ statement. Maximum number of characters is 10. example: P2P Credit minLength: 1 maxLength: 10 pattern: ^(?!0+$)(?! +$)[\x20-\x7E]*$ TransactionCode: type: string example: checking_credit description: Identifies the type of debit or credit Entry and the account type enum: - checking_credit - checking_credit_prenote - checking_debit - checking_debit_prenote - savings_credit - savings_credit_prenote - savings_debit - savings_debit_prenote IndividualId: type: string description: >- The name of the individual you are sending funds to. _Required for P2P payments._ maxLength: 15 pattern: ^[\x20-\x7E]*$ ReceiverName: type: string description: >- The name of the receiver of funds. _Note: This field is set by the counterparty and may or not be accurate._ pattern: ^[\x20-\x7E]*$ DescriptiveDate: type: string description: >- The date you would like displayed to the counterparty. *Receiving financial institutions may utilize this field to display on the statement.* example: '220627' maxLength: 6 pattern: ^[\x20-\x7E]*$ AdditionalInformation: type: string description: >- Additional information for the ACH recipient. _Not all banks will share this message with their end customer._ maxLength: 80 pattern: ^[\x20-\x7E]*$ Counterparty: type: object description: The details of the counterparty you are sending/receiving money from. required: - account_number - routing_number - account_type - name properties: name: type: string description: The name of the counterparty you are transacting with. example: Lara Smikle maxLength: 22 pattern: ^(?!\s*$)[\x20-\x7E]*$ account_number: type: string description: The account number for the bank account. example: '1032345678' maxLength: 17 pattern: ^[a-zA-Z0-9 ]*[a-zA-Z0-9]+$ routing_number: type: string description: >- The routing number for the bank account. This should be the ACH routing number, not the wire routing number. example: '021000021' minLength: 9 maxLength: 9 pattern: ^[0-9]+$ account_type: $ref: '#/components/schemas/AccountType' Return: type: object properties: type: type: string description: Type of the return record, determined by the respective return code. example: return enum: - return - dishonored_return - contested_return status: $ref: '#/components/schemas/AchStatus' return_code: $ref: '#/components/schemas/ReturnCode' return_reason: type: string description: Short description of the associated return code. trace_number: type: string description: >- The unique number assigned to this ACH return by the ODFI, which identifies the entry within a specific ACH file. example: '123456789012345' additional_information: type: string description: >- Based on the associated return code, if the content is provided by the parties, the additional information field in the ACH addenda. ReversalReason: type: string description: Reason you want to initiate a reversal. enum: - duplicate - receiver_incorrect - amount_incorrect - debit_too_early - credit_too_late RejectionReason: type: object properties: reason: type: string description: The rejection code that indicates the type of rejection example: account_number_status details: type: string description: Additional info about the rejection example: Account number account_123 is inactive. AchCorrection: type: object description: The corrected `counterparty` details. properties: account_number: type: string description: The updated account number for the `counterparty`. example: '1032345678' maxLength: 17 routing_number: type: string description: The updated routing number for the `counterparty`. example: '021000021' minLength: 9 maxLength: 9 account_type: type: string description: The updated account type for the `counterparty`. enum: - checking - savings IatDetails: type: object description: >- IAT (International ACH Transaction) specific details. Present only when sec_code is IAT. properties: transaction_type_code: $ref: '#/components/schemas/IatTransactionTypeCode' destination_country: type: string description: >- ISO 3166-1 alpha-2 country code identifying the destination country of the transaction. example: CA minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ originator_currency_code: type: string description: ISO 4217 three-letter currency code in which the ACH was originated. example: USD minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ destination_currency_code: type: string description: >- ISO 4217 three-letter currency code in which the ACH will be received. example: CAD minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ foreign_trace_number: type: string description: >- Trace number assigned to the Entry in the originating national payments system. Only present for inbound IAT entries. example: FRN-2024-98765-INTL maxLength: 22 pattern: ^[\x20-\x7E]*$ additional_information: $ref: '#/components/schemas/AdditionalInformation' originator: $ref: '#/components/schemas/IatParty' originating_financial_institution: $ref: '#/components/schemas/IatFinancialInstitution' receiver: $ref: '#/components/schemas/IatReceiver' receiving_financial_institution: $ref: '#/components/schemas/IatFinancialInstitution' foreign_correspondent_banks: type: array description: >- Intermediary or correspondent banks in the payment chain. Up to 5 banks may be listed. maxItems: 5 items: $ref: '#/components/schemas/IatFinancialInstitution' InvalidParameterDetail: type: object properties: parameter: type: string description: Which parameter is invalid. example: transaction_type reason: type: string description: Why the parameter is invalid. AccountType: type: string example: checking description: >- The account type for the bank account. This should be one of checking or savings. enum: - checking - savings ReturnCode: type: string description: NACHA Return codes. example: R02 enum: - R01 - R02 - R03 - R04 - R05 - R06 - R07 - R08 - R09 - R10 - R11 - R12 - R13 - R14 - R15 - R16 - R17 - R18 - R19 - R20 - R21 - R22 - R23 - R24 - R25 - R26 - R27 - R28 - R29 - R30 - R31 - R32 - R33 - R34 - R35 - R36 - R37 - R38 - R39 - R40 - R41 - R42 - R43 - R44 - R45 - R46 - R47 - R50 - R51 - R52 - R53 - R61 - R62 - R67 - R68 - R69 - R70 - R71 - R72 - R73 - R74 - R75 - R76 - R77 - R80 - R81 - R82 - R83 - R84 - R85 IatTransactionTypeCode: type: string description: Identifies the purpose of the IAT transaction. example: business enum: - annuity - business - deposit - loan - miscellaneous - mortgage - pension - rental_lease - salary - tax - telephone - internet - accounts_receivable - back_office_conversion - point_of_purchase - represented_check IatParty: type: object description: Name and address of a party to an IAT transaction, in NACHA format. properties: name: type: string description: Name of the party. example: Acme Inc. maxLength: 35 pattern: ^[\x20-\x7E]*$ street_address: type: string description: Physical street address of the party. example: 123 Main Street maxLength: 35 pattern: ^[\x20-\x7E]*$ city_state_province: type: string description: City and state or province of the party. Max 35 characters example: New York*NY\ maxLength: 35 pattern: ^[\x20-\x7E]*$ country_postal_code: type: string description: >- Country code and postal code of the party. Country code is ISO 3166-1 alpha-2. Max 35 characters. example: US*10001\ maxLength: 35 pattern: ^[\x20-\x7E]*$ IatFinancialInstitution: type: object description: Financial institution details for an IAT transaction. properties: name: type: string description: Name of the financial institution. example: First National Bank maxLength: 35 pattern: ^[\x20-\x7E]*$ identifier_type: type: string description: Type of bank identifier example: swift_bic enum: - national_clearing_system - business_identifier_code - iban identifier_code: type: string description: >- The identifier value for the financial institution, corresponding to the `identifier_type` (e.g., SWIFT BIC, routing number, IBAN). example: FNBUS33XXX maxLength: 34 pattern: ^[\x20-\x7E]*$ branch_country: type: string description: >- ISO 3166-1 alpha-2 country code for the branch country of the financial institution. example: US minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ IatReceiver: type: object description: >- Name, reference number, and address of the receiver of an IAT transaction. properties: name: type: string description: Name of the receiver or beneficiary of the transaction. example: Lara Smikle maxLength: 35 pattern: ^[\x20-\x7E]*$ reference_number: type: string description: >- Reference number assigned by the originator for tracking this receiver or payment. example: RCV-2024-001 maxLength: 15 pattern: ^[\x20-\x7E]*$ street_address: type: string description: Physical street address of the receiver. example: 456 Maple Avenue maxLength: 35 pattern: ^[\x20-\x7E]*$ city_state_province: type: string description: City and state or province of the receiver. Max 35 characters. example: Toronto*ON\ maxLength: 35 pattern: ^[\x20-\x7E]*$ country_postal_code: type: string description: >- Country code and postal code of the receiver. Country code is ISO 3166-1 alpha-2. Max 35 characters. example: CA*M5H 2N2\ maxLength: 35 pattern: ^[\x20-\x7E]*$ securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````