> ## 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 — BillPay

> Tokenize a biller account for BillPay push disbursements.



## OpenAPI

````yaml specs/ingopay-verify-billpay.yaml POST /gateway/verify--billpay
openapi: 3.0.3
info:
  title: IngoPay API — Verify BillPay
  description: >
    Verify support for customer bill payment account data and tokenize the
    account for use in a subsequent Process call.


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


    **`payee_id` is always required** and identifies the specific biller to
    which the payment will be directed. Obtain `payee_id` from the Biller
    Payments Search API prior to calling Verify.


    **Mutual exclusivity rules:**

    - Provide either `customer_account_token` **or** raw account fields
      (`account`, `recipient_first_name`, `recipient_last_name`,
      `recipient_address1`, `recipient_city`, `recipient_state`,
      `recipient_zip`) — never both.

    - When `customer_account_token` is provided, all raw account fields
      listed above are not required and should be omitted.
  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--billpay:
    post:
      tags:
        - Account Tokenization
      summary: Verify and tokenize a bill payment account
      description: >
        Validates a customer's bill payment account data and returns a
        `customer_account_token` for use in push (Process) requests.
        `account_type` must always be `BP` for this operation.
      operationId: verifyBillpay
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyBillpayRequest'
            example:
              participant_id: 12345
              payee_id: '123457'
              timestamp: 1587052132
              version: 11
              participant_unique_id1: f8f68709-8e5d-4c19-8ca0-2eaffef4ec57
              account: '12345678'
              recipient_first_name: Alex
              recipient_last_name: Rivera
              recipient_address1: 100 Innovation Way
              recipient_address2: Apt 2
              recipient_city: Anytown
              recipient_state: GA
              recipient_zip: '00000'
              recipient_phone: '1231231234'
              amount: 1010.5
              participant_unique_id2: 257b5bae-d52f-42e2-8f2c-0700d8d7a7a5
              account_type: BP
      responses:
        '200':
          description: Verification successful — token returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyBillpayResponse'
              example:
                status: 100
                client_message: Success
                data:
                  customer_account_token: a74eacf4-32e8-4081-b69c-565a89dd6cf1
                  last_4: '5678'
                  request_timestamp: 1587052142
                  issuers:
                    - payee_id: '123457'
                      payee_name: First Service Middle Jersey
                      payee_address: PO Box 5555
                      payee_city: Secaucus
                      payee_state: NJ
                      payee_zip: 07032-0310
                      credit_info:
                        min: '5.00'
                        max: '2000.00'
                        card_type: NA
                        estimated_posting_time: Payment will post 04/17/2026
                        estimated_posting_date: 04/17/2026
                      issuing_network: NA
                      credit_enabled: 1
                      debit_enabled: 0
                  participant_unique_id1: f8f68709-8e5d-4c19-8ca0-2eaffef4ec57
                  participant_unique_id2: 257b5bae-d52f-42e2-8f2c-0700d8d7a7a5
                  count: 1
                time: '1.6832'
        '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: 1587052142
