openapi: 3.0.3
info:
  title: IngoPay API — Check Cancel
  description: >
    Submit a request to cancel (void) an existing check disbursement.


    The Check Cancel method is used to void a previously accepted check payment
    request. Unlike Check Stop, a successful cancel response confirms the check
    has been voided. The check must be in a routed or issued status to be
    eligible for cancellation.


    **Reason codes for Check Cancel — and their eligible transaction states:**

    | Code | Description | Eligible Status | |---|---|---| | `73` | Check Not
    Printed | Routed only | | `74` | Undelivered Check | Issued only | | `75` |
    Client Request | Issued only | | `76` | Internal Request | Issued only |


    Providing a reason code that does not match the check's current status
    returns an error. For example, using `73` (Check Not Printed) on an issued
    check will be rejected.


    > **Check Cancel is a SaaS-only endpoint.** Your participant account must be
    configured as a SaaS participant with check disbursement capability. Contact
    your Ingo integration manager to confirm your configuration.
  version: '1'
  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/checkcancel:
    post:
      summary: Cancel (void) a check disbursement
      description: >
        Submits a cancellation request for a previously issued or routed check
        disbursement. The check is located by exact match on `participant_id`,
        `check_number`, `amount`, and `participant_unique_id1`.


        The `reason_code` must match the check's current transaction status.
        `73` (Check Not Printed) is only valid for routed transactions. `74`,
        `75`, and `76` are only valid for issued transactions.
      operationId: checkCancel
      tags:
        - Check Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckCancelRequest'
            example:
              participant_id: '12345'
              check_number: '49379283'
              amount: 100.04
              reason_code: 73
              explanation: Check Not Printed
              participant_unique_id1: 2ac29937-1c52-4647-ba54-f1442ffae4d1
      responses:
        '200':
          description: Check cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckCancelResponse'
              example:
                status_code: 100
                client_message: Success
                data:
                  check_number: '49379283'
                  transaction_id: 2361543
                  request_timestamp: 1633470601
                  participant_unique_id1: 2ac29937-1c52-4647-ba54-f1442ffae4d1
                time: '0.7614'
        '400':
          description: Validation error or check not eligible for cancel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status_code: 722
                client_message: Check Invalid To Cancel
components:
  schemas:
    CheckCancelRequest:
      type: object
      required:
        - participant_id
        - check_number
        - amount
        - reason_code
        - explanation
        - participant_unique_id1
      properties:
        participant_id:
          type: string
          maxLength: 5
          description: Unique participant identifier assigned by Ingo.
          example: '12345'
        check_number:
          type: string
          description: >
            Check number assigned to the check disbursement transaction.
            Provided in the Process call response (`check_number` field).
          example: '49379283'
        amount:
          type: number
          format: float
          minimum: 0.01
          description: >
            Amount of the transaction. Must exactly match the original
            transaction amount.
          example: 100.04
        reason_code:
          type: integer
          enum:
            - 73
            - 74
            - 75
            - 76
          description: >
            Reason code for the check cancel request. Must match the check's
            current transaction status. 73 = Check Not Printed (routed
            transactions only). 74 = Undelivered Check (issued transactions
            only). 75 = Client Request (issued transactions only). 76 = Internal
            Request (issued transactions only).
          example: 73
        explanation:
          type: string
          minLength: 1
          maxLength: 150
          description: Brief explanation for the check cancel request.
          example: Check Not Printed
        participant_unique_id1:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            Participant assigned unique ID for the original check Process
            request. Must exactly match the original value.
          example: 2ac29937-1c52-4647-ba54-f1442ffae4d1
    CheckCancelResponse:
      type: object
      properties:
        status_code:
          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
          description: Information about identifiers associated with the transaction.
          properties:
            check_number:
              type: string
              description: >
                Check number assigned to the check disbursement transaction and
                provided in the Process call response.
              example: '49379283'
            transaction_id:
              type: integer
              description: Ingo assigned unique ID for the cancel reversal transaction.
              example: 2361543
            request_timestamp:
              type: integer
              format: int64
              description: Unix timestamp of the request.
              example: 1633470601
            participant_unique_id1:
              type: string
              description: Participant assigned unique ID for the original request.
              example: 2ac29937-1c52-4647-ba54-f1442ffae4d1
        time:
          type: string
          description: Time in seconds to complete the request.
          example: '0.7614'
    ErrorResponse:
      type: object
      properties:
        status_code:
          type: integer
          example: 722
        client_message:
          type: string
          example: Check Invalid To Cancel
  securitySchemes:
    HmacAuth:
      type: http
      scheme: hmac-sha512
      description: >-
        HMAC-SHA512 signed Authorization header. See the Authentication page for
        the complete signing guide.
security:
  - HmacAuth: []