> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ingopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify — Check by Mail

> Tokenize a recipient address for check by mail disbursements.



## OpenAPI

````yaml specs/ingopay-verify-check.yaml POST /gateway/verify--check
openapi: 3.0.3
info:
  title: IngoPay API — Verify Check by Mail
  description: >
    Verify support for customer check by mail account data and tokenize the
    account for use in a subsequent Process call.


    The Verify method validates and tokenizes the customer's check payment
    information. The returned `customer_account_token` is used in place of raw
    account data on all future Process requests for the same account.


    **`recipient_is_beneficiary` controls the mailing structure:**

    - `1` — The recipient is the beneficiary. The check is made out to and
      mailed to the beneficiary's name and address. The `recipient` object
      is not required and will be auto-populated from `beneficiary` fields.

    - `0` — The recipient is not the beneficiary. The check is made out to
      the beneficiary but mailed to a separate recipient address. Both
      `recipient` and `beneficiary` objects are required.


    **`beneficiary` is always required.** It contains the account identifier and
    the person or entity associated with the payment. All information provided
    is included in the remittance data printed and sent with the check.


    **`customer_account_token` mutual exclusivity:** When provided, the
    `beneficiary_account` and all `beneficiary` identification fields are not
    required.
  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
security:
  - HmacAuth: []
paths:
  /gateway/verify--check:
    post:
      tags:
        - Account Tokenization
      summary: Verify and tokenize a check by mail account
      description: >
        Validates customer check payment information and returns a
        `customer_account_token` for use in push (Process) requests.
        `account_type` must always be `CK` for this operation.
      operationId: verifyCheck
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyCheckRequest'
            examples:
              recipient_is_beneficiary:
                summary: Recipient is the beneficiary (recipient_is_beneficiary = 1)
                value:
                  participant_id: 12345
                  account_type: CK
                  recipient_is_beneficiary: 1
                  recipient:
                    recipient_line1: Ace Ventura
                    recipient_address1: 100 Innovation Way
                    recipient_address2: Apt 3
                    recipient_city: Anytown
                    recipient_state: GA
                    recipient_zip: '00000'
                    recipient_phone: '5555550100'
                  beneficiary:
                    beneficiary_account: '3000000038'
                    beneficiary_first_name: Alex
                    beneficiary_last_name: Rivera
                    beneficiary_address1: 100 Innovation Way
                    beneficiary_address2: ''
                    beneficiary_city: Anytown
                    beneficiary_state: GA
                    beneficiary_zip: '00000'
                    beneficiary_phone: '5555550100'
                  participant_unique_id1: 35a792a5-39e6-46fa-add1-419a75d3aa9a
                  participant_unique_id2: 2d4ebd46-616b-4212-bc54-1f7f68514e1a
                  timestamp: 1597862420
                  version: 11
              recipient_not_beneficiary:
                summary: >-
                  Recipient is not the beneficiary (recipient_is_beneficiary =
                  0)
                value:
                  participant_id: 12345
                  account_type: CK
                  recipient_is_beneficiary: 0
                  recipient:
                    recipient_line1: Elmer Fudd
                    recipient_address1: 100 Innovation Way
                    recipient_address2: Apt 2
                    recipient_city: Anytown
                    recipient_state: GA
                    recipient_zip: '00000'
                    recipient_phone: '5555550100'
                  beneficiary:
                    beneficiary_account: '3000000038'
                    beneficiary_first_name: Alex
                    beneficiary_last_name: Rivera
                    beneficiary_address1: 100 Innovation Way
                    beneficiary_address2: ''
                    beneficiary_city: Anytown
                    beneficiary_state: GA
                    beneficiary_zip: '00000'
                    beneficiary_phone: '5555550100'
                  participant_unique_id1: 35a792a5-39e6-46fa-add1-419a75d3aa9a
                  participant_unique_id2: 2d4ebd46-616b-4212-bc54-1f7f68514e1a
                  timestamp: 1597862420
                  version: 11
      responses:
        '200':
          description: Verification successful — token returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyCheckResponse'
              example:
                status: 100
                client_message: Success
                data:
                  customer_account_token: 6218c726-3989-40ab-af84-fa6f4c932cb6
                  last_4: '0038'
                  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: 1597867738
                time: '1.4295'
        '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: 1597867738
