Payabli Management API

openapi: 3.1.0
info:
  title: API reference Bill Management API
  version: 1.0.0
servers:
- url: https://api-sandbox.payabli.com/api
  description: Sandbox
- url: https://api.payabli.com/api
  description: Production
tags:
- name: Management
paths:
  /Management/verifyAccountDetails/{entry}:
    post:
      operationId: VerifyAccountDetails
      summary: Verify bank account details
      description: 'Verifies a bank account and returns detailed verification results from the verification network, including bank name, account status, and response codes. Unlike a pass/fail verification, this endpoint returns granular data to support decision-making and troubleshooting.


        When bank authentication is enabled for the paypoint''s organization, the endpoint performs an identity verification check on the account holder. Otherwise, it performs an account existence check. When bank authentication is enabled, the `accountHolderType` and `holderName` fields are required.


        Requires `inboundpayments_create` or `outboundpayments_create` permission.'
      tags:
      - Management
      parameters:
      - name: entry
        in: path
        description: The paypoint's entry name identifier.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).

          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyAccountDetailsResponse'
        '400':
          description: Bad request / invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayabliErrorBody'
        '401':
          description: Unauthorized request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayabliErrorBody'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayabliErrorBody'
        '503':
          description: Database connection error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayabliErrorBody'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyAccountDetailsRequest'
components:
  schemas:
    PayabliErrorBody:
      type: object
      properties:
        isSuccess:
          type: boolean
          description: Always `false` for error responses.
        responseCode:
          type: integer
          description: 'Code for the response. Learn more in

            [API Response Codes](/developers/api-reference/api-responses).

            '
        responseText:
          type: string
          description: Error text describing what went wrong.
        responseData:
          $ref: '#/components/schemas/PayabliErrorBodyResponseData'
          description: Object with detailed error context.
      required:
      - isSuccess
      - responseText
      description: 'Shape returned by every Payabli API error response. The `responseData`

        object carries human-readable error context.

        '
      title: PayabliErrorBody
    PayabliErrorBodyResponseData:
      type: object
      properties:
        explanation:
          type: string
          description: Human-readable explanation of what happened.
        todoAction:
          type: string
          description: Suggested resolution.
      description: Object with detailed error context.
      title: PayabliErrorBodyResponseData
    BankAccountVerificationDetailsResponse:
      type: object
      properties:
        aba:
          type: string
          description: The ABA routing number that was verified.
        accountNumber:
          type: string
          description: The account number that was verified.
        isValid:
          type: boolean
          description: Whether the bank account passed verification.
        errorMessage:
          type:
          - string
          - 'null'
          description: Error message if the verification request failed.
        verificationResponse:
          type: string
          description: Overall verification outcome. Possible values include `Pass`, `Verified`, `Declined`, `NoData`, `Bypassed`, and `Error`.
        responseCode:
          type: string
          description: Response code returned by the verification network.
        responseValue:
          type: string
          description: Response value associated with the verification outcome.
        responseDescription:
          type: string
          description: Human-readable description of the verification outcome.
        bankName:
          type:
          - string
          - 'null'
          description: Name of the bank associated with the routing number.
        reportedAccountType:
          type:
          - string
          - 'null'
          description: Account type as reported by the verification network, such as `Checking` or `Savings`.
        accountAddedDate:
          type:
          - string
          - 'null'
          description: Date the account was first seen by the verification network (ISO 8601 format).
        accountLastUpdatedDate:
          type:
          - string
          - 'null'
          description: Date the account record was last updated in the verification network (ISO 8601 format).
        accountClosedDate:
          type:
          - string
          - 'null'
          description: Date the account was closed, if applicable (ISO 8601 format).
      required:
      - isValid
      - errorMessage
      - bankName
      - reportedAccountType
      - accountAddedDate
      - accountLastUpdatedDate
      - accountClosedDate
      description: Detailed bank account verification results from the verification network.
      title: BankAccountVerificationDetailsResponse
    VerifyAccountDetailsRequest:
      type: object
      properties:
        routingNumber:
          type: string
          description: The bank routing number to verify.
        accountNumber:
          type: string
          description: The bank account number to verify.
        accountType:
          type: string
          description: The type of bank account, such as `Checking` or `Savings`.
        country:
          type: string
          description: The ISO country code for the bank account, such as `US`.
        accountHolderType:
          type: string
          description: The type of account holder. Accepted values are `personal` or `business`. Required when bank authentication is enabled for the paypoint's organization.
        holderName:
          type: string
          description: The name of the bank account holder. For personal accounts, provide the holder's full name (for example, `Jane Doe`); the value is split on the first space into first and last name. For business accounts, provide the legal business name. Required when bank authentication is enabled for the paypoint's organization.
      required:
      - routingNumber
      - accountNumber
      title: VerifyAccountDetailsRequest
    ResponseText:
      type: string
      description: 'Response text for operation: ''Success'' or ''Declined''.

        '
      title: ResponseText
    IsSuccess:
      type: boolean
      description: 'Boolean indicating whether the operation was successful. A `true` value

        indicates success. A `false` value indicates failure.

        '
      title: IsSuccess
    VerifyAccountDetailsResponse:
      type: object
      properties:
        isSuccess:
          $ref: '#/components/schemas/IsSuccess'
        responseText:
          $ref: '#/components/schemas/ResponseText'
        responseData:
          $ref: '#/components/schemas/BankAccountVerificationDetailsResponse'
      required:
      - responseText
      description: Response wrapper for the bank account verification details endpoint.
      title: VerifyAccountDetailsResponse
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication).

        '
    APIKeyAuth:
      type: apiKey
      in: header
      name: requestToken
      description: 'Long-lived API token sent in the `requestToken` header. See [API token authentication](/developers/api-tokens).

        '