Helcim ACH Payment API

openapi: 3.2.0
info:
  description: This API covers publicly accessible merchant actions
  version: 2.2.0
  title: Helcim ACH Payment API
servers:
- url: https://api.helcim.com/v2
- url: https://api.helcim.test/v2
tags:
- name: ACH Payment
paths:
  /ach/withdraw:
    put:
      tags:
      - ACH Payment
      summary: Process an ACH withdraw
      operationId: ach-withdraw
      parameters:
      - in: header
        name: idempotency-key
        description: A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Req-3'
      responses:
        '200':
          description: An ACH withdrawal was successfully processed. This does not guarantee that all necessary sub-objects were updated, only a guarantee that the payments action was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Res-4'
        '400':
          description: Invalid request. Likely caused by malformed content in request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '403':
          description: User does not have valid permissions.
        '500':
          description: Unexpected internal error.
      security:
      - ApiAccessAuth: []
  /ach/transactions:
    get:
      tags:
      - ACH Payment
      summary: Collects all ACH transactions
      operationId: get-many-ach-transactions
      parameters:
      - in: query
        name: page
        description: Page number for paginated results.
        example: 1
        schema:
          type: integer
          minimum: 1
      - in: query
        name: limit
        description: 'The number of transactions that will be returned in one request. We only allow maximum 125 objects per request.  If no limit specified, the default limit will be 125 objects.

          '
        example: 50
        schema:
          type: integer
          maximum: 125
      - in: query
        name: startDate
        description: 'Filter transactions created on or after this date. Format: `YYYY-MM-DD`. If `endDate` is provided, it must not be earlier than `startDate`.

          '
        example: '2020-01-01'
        schema:
          type: string
          format: date
      - in: query
        name: endDate
        description: 'Filter transactions created on or before this date. Format: `YYYY-MM-DD`. If `startDate` is provided, `endDate` must not be earlier than `startDate`.

          '
        example: '2021-01-01'
        schema:
          type: string
          format: date
      - in: query
        name: amountMin
        description: 'Filter transactions by minimum amount. If `amountMax` is provided, `amountMin` must not be greater than `amountMax`.

          '
        example: 150
        schema:
          type: number
          format: float
      - in: query
        name: amountMax
        description: 'Filter transactions by maximum amount. If `amountMin` is provided, `amountMax` must not be less than `amountMin`.

          '
        example: 200
        schema:
          type: number
          format: float
      - in: query
        name: statusAuth
        description: Filter transactions by auth status.
        example: APPROVED,PENDING
        schema:
          type: array
          items:
            type: string
            enum:
            - APPROVED
            - DECLINED
            - IN_PROGRESS
            - PENDING
            - CANCELLED
      - in: query
        name: statusClearing
        description: Filter transactions by clearing status.
        example: REJECTED,CONTESTED
        schema:
          type: array
          items:
            type: string
            enum:
            - OPENED
            - CLEARED
            - REJECTED
            - CONTESTED
            - RETURNED
      - in: query
        name: users
        description: Filter transactions by users.
        example: 1234,5678,8271
        schema:
          type: array
          items:
            type: integer
      - in: query
        name: search
        description: 'Searches id, bankAccountL4l4, order id, batch id, contact name and business name.

          '
        example: Joe
        schema:
          type: string
      responses:
        '200':
          description: All ACH transactions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransactionEft'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '403':
          description: User does not have valid permissions.
        '500':
          description: Unexpected internal error.
      security:
      - ApiAccessAuth: []
  /ach/transactions/{transactionId}:
    get:
      tags:
      - ACH Payment
      summary: Retrieves a single ACH transaction
      operationId: get-ach-transaction-by-id
      parameters:
      - name: transactionId
        in: path
        schema:
          type: integer
        required: true
        description: The ID of the ACH transaction.
      responses:
        '200':
          description: An ACH transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionEft'
        '400':
          description: Invalid request. Likely due to using an invalid ACH transaction ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '403':
          description: User does not have valid permissions.
        '500':
          description: Unexpected internal error.
      security:
      - ApiAccessAuth: []
  /ach/transactions/{transactionId}/refund:
    put:
      tags:
      - ACH Payment
      summary: Refund an ACH transaction
      operationId: ach-refund
      parameters:
      - in: header
        name: idempotency-key
        description: A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: transactionId
        description: The ID of the ACH transaction to refund.
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Req-4'
      responses:
        '200':
          description: An ACH refund was successfully processed. This does not guarantee that all necessary sub-objects were updated, only a guarantee that the payments action was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Res-5'
        '400':
          description: Invalid request. Likely caused by malformed content in request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '403':
          description: User does not have valid permissions.
        '500':
          description: Unexpected internal error.
      security:
      - ApiAccessAuth: []
  /ach/transactions/{transactionId}/void:
    put:
      tags:
      - ACH Payment
      summary: Void an ACH transaction
      operationId: ach-void
      parameters:
      - in: header
        name: idempotency-key
        description: A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: transactionId
        description: The ID of the ACH transaction to void.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The ACH transaction was successfully voided. This does not guarantee that all necessary sub-objects were updated, only a guarantee that the payments action was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Res-6'
        '400':
          description: Invalid request. Likely caused by providing an ACH transaction ID referencing a transaction that is not eligible for voiding.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '403':
          description: User does not have valid permissions.
        '500':
          description: Unexpected internal error.
      security:
      - ApiAccessAuth: []
  /ach/transactions/{transactionId}/cancel:
    patch:
      tags:
      - ACH Payment
      summary: Cancel a pending ACH transaction
      operationId: ach-cancel
      parameters:
      - in: header
        name: idempotency-key
        description: A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: transactionId
        description: The ID of the ACH transaction to cancel.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The pending ACH transaction was successfully cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Res-7'
        '400':
          description: Invalid request. Likely due to the ACH transaction not being pending.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '403':
          description: User does not have valid permissions.
        '500':
          description: Unexpected internal error.
      security:
      - ApiAccessAuth: []
  /ach/batches:
    get:
      tags:
      - ACH Payment
      summary: Collects all ACH batches
      operationId: get-many-ach-batches
      responses:
        '200':
          description: All ACH Batches.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AchBatch'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '403':
          description: User does not have valid permissions.
        '500':
          description: Unexpected internal error.
      security:
      - ApiAccessAuth: []
  /ach/batches/{batchId}/settle:
    put:
      tags:
      - ACH Payment
      summary: Settle an ACH batch
      operationId: ach-batch-settle
      parameters:
      - in: header
        name: idempotency-key
        description: A UUID-formatted idempotency key. Accepted format is 25-36 alphanumeric characters (including '-' and '_').
        required: true
        schema:
          type: string
          format: uuid
      - name: batchId
        in: path
        schema:
          type: integer
        required: true
        description: The ID of the ACH batch.
      responses:
        '200':
          description: The ACH batch was successfully settled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Res-8'
        '400':
          description: Invalid request. Likely caused by the batch not being eligible for settling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '403':
          description: User does not have valid permissions.
        '500':
          description: Unexpected internal error.
      security:
      - ApiAccessAuth: []
