openapi: 3.2.0
info:
  description: This API covers publicly accessible merchant actions
  version: 2.2.0
  title: Helcim Customer API
servers:
- url: https://api.helcim.com/v2
- url: https://api.helcim.test/v2
tags:
- name: Customer
paths:
  /customers:
    get:
      tags:
      - Customer
      summary: Get customers
      operationId: get-customers
      parameters:
      - in: query
        name: search
        description: The search term to be used for partial matching on contactName, businessName, customerCode, city, phone and email (Only use one query field per request).
        example: john
        schema:
          type: string
      - in: query
        name: customerCode
        description: Existing customer code (Only use one query field per request).
        example: CST1000
        schema:
          type: string
      - in: query
        name: limit
        description: The limit number of customers will be returned in one request. We only allow maximum 100 objects per request. If no limit specified, the default limit will be 100 objects.
        example: 25
        schema:
          type: integer
      - in: query
        name: page
        description: Specifies the page number of the results you want to retrieve.
        example: 1
        schema:
          type: integer
      - in: query
        name: includeCards
        description: "Specifies whether to return any credit cards for retrieved customers. By default no cards are returned.\n  * `yes` - return all available cards for retrieved customers.\n"
        example: 'yes'
        schema:
          type: string
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Customer'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
    post:
      tags:
      - Customer
      summary: Create customer
      operationId: create-customer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
  /customers/{customerId}:
    get:
      tags:
      - Customer
      summary: Get customer
      operationId: get-customer
      parameters:
      - in: path
        name: customerId
        schema:
          type: integer
        required: true
        description: The Id of the customer
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
    put:
      tags:
      - Customer
      summary: Update customer
      operationId: update-customer
      parameters:
      - in: path
        name: customerId
        schema:
          type: string
        required: true
        description: The Id of the customer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdateRequest'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
  /customers/{customerId}/cards:
    get:
      tags:
      - Customer
      summary: Get customer cards
      operationId: get-customer-cards
      parameters:
      - in: path
        name: customerId
        schema:
          type: integer
        required: true
        description: The Id of the customer
      - in: query
        name: cardToken
        description: The card token.
        example: 907af81acc0224e0134949
        schema:
          type: string
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CardResponse'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
  /customers/{customerId}/cards/{cardId}:
    get:
      tags:
      - Customer
      summary: Get customer card
      operationId: get-customer-card
      parameters:
      - in: path
        name: customerId
        schema:
          type: integer
        required: true
        description: The Id of the customer
      - in: path
        name: cardId
        schema:
          type: integer
        required: true
        description: The Id of the card
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CardResponse'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
    delete:
      tags:
      - Customer
      summary: Delete customer card
      operationId: delete-customer-card
      parameters:
      - in: path
        name: customerId
        schema:
          type: integer
        required: true
        description: The ID of the customer
      - in: path
        name: cardId
        schema:
          type: integer
        required: true
        description: The ID of the card
      responses:
        '204':
          description: Successfully deleted card
        '404':
          description: No card found
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
  /customers/{customerId}/cards/{cardId}/default:
    patch:
      tags:
      - Customer
      summary: Set customer card as default
      operationId: set-customer-card-default
      parameters:
      - in: path
        name: customerId
        schema:
          type: integer
        required: true
        description: The ID of the customer
      - in: path
        name: cardId
        schema:
          type: integer
        required: true
        description: The ID of the card
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Customer'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
  /customers/{customerId}/pads:
    get:
      tags:
      - Customer
      summary: Get all PADS for a customer.
      operationId: get-pads
      parameters:
      - name: customerId
        in: path
        description: Customer ID.
        required: true
        schema:
          type: number
      responses:
        '200':
          description: Successfully retrieved all PADs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Res'
        '204':
          description: No PADs for a given customer.
        '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: []
  /customers/{customerId}/bank-accounts:
    get:
      tags:
      - Customer
      summary: Get customer bank accounts.
      operationId: get-customer-bank-accounts
      parameters:
      - in: path
        name: customerId
        schema:
          type: integer
        required: true
        description: The ID of the customer
      - in: query
        name: bankToken
        description: The bank account token.
        schema:
          type: string
      - in: query
        name: verified
        description: If the bank account is verified or not. Use 1 or 0.
        schema:
          type: number
      - in: query
        name: ready
        description: If the bank account is verified or not. Use 1 or 0.
        schema:
          type: number
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccountResponse'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
    post:
      tags:
      - Customer
      summary: Create a bank account.
      operationId: create-bank-account
      parameters:
      - name: customerId
        in: path
        description: Customer ID.
        required: true
        schema:
          type: number
      requestBody:
        description: Bank information.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Req'
      responses:
        '201':
          description: Successfully created new bank account. A bank authorization was also emailed to the customer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Res-2'
        '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: []
  /customers/{customerId}/bank-accounts/request-new:
    get:
      tags:
      - Customer
      summary: Request bank account information from a customer.
      operationId: request-new-bank-account
      parameters:
      - name: customerId
        in: path
        description: Customer ID.
        required: true
        schema:
          type: number
      responses:
        '200':
          description: Successfully sent bank account request email to customer.
        '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: []
  /customers/{customerId}/bank-accounts/{bankAccountId}:
    get:
      tags:
      - Customer
      summary: Get customer bank account
      operationId: get-customer-bank-account
      parameters:
      - in: path
        name: customerId
        schema:
          type: integer
        required: true
        description: The Id of the customer
      - in: path
        name: bankAccountId
        schema:
          type: integer
        required: true
        description: The Id of the bank account
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccountResponse'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
    delete:
      tags:
      - Customer
      summary: Delete customer bank account.
      operationId: delete-customer-bank-account
      parameters:
      - in: path
        name: customerId
        schema:
          type: integer
        required: true
        description: The ID of the customer
      - in: path
        name: bankAccountId
        schema:
          type: integer
        required: true
        description: The ID of the bank account.
      responses:
        '204':
          description: Bank account successfully deleted.
        '400':
          description: Invalid request. Customer ID or bank account ID is missing or invalid.
        '403':
          description: User does not have valid permissions.
        '404':
          description: Bank account not found or has already been deleted.
        '500':
          description: Internal server error while deleting the bank account.
      security:
      - ApiAccessAuth: []
  /customers/{customerId}/bank-accounts/{bankAccountId}/default:
    patch:
      tags:
      - Customer
      summary: Set customer bank account as default
      operationId: set-customer-bank-account-default
      parameters:
      - in: path
        name: customerId
        schema:
          type: integer
        required: true
        description: The Id of the customer
      - in: path
        name: bankAccountId
        schema:
          type: integer
        required: true
        description: The Id of the bank account
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BankAccountResponse'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedPaymentResponse'
      security:
      - ApiAccessAuth: []
  /customers/{customerId}/bank-accounts/{bankAccountId}/pads/{padId}:
    get:
      tags:
      - Customer
      summary: Get a PAD by its ID.
      operationId: get-pad
      parameters:
      - name: customerId
        in: path
        description: Customer ID.
        required: true
        schema:
          type: number
      - name: bankAccountId
        in: path
        description: Bank account ID.
        required: true
        schema:
          type: number
      - name: padId
        in: path
        description: PAD ID.
        required: true
        schema:
          type: number
      responses:
        '200':
          description: Successfully retrieved PAD.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Res-3'
        '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: []
    put:
      tags:
      - Customer
      summary: Update a PAD by its ID.
      operationId: update-pad
      parameters:
      - name: customerId
        in: path
        description: Customer ID.
        required: true
        schema:
          type: number
      - name: bankAccountId
        in: path
        description: Bank account ID.
        required: true
        schema:
          type: number
      - name: padId
        in: path
        description: PAD ID.
        required: true
        schema:
          type: number
      requestBody:
        description: Optional PAD fields to be updated.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Req-2'
      responses:
        '200':
          description: Successfully updated PAD.
        '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: []
components:
  schemas:
    CardResponse:
      title: Card
      type: object
      properties:
        id:
          type: integer
          example: 161462
          description: The id of the card.
        cardToken:
          type: string
          example: 907af81acc0224e0134949
          description: The card token.
        dateCreated:
          type: string
          example: '2025-01-30 13:35:36'
          description: The date when the card is created.
        dateUpdated:
          type: string
          example: '2025-01-30 13:35:36'
          description: The date when the card last got updated.
        cardHolderName:
          type: string
          example: John Smith
          description: The cardholder name.
        cardF6L4:
          type: string
          example: '5454545454'
          description: The first-six and last-four card numbers.
        cardExpiry:
          type: string
          example: '1257'
          description: The card expiry date, in MMYY format (total of 4 digits without spaces or slashes).
        cardCVV:
          type: string
          example: '100'
          description: The card CVV (3-4 digits on back of credit card).
    Customer:
      type: object
      properties:
        id:
          type: integer
          example: 2488717
          description: Id of Customer
        customerCode:
          type: string
          example: CST1200
          description: Customer code of the customer
        businessName:
          type: string
          example: Best company
          description: Name of the business
        contactName:
          type: string
          example: John Smith
          description: Contact Name
        cellPhone:
          type: string
          example: 908-295-4902
          description: Cell phone number of customer
        billingAddress:
          $ref: '#/components/schemas/Address'
        shippingAddress:
          $ref: '#/components/schemas/Address'
        cards:
          type: array
          description: Array of cards stored in the vault associated with this customer.
          items:
            title: Card
            type: object
            properties:
              cardHolderName:
                type: string
                example: John Smith
                description: The card holder name.
              cardF6L4:
                type: string
                example: 5454545454
                description: The F6L4 of card.
              cardToken:
                type: string
                example: a1b2c3d4e5f6
                description: Card token
    Res-3:
      title: Get Pre-Authorized Debit Agreement Response Payload
      type: object
      properties:
        pad:
          $ref: '#/components/schemas/Pad'
    Pad:
      title: Pre-Authorized Debit Agreement
      type: object
      properties:
        id:
          type: integer
          format: int64
        accepted:
          type: integer
          format: int8
          enum:
          - 0
          - 1
          description: "Whether the PAD was accepted or not:\n  * `0` - Unaccepted\n  * `1` - Accepted\n"
        bankAccountId:
          type: integer
          format: int8
        customerId:
          type: integer
          format: int64
        dateAccepted:
          type: string
          format: date-time
        dateCreated:
          type: string
          format: date-time
        dateEarliestDebit:
          type: string
          format: date-time
        dateRevoked:
          type: string
          format: date-time
        dateUpdated:
          type: string
          format: date-time
        ipAddress:
          type: string
        merchantId:
          type: integer
          format: int64
        type:
          type: integer
          format: int8
          enum:
          - 1
          - 2
          description: "The type of the bank account:\n  * `1` - Personal\n  * `2` - Business\n"
        status:
          type: integer
          format: int8
          enum:
          - 1
          - 2
          description: "The status of the PAD:\n  * `1` - Active\n  * `2` - Inactive\n"
      example:
        id: 238954
        accepted: 1
        bankAccountId: 111
        customerId: 222
        dateAccepted: '2023-04-23 13:30:00'
        dateCreated: '2023-09-19 13:30:00'
        dateEarliestDebit: '2023-10-06 13:30:00'
        dateRevoked: '2023-11-17 13:30:00'
        dateUpdated: '2023-08-10 13:30:00'
        ipAddress: 123.456.789.0
        merchantId: 333
        type: 2
        status: 2
    Message:
      title: Generic Response Payload Message
      type: object
      properties:
        message:
          type: string
    CustomerRequest:
      title: Customer Request
      type: object
      properties:
        customerCode:
          type: string
          example: CST1000
          description: The unique customer code. If blank, it will be automatically generated.
        contactName:
          type: string
          example: John Smith
          description: The primary contact name (full name) of the customer.
        businessName:
          type: string
          example: Best Company
          description: The business name of the customer. There must be either a contact name or business name present.
        cellPhone:
          type: string
          example: 908-295-4902
          description: The cell phone number of the customer.
        billingAddress:
          $ref: '#/components/schemas/Address'
        shippingAddress:
          $ref: '#/components/schemas/Address'
    CustomerUpdateRequest:
      title: Customer Update Request
      type: object
      properties:
        customerCode:
          type: string
          example: CST1000
          description: The unique customer code.
        contactName:
          type: string
          example: John Smith
          description: The primary contact name (full name) of the customer.
        businessName:
          type: string
          example: Best Company
          description: The business name of the customer. There must be either a contact name or business name present.
        cellPhone:
          type: string
          example: 908-295-4902
          description: The cell phone number of the customer.
        billingAddress:
          $ref: '#/components/schemas/Address'
        shippingAddress:
          $ref: '#/components/schemas/Address'
    Req-2:
      title: Update Pre-Authorized Debit Agreement
      type: object
      properties:
        accepted:
          type: integer
          format: int8
          enum:
          - 0
          - 1
          description: "Whether the PAD was accepted or not:\n  * `0` - Unaccepted\n  * `1` - Accepted\n\nIf the PAD is set to accepted and the PAD is active, a side effect of updating the associated bank account to ready will also happen. If the PAD was set to unaccepted, it will unready the bank account.\n"
        ipAddress:
          type: string
        type:
          type: integer
          format: int8
          enum:
          - 1
          - 2
          description: "The type of the bank account:\n  * `1` - Personal\n  * `2` - Business\n"
        status:
          type: integer
          format: int8
          enum:
          - 1
          - 2
          description: "The status of the PAD:\n  * `1` - Active\n  * `2` - Inactive\n\nIf the PAD is set to active and the PAD is accepted, a side effect of updating the associated bank account to ready will also happen. If the PAD was unaccepted, it will unready the bank account. Note: there can only be 1 active PAD per bank account.\n"
      example:
        accepted: 1
        ipAddress: 123.456.789.0
        type: 2
        status: 1
    FailedPaymentResponse:
      type: object
      properties:
        errors:
          type: array
          description: List of errors
          items:
            type: string
            example: An error occurred
    BankAccountResponse:
      title: BankAccount
      type: object
      properties:
        id:
          type: integer
          example: 12312
          description: The id of the bank account.
        customerId:
          type: integer
          example: 2222
          description: The id of the customer owning the bank account.
        dateCreated:
          type: string
          example: '2025-01-30 13:35:36'
          description: The date when the bank account is created.
        dateUpdated:
          type: string
          example: '2025-01-30 13:35:36'
          description: The date when the bank account last got updated.
        dateLastUsed:
          type: string
          example: '2025-01-30 13:35:36'
          description: The date when the bank account last got used.
        dateVerified:
          type: string
          example: '2025-01-30 13:35:36'
          description: The date when the bank account is verified.
        bankToken:
          type: string
          example: JHKJHKLKJLOHKJ876545KJBK
          description: The token of the bank account.
        accountType:
          type: string
          example: CHECKING
          description: The type of the bank account, such as CHECKING | SAVINGS.
        accountCorporate:
          type: string
          example: PERSONAL
          description: The corporate type of the bank account, such as PERSONAL | CORPORATE.
        verified:
          type: string
          example: 1
          description: Verified status of the bank account, 1|0.
        ready:
          type: string
          example: 1
          description: Ready status of the bank account, 1|0.
        bankIdNumber:
          type: string
          example: '333'
          description: The institution number of Canadian Bank Account that identifies the bank.
        transitNumber:
          type: string
          example: '55555'
          description: The transit number of Canadian Bank Account. Shows which branch you opened your account at.
        routingNumber:
          type: string
          example: '999999999'
          description: The routing number of US Bank Account. Identifies the financial institution on which it was drawn.
        bankAccountNumberL4:
          type: string
          example: '9999'
          description: Last 4 digits of the bank account number.
        address:
          $ref: '#/components/schemas/Address'
    Req:
      title: Create Bank Account Request Payload
      type: object
      required:
      - accountCorporate
      - accountType
      - bankAccountNumber
      - city
      - countryAlpha2
      - postalCode
      - provinceAlpha2
      - streetAddress
      properties:
        accountCorporate:
          type: integer
          format: int8
          enum:
          - 1
          - 2
          description: "The bank account type:\n  * `1` - Personal\n  * `2` - Corporate\n"
        accountType:
          type: integer
          format: int8
          enum:
          - 1
          - 2
          description: "The bank account type:\n  * `1` - Checking\n  * `2` - Savings\n"
        bankAccountNumber:
          type: string
          description: 7-12 digits for Canadian bank accounts and 8-12 for US bank accounts.
        bankFinancialNumber:
          type: string
          description: This 3 digit number is needed for Canadian bank accounts.
        bankRoutingNumber:
          type: string
          description: This 9 digit number is needed for US bank accounts.
        bankTransitNumber:
          type: string
          description: This 5 digit number is needed for Canadian bank accounts.
        city:
          type: string
        countryAlpha2:
          type: string
          description: Country name in ISO2 format, e.g "CA", "US"
        firstName:
          type: string
          description: Either first and last name or company name need to be specified.
        lastName:
          type: string
          description: Either first and last name or company name need to be specified.
        companyName:
          type: string
          description: Either first and last name or company name need to be specified.
        postalCode:
          type: string
        provinceAlpha2:
          type: string
          description: Province/State name in ISO2 format, e.g "AB", "ON"
        streetAddress:
          type: string
      example:
        accountCorporate: 1
        accountType: 2
        bankAccountNumber: '123456789'
        bankFinancialNumber: '123'
        bankTransitNumber: '12345'
        city: Calgary
        countryAlpha2: CA
        firstName: John
        lastName: Doe
        postalCode: T2P5E9
        provinceAlpha2: AB
        streetAddress: 440 2 Ave SW
    Address:
      title: Address
      type: object
      required:
      - name
      - street1
      - postalCode
      properties:
        name:
          type: string
          description: 'The recipient''s name or business name for this address.

            '
          example: John Smith / Helcim
        street1:
          type: string
          description: 'The primary street address.

            '
          example: 21 Jump Street
        street2:
          type: string
          description: 'Additional address details, such as unit or suite number.

            '
          example: Suite 400
        city:
          type: string
          description: 'The city for this address.

            '
          example: Calgary
        province:
          type: string
          description: 'The two-letter province or state code (e.g., AB, BC, CA).  Required if the country is CAN or USA.

            '
          example: AB
        country:
          type: string
          description: 'The three-letter [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code (e.g., CAN, USA).

            '
          example: CAN
        postalCode:
          type: string
          description: 'The postal or ZIP code for this address.

            '
          example: H0H0H0
        phone:
          type: string
          description: 'Contact phone number (10 to 15 digits).

            '
          example: 4031231234
        email:
          type: string
          description: 'Contact email address for this address.

            '
          example: john@example.com
    Res-2:
      type: object
      properties:
        message:
          type: string
          example: 'Successfully created new bank account with ID #12345. A bank authorization email was also emailed to customer@helcim.com.'
        bankAccount:
          type: object
          properties:
            id:
              type: integer
              format: int64
          example:
            id: 12345
    Res:
      title: Get All Pre-Authorized Debit Agreement Response Payload
      type: object
      properties:
        pads:
          type: array
          items:
            $ref: '#/components/schemas/Pad'
  securitySchemes:
    ApiAccessAuth:
      description: API Token with required permissions
      type: apiKey
      in: header
      name: api-token