components:
  schemas:
    VerifyBillpayRequest:
      type: object
      required:
        - participant_id
        - payee_id
        - timestamp
        - version
        - participant_unique_id1
        - account_type
      description: >
        Provide either `customer_account_token` or the raw account fields
        (`account`, `recipient_first_name`, `recipient_last_name`,
        `recipient_address1`, `recipient_city`, `recipient_state`,
        `recipient_zip`) — never both.
      properties:
        participant_id:
          type: integer
          description: Unique participant identifier assigned by Ingo.
          example: 12345
        payee_id:
          type: string
          maxLength: 40
          description: >
            Ingo assigned payee ID for the selected biller. Obtain from the
            Biller Payments Search API prior to calling Verify.
          example: '123457'
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp of the request.
          example: 1587052132
        version:
          type: integer
          description: API version of the request. Current version is 11.
          example: 11
        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: f8f68709-8e5d-4c19-8ca0-2eaffef4ec57
        customer_account_token:
          type: string
          minLength: 1
          maxLength: 255
          nullable: true
          description: >
            Alternative to raw account data when the account was previously
            tokenized. If provided, the following fields are not required and
            should be omitted: `account`, `recipient_first_name`,
            `recipient_last_name`, `recipient_address1`, `recipient_city`,
            `recipient_state`, `recipient_zip`.
          example: a74eacf4-32e8-4081-b69c-565a89dd6cf1
        account:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            Customer bill payment account number. Required unless a valid
            `customer_account_token` is provided.
          example: '12345678'
        recipient_first_name:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            Customer first name. Required unless a valid
            `customer_account_token` is provided.
          example: Johnny
        recipient_last_name:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            Customer last name. Required unless a valid `customer_account_token`
            is provided.
          example: Rockets
        recipient_business_name:
          type: string
          maxLength: 150
          nullable: true
          description: Optional recipient business name.
          example: Rockets LLC
        recipient_address1:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            Customer billing address line 1. Required unless a valid
            `customer_account_token` is provided.
          example: 123 Main St
        recipient_city:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            Customer billing city. Required unless a valid
            `customer_account_token` is provided.
          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: >
            Customer billing state (standard US postal abbreviation). Required
            unless a valid `customer_account_token` is provided.
          example: GA
        recipient_zip:
          type: string
          maxLength: 10
          pattern: ^[0-9]{5}(?:-[0-9]{4})?$
          description: >
            Customer billing zip code. 5-digit zip or zip+4 in xxxxx-xxxx
            format. Required unless a valid `customer_account_token` is
            provided.
          example: '30313'
        recipient_address2:
          type: string
          maxLength: 255
          nullable: true
          description: Customer billing address line 2.
          example: Apt 2
        recipient_email:
          type: string
          maxLength: 255
          nullable: true
          description: Optional recipient email address.
          example: johnny.rockets@example.com
        recipient_phone:
          type: string
          maxLength: 10
          nullable: true
          description: 10-digit recipient phone number.
          example: '1231231234'
        participant_unique_id2:
          type: string
          maxLength: 255
          nullable: true
          description: >
            Optional second participant assigned ID to be associated with
            `customer_account_token` creation. Should be carried forward to
            future process requests for tracking purposes. Must not contain NPI
            data.
          example: 257b5bae-d52f-42e2-8f2c-0700d8d7a7a5
        amount:
          type: number
          format: float
          minimum: 0.01
          nullable: true
          description: >
            Dollar amount of disbursement. Max value determined by participant
            velocity limits.
          example: 1010.5
        account_type:
          type: string
          enum:
            - BP
          minLength: 1
          description: Always `BP` for bill payment transactions.
          example: BP
    VerifyBillpayResponse:
      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: a74eacf4-32e8-4081-b69c-565a89dd6cf1
            last_4:
              type: string
              description: The last 4 digits of the account number.
              example: '5678'
            request_timestamp:
              type: integer
              format: int64
              description: Unix timestamp of the request.
              example: 1587052142
            issuers:
              type: array
              description: Information about the issuer (biller).
              items:
                type: object
                properties:
                  payee_id:
                    type: string
                    description: The Ingo assigned ID for the payee.
                    example: '123457'
                  payee_name:
                    type: string
                    description: Name of the payee (biller).
                    example: First Service Middle Jersey
                  payee_address:
                    type: string
                    nullable: true
                    description: Payee address.
                    example: PO Box 5555
                  payee_city:
                    type: string
                    nullable: true
                    description: Payee city.
                    example: Secaucus
                  payee_state:
                    type: string
                    nullable: true
                    description: Payee state.
                    example: NJ
                  payee_zip:
                    type: string
                    nullable: true
                    description: Payee zip code.
                    example: 07032-0310
                  credit_info:
                    type: object
                    nullable: true
                    description: >
                      Information regarding limits for push (credit)
                      transactions. Returned if participant is enabled for push
                      processing.
                    properties:
                      min:
                        type: string
                        description: Minimum amount accepted for a push transaction.
                        example: '5.00'
                      max:
                        type: string
                        description: Maximum amount accepted for a push transaction.
                        example: '2000.00'
                      card_type:
                        type: string
                        description: Account type identifier.
                        example: NA
                      estimated_posting_time:
                        type: string
                        description: Estimated posting time narrative.
                        example: Payment will post 04/17/2026
                      estimated_posting_date:
                        type: string
                        description: Estimated posting date.
                        example: 04/17/2026
                  issuing_network:
                    type: string
                    description: Issuing network identifier.
                    example: NA
                  credit_enabled:
                    type: integer
                    enum:
                      - 0
                      - 1
                    description: >
                      Whether the account is enabled for push (credit)
                      transactions. 1 = Enabled, 0 = Not enabled.
                    example: 1
                  debit_enabled:
                    type: integer
                    enum:
                      - 0
                      - 1
                    description: >
                      Whether the account is enabled for pull (debit)
                      transactions. 1 = Enabled, 0 = Not enabled.
                    example: 0
            participant_unique_id1:
              type: string
              description: Echo of participant assigned ID for the verify request.
              example: f8f68709-8e5d-4c19-8ca0-2eaffef4ec57
            participant_unique_id2:
              type: string
              nullable: true
              description: >
                Echo of optional second participant assigned ID for the verify
                request.
              example: 257b5bae-d52f-42e2-8f2c-0700d8d7a7a5
            count:
              type: integer
              description: Number of issuers returned.
              example: 1
        time:
          type: string
          description: Time in seconds to complete the request.
          example: '1.6832'
    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: 1587052142
  securitySchemes:
    HmacAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        HMAC-SHA512 signed Authorization header. See the Authentication page for
        the complete signing guide.

````