components:
  schemas:
    Req-3:
      title: ACH Withdraw Request Payload
      type: object
      required:
      - bankAccountId
      - customerId
      - amount
      - currencyId
      properties:
        bankAccountId:
          type: integer
          format: int64
          description: The bank account ID to withdraw from.
        customerId:
          type: integer
          format: int64
          description: The customer ID associated with the bank account.
        orderId:
          type: integer
          format: int64
          description: An optional invoice ID to process the withdrawal with. If provided, the withdrawal action will perform invoice and inventory management.
        amount:
          type: number
          format: float
          description: The amount to withdraw.
        currencyId:
          type: integer
          format: int64
          enum:
          - 1
          - 2
          description: "The currency of the transaction:\n  * `1` - CAD\n  * `2` - USD\n"
      example:
        bankAccountId: 1182342
        customerId: 389829
        orderId: 12083
        amount: 79.99
        currencyId: 1
    Res-7:
      title: ACH Cancel Response Payload
      type: object
      properties:
        message:
          type: string
      example:
        message: 'Successfully cancelled ACH transaction #34232.'
    Res-8:
      title: ACH Void Response Payload
      type: object
      properties:
        message:
          type: string
      example:
        message: 'Successfully settled ACH batch ID #1533.'
    Res-4:
      title: ACH Withdraw Response Payload
      type: object
      properties:
        transaction:
          $ref: '#/components/schemas/TransactionEft'
    Res-6:
      title: ACH Void Response Payload
      type: object
      properties:
        message:
          type: string
      example:
        message: 'Successfully voided transaction ID #24732. Void transaction ID #24859 created.'
    Req-4:
      title: ACH Refund Request Payload
      type: object
      required:
      - amount
      properties:
        amount:
          type: number
          format: float
          description: The amount to be refunded.
      example:
        amount: 96.34
    Message:
      title: Generic Response Payload Message
      type: object
      properties:
        message:
          type: string
    AchBatch:
      title: ACH Batch
      type: object
      properties:
        batchId:
          type: integer
          format: int64
          example: 861456
          description: The id for the ACH batch.
        batchReference:
          type: string
          example: ach-1234
          description: The reference identifier for the ACH batch.
        merchantId:
          type: integer
          format: int64
          example: 8
          description: The id of the merchant associated with this batch.
        statusBatch:
          type: integer
          format: int64
          example: 1
          description: 'The current state of the batch. Valid values: 1 (Open), 2 (Closed).'
          enum:
          - 1
          - 2
        amountWithdrawals:
          type: number
          format: float
          example: 120.5
          description: The total monetary amount withdrawn.
        countWithdrawals:
          type: number
          format: int64
          example: 2
          description: The number of withdrawn transactions.
        amountDeposits:
          type: number
          format: float
          example: 150
          description: The total monetary amount deposited.
        countDeposits:
          type: number
          format: int64
          example: 2
          description: The number of deposited transactions.
        amountReversed:
          type: number
          format: float
          example: 0
          description: The total monetary amount reversed.
        countReversed:
          type: number
          format: int64
          example: 0
          description: The number of reversed transactions.
        amountRefunded:
          type: number
          format: float
          example: 8.5
          description: The total monetary amount refunded.
        countRefunded:
          type: number
          format: int64
          example: 5
          description: The number of refunded transactions.
        dateOpened:
          type: string
          example: '2026-05-06 13:01:15'
          description: The timestamp indicating when the batch was opened.
        dateClosed:
          type: string
          example: '2026-05-06 13:01:15'
          description: The timestamp indicating when the batch was closed.
    Res-5:
      title: ACH Refund Response Payload
      type: object
      properties:
        message:
          type: string
      example:
        message: 'Successfully refunded transaction ID #1342. Refund transaction ID #1355 created.'
    TransactionEft:
      title: ACH Transaction
      type: object
      properties:
        id:
          type: integer
          format: int64
        merchantId:
          type: integer
          format: int64
        dateCreated:
          type: string
          format: date-time
        statusAuth:
          type: integer
          format: int64
        statusClearing:
          type: integer
          format: int64
        userId:
          type: integer
          format: int64
        batchId:
          type: integer
          format: int64
        bankAccountId:
          type: integer
          format: int64
        bankAccountL4l4:
          type: integer
          format: int64
        transactionType:
          type: integer
          format: int64
        amount:
          type: number
          format: float
        currency:
          type: integer
          format: int64
        approvalCode:
          type: string
        test:
          type: integer
          format: int64
        acquirerTransactionId:
          type: string
        responseMessage:
          type: string
        payFacTransactionId:
          type: integer
          format: int64
        originalTransactionId:
          type: integer
          format: int64
        statusBatch:
          type: integer
          format: int64
        dateClosed:
          type: string
          format: date-time
  securitySchemes:
    ApiAccessAuth:
      description: API Token with required permissions
      type: apiKey
      in: header
      name: api-token