components:
  schemas:
    VerifyCheckRequest:
      type: object
      required:
        - participant_id
        - account_type
        - recipient
        - recipient_is_beneficiary
        - beneficiary
        - participant_unique_id1
        - timestamp
        - version
      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 transactions.
          example: CK
        recipient:
          type: object
          description: >
            Information about the recipient (payee) of the check — used for the
            pay-to line and mailing address. Required when
            `recipient_is_beneficiary` = 0. When `recipient_is_beneficiary` = 1,
            this object is auto-populated from `beneficiary` fields and may be
            omitted.
          required:
            - recipient_line1
            - recipient_address1
            - recipient_city
            - recipient_state
            - recipient_zip
          properties:
            recipient_line1:
              type: string
              minLength: 1
              maxLength: 75
              description: |
                Recipient / Pay To line 1 for the check and the mailing.
              example: Ace Ventura
            recipient_line2:
              type: string
              maxLength: 75
              nullable: true
              description: >
                Optional recipient / Pay To line 2 for the check and the
                mailing.
              example: c/o Pet Detective Agency
            recipient_address1:
              type: string
              minLength: 1
              maxLength: 40
              description: Remittance address line 1 for the mailing.
              example: 123 Main St.
            recipient_address2:
              type: string
              maxLength: 40
              nullable: true
              description: Optional remittance address line 2 for the mailing.
              example: Apt 3
            recipient_city:
              type: string
              minLength: 1
              maxLength: 25
              description: Remittance city for the mailing.
              example: Atlanta
            recipient_state:
              type: string
              minLength: 2
              maxLength: 2
              pattern: >-
                ^(?:A[LKSZRAEP]|C[AOT]|D[EC]|F[LM]|G[AU]|HI|I[ADLN]|K[SY]|LA|M[ADEHINOPST]|N[CDEHJMVY]|O[HKR]|P[ARW]|RI|S[CD]|T[NX]|UT|V[AIT]|W[AIVY])$
              description: >
                Remittance state for the mailing (standard US postal
                abbreviation).
              example: GA
            recipient_zip:
              type: string
              maxLength: 10
              pattern: ^[0-9]{5}(?:-[0-9]{4})?$
              description: >
                Remittance zip for the mailing. 5-digit zip or zip+4 in
                xxxxx-xxxx format.
              example: '30033'
            recipient_phone:
              type: string
              maxLength: 25
              nullable: true
              description: Recipient phone number.
              example: '5551234567'
        recipient_is_beneficiary:
          type: integer
          enum:
            - 0
            - 1
          description: >
            Flag indicating whether the recipient is the beneficiary. 1 =
            Recipient is the beneficiary (default). 0 = Recipient is not the
            beneficiary — a separate `recipient` mailing address must be
            provided.
          example: 1
        beneficiary:
          type: object
          description: >
            Information about the beneficiary associated with the payment. Only
            persistent data should be provided — data that can be used again for
            payments on the same account. All information provided is included
            in the remittance data printed and sent with the check. When
            `recipient_is_beneficiary` = 1, this information is also used for
            the pay-to line and mailing address.
          required:
            - beneficiary_account
            - beneficiary_first_name
            - beneficiary_last_name
            - beneficiary_address1
            - beneficiary_city
            - beneficiary_state
            - beneficiary_zip
          properties:
            beneficiary_account:
              type: string
              minLength: 1
              maxLength: 30
              description: >
                Account number or other identifier used to ensure the payment is
                applied to the correct beneficiary account. Should be a value
                that can be used on repeat or subsequent payments with the same
                generated `customer_account_token`.
              example: '3000000038'
            beneficiary_first_name:
              type: string
              minLength: 1
              maxLength: 30
              description: First name of person associated with the beneficiary account.
              example: Ace
            beneficiary_last_name:
              type: string
              minLength: 1
              maxLength: 30
              description: Last name of person associated with the beneficiary account.
              example: Ventura
            beneficiary_company:
              type: string
              maxLength: 75
              nullable: true
              description: >
                Optional company name of business associated with the
                beneficiary account.
              example: null
            beneficiary_address1:
              type: string
              minLength: 1
              maxLength: 40
              description: Beneficiary address line 1.
              example: 123 Main St.
            beneficiary_address2:
              type: string
              maxLength: 40
              nullable: true
              description: Optional beneficiary address line 2.
              example: Apt 3
            beneficiary_city:
              type: string
              minLength: 1
              maxLength: 25
              description: Beneficiary city.
              example: Atlanta
            beneficiary_state:
              type: string
              minLength: 2
              maxLength: 2
              pattern: >-
                ^(?:A[LKSZRAEP]|C[AOT]|D[EC]|F[LM]|G[AU]|HI|I[ADLN]|K[SY]|LA|M[ADEHINOPST]|N[CDEHJMVY]|O[HKR]|P[ARW]|RI|S[CD]|T[NX]|UT|V[AIT]|W[AIVY])$
              description: |
                Beneficiary state (standard US postal abbreviation).
              example: GA
            beneficiary_zip:
              type: string
              minLength: 1
              maxLength: 10
              pattern: ^[0-9]{5}(?:-[0-9]{4})?$
              description: |
                Beneficiary zip. 5-digit zip or zip+4 in xxxxx-xxxx format.
              example: '30033'
            beneficiary_phone:
              type: string
              maxLength: 25
              nullable: true
              description: Phone number associated with the beneficiary.
              example: '5551234567'
            beneficiary_email:
              type: string
              maxLength: 60
              nullable: true
              description: Email address associated with the beneficiary.
              example: ace.ventura@example.com
            customer_account_token:
              type: string
              minLength: 1
              maxLength: 255
              nullable: false
              description: >
                Alternative to raw beneficiary data when the account was
                previously tokenized. If provided, `beneficiary_account` and
                beneficiary identification fields are not required.
              example: 6218c726-3989-40ab-af84-fa6f4c932cb6
        participant_unique_id1:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            Participant assigned ID to be associated with
            `customer_account_token` creation. Should correlate to participant
            assigned values affiliated with future process requests for tracking
            purposes (e.g. CustomerID or AccountID). Must not contain NPI data.
          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
        participant_unique_id2:
          type: string
          maxLength: 255
          nullable: true
          description: >
            Optional second participant assigned ID. Should be carried forward
            to future process requests for tracking purposes. Must not contain
            NPI data.
          example: 2d4ebd46-616b-4212-bc54-1f7f68514e1a
        store_id:
          type: string
          maxLength: 255
          nullable: true
          description: |
            Client assigned store ID. Required for Retail client participants.
          example: STORE-001
        terminal_id:
          type: string
          maxLength: 255
          nullable: true
          description: >
            Client assigned terminal ID. Required for Retail client
            participants.
          example: TERM-042
        clerk_id:
          type: string
          maxLength: 255
          nullable: true
          description: |
            Client assigned clerk ID. Required for Retail client participants.
          example: CLK-007
    VerifyCheckResponse:
      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:
            customer_account_token:
              type: string
              description: >
                GUID — unique value generated based upon account and recipient
                data. Use this token in all subsequent Process requests for this
                account.
              example: 6218c726-3989-40ab-af84-fa6f4c932cb6
            last_4:
              type: string
              description: The last 4 digits of the `beneficiary_account` value.
              example: '0038'
            estimated_posting_date:
              type: string
              description: Estimated posting date of the payment.
              example: 08/29/2020
            estimated_posting_time:
              type: string
              description: Estimated posting time narrative.
              example: Payment will post 7-10 Days
            participant_unique_id1:
              type: string
              description: Echo of participant assigned ID for the verify request.
              example: 35a792a5-39e6-46fa-add1-419a75d3aa9a
            participant_unique_id2:
              type: string
              nullable: true
              description: >
                Echo of optional second participant assigned ID for the verify
                request.
              example: 2d4ebd46-616b-4212-bc54-1f7f68514e1a
            request_timestamp:
              type: integer
              format: int64
              description: Unix timestamp of the request.
              example: 1597867738
        time:
          type: string
          description: Time in seconds to complete the request.
          example: '1.4295'
    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: 1597867738
  securitySchemes:
    HmacAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        HMAC-SHA512 signed Authorization header. See the Authentication page for
        the complete signing guide.

````