openapi: 3.0.3
info:
  title: IngoPay API — Push Method Check by Mail
  description: >
    Submit a request to push funds to a customer via physical check by mail
    (account_type: CK).


    The partner and their customer should be committed to the payment prior to
    making this call. A successful response confirms the payment item has been
    accepted. **Once accepted, a payment cannot be reversed.**


    > **Assume Success:** Clients should assume success for any Process request
    where a response was not received from Ingo Payments, including assumption
    of normal settlement. Any consumer funds associated with the transaction
    should be accounted for aligning with normal successful transaction
    processing.


    > **Log Transaction ID:** Log the Ingo `transaction_id` and
    `participant_unique_id1` for every transaction — Ingo Payment Services will
    request these values for any support interactions.
  version: '11'
  contact:
    name: Ingo Money Developer Support
    url: https://developers.ingomoney.com
servers:
  - url: https://payapi-sandbox.ingo.money
    description: Sandbox
  - url: https://payapi.ingo.money
    description: Production
paths:
  /gateway/process--check:
    post:
      summary: Push funds via check by mail
      description: >
        Initiates a push disbursement by issuing a physical check mailed to the
        recipient address associated with the `customer_account_token` from a
        prior Verify call. `account_type` must always be `CK` for this
        operation.
      operationId: processCheck
      tags:
        - Push Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessCheckRequest'
            example:
              participant_id: 12345
              account_type: CK
              amount: 500
              source_of_funds: 4
              participant_unique_id1: 35a792a5-39e6-46fa-add1-419a75d3aa9a
              timestamp: 1597862420
              version: 11
              customer_account_token: 6218c726-3989-40ab-af84-fa6f4c932cb6
              recipient_phone: '5555550100'
              participant_unique_id2: 2d4ebd46-616b-4212-bc54-1f7f68514e1a
              check_memo_data: 'Invoice #12345'
              remittance_memo_data: Payment for services rendered Q2 2026
              store_id: STORE-001
              clerk_id: CLK-007
              terminal_id: TERM-042
              ledger:
                api_key: lk_live_abc123xyz
                user_id: usr_00456
                entity_type: program
                entity_id: ent_00789
      responses:
        '200':
          description: Payment accepted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessCheckResponse'
              example:
                status: 100
                client_message: Success
                data:
                  check_number: '100042'
                  transaction_id: 2361540
                  customer_account_token: 6218c726-3989-40ab-af84-fa6f4c932cb6
                  estimated_posting_date: 08/29/2020
                  estimated_posting_time: Payment will post 7-10 Days
                  participant_unique_id1: 35a792a5-39e6-46fa-add1-419a75d3aa9a
                  participant_unique_id2: 2d4ebd46-616b-4212-bc54-1f7f68514e1a
                  request_timestamp: 1597862480
        '400':
          description: Validation error — check request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 700
                client_message: Account not currently available for payment
                data:
                  request_timestamp: 1597862480
components:
  schemas:
    ProcessCheckRequest:
      type: object
      required:
        - participant_id
        - account_type
        - amount
        - source_of_funds
        - participant_unique_id1
        - timestamp
        - version
        - customer_account_token
      properties:
        participant_id:
          type: integer
          description: Unique participant identifier assigned by Ingo.
          example: 12345
        account_type:
          type: string
          enum:
            - CK
          minLength: 1
          description: Always `CK` for check by mail disbursements.
          example: CK
        amount:
          type: number
          format: float
          minimum: 0.01
          description: Amount of the transaction.
          example: 500
        source_of_funds:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
          description: >
            Funding source indicator: 1 = Cash, 2 = Check, 3 = Combo of Cash &
            Check, 4 = Corp Disbursement.
          example: 4
        participant_unique_id1:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            Participant assigned transaction ID for the process request. Value
            must be unique and may not contain NPI data. Used for idempotency —
            a duplicate value returns an idempotent response without initiating
            a new push request. Appears on daily reconciliation reports.
          example: 35a792a5-39e6-46fa-add1-419a75d3aa9a
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp of the request.
          example: 1597862420
        version:
          type: integer
          description: API version of the request. Current version is 11.
          example: 11
        customer_account_token:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            Token representing the account number and customer data as provided
            in the response from a previous Verify API call.
          example: 6218c726-3989-40ab-af84-fa6f4c932cb6
        recipient_phone:
          type: string
          maxLength: 25
          nullable: true
          description: Recipient phone number.
          example: '5551234567'
        participant_unique_id2:
          type: string
          maxLength: 255
          nullable: true
          description: >
            Optional second participant assigned transaction ID. Does not appear
            on daily reconciliation reports.
          example: 2d4ebd46-616b-4212-bc54-1f7f68514e1a
        check_memo_data:
          type: string
          maxLength: 30
          nullable: true
          description: |
            Optional memo line printed on the check. Maximum 30 characters.
          example: 'Invoice #12345'
        remittance_memo_data:
          type: string
          maxLength: 193
          nullable: true
          description: >
            Optional remittance memo data included with the check mailing.
            Maximum 193 characters.
          example: Payment for services rendered Q2 2026
        store_id:
          type: string
          maxLength: 255
          nullable: true
          description: |
            Client assigned store ID. Required for Retail client participants.
          example: STORE-001
        clerk_id:
          type: string
          maxLength: 255
          nullable: true
          description: |
            Client assigned clerk ID. Required for Retail client participants.
          example: CLK-007
        terminal_id:
          type: string
          maxLength: 255
          nullable: true
          description: >
            Client assigned terminal ID. Required for Retail client
            participants.
          example: TERM-042
        ledger:
          $ref: '#/components/schemas/Ledger'
    Ledger:
      type: object
      description: >
        Required for clients configured for ledger service. Exclude entirely if
        not applicable to your integration.
      required:
        - api_key
        - user_id
        - entity_type
        - entity_id
      properties:
        api_key:
          type: string
          minLength: 1
          maxLength: 100
          description: API key associated with the ledger program.
          example: lk_live_abc123xyz
        user_id:
          type: string
          minLength: 1
          maxLength: 100
          description: User ID associated with the ledger program.
          example: usr_00456
        entity_type:
          type: string
          minLength: 1
          maxLength: 50
          enum:
            - program
            - business
            - user
          description: >
            Entity type for the ledger. Accepted values: `program`, `business`,
            `user`.
          example: program
        entity_id:
          type: string
          maxLength: 100
          nullable: true
          description: Entity ID associated with the ledger.
          example: ent_00789
    ProcessCheckResponse:
      type: object
      properties:
        status:
          type: integer
          description: >
            Numeric code describing the status of the API request. 100 =
            Success.
          example: 100
        client_message:
          type: string
          description: Text description associated with the status code.
          example: Success
        data:
          type: object
          properties:
            check_number:
              type: string
              description: >
                Check number assigned to this disbursement. Unique to this
                transaction.
              example: '100042'
            transaction_id:
              type: integer
              nullable: true
              description: >
                Always provided on success and in certain failure conditions.
                Unique transaction identifier. Log this value — Ingo Payment
                Services will request it for support interactions.
              example: 2361540
            customer_account_token:
              type: string
              description: Echo of value from request. Provided on success.
              example: 6218c726-3989-40ab-af84-fa6f4c932cb6
            estimated_posting_date:
              type: string
              description: Provided on success. Estimated posting date.
              example: 08/29/2020
            estimated_posting_time:
              type: string
              description: Provided on success. Estimated posting time narrative.
              example: Payment will post 7-10 Days
            participant_unique_id1:
              type: string
              description: >
                Always provided on success and in certain failure conditions.
                Echo of value provided on request.
              example: 35a792a5-39e6-46fa-add1-419a75d3aa9a
            participant_unique_id2:
              type: string
              nullable: true
              description: >
                Provided on success and in certain failure conditions if sent on
                original request. Echo of value provided on request.
              example: 2d4ebd46-616b-4212-bc54-1f7f68514e1a
            request_timestamp:
              type: integer
              format: int64
              description: Unix timestamp of the request.
              example: 1597862480
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          example: 700
        client_message:
          type: string
          example: Account not currently available for payment
        data:
          type: object
          properties:
            request_timestamp:
              type: integer
              format: int64
              example: 1597862480
  securitySchemes:
    HmacAuth:
      type: http
      scheme: hmac-sha512
      description: >-
        HMAC-SHA512 signed Authorization header. See the Authentication page for
        the complete signing guide.
security:
  - HmacAuth: []