openapi: 3.0.0
info:
  title: Bank Validation API
  description: >-
    Complete API collection for bank account validation services.


    ## Features

    - Validate bank account numbers and account holder names

    - Support for 130+ Indonesian banks (BCA, BRI, BNI, BSI, Mandiri, SeaBank, and many more)

    - Name masking for privacy protection

    - Real-time account verification

    - Get list of all available banks

    - Flexible bank code input (accepts both "mandiri" and "bank_mandiri" formats)


    ## Authentication

    All requests require an API key in the `x-api-co-id` header.


    ## Base URL

    ```
    https://use.api.co.id/validation
    ```


    ## Supported Banks

    We support 130+ Indonesian banks including:

    - **BCA** (Bank Central Asia) - `bca` or `bank_bca`

    - **BRI** (Bank Rakyat Indonesia) - `bri` or `bank_bri`

    - **BNI** (Bank Negara Indonesia) - `bni` or `bank_bni`

    - **BSI** (Bank Syariah Indonesia) - `bsi` or `bank_bsm`

    - **Mandiri** (Bank Mandiri) - `mandiri` or `bank_mandiri`

    - **SeaBank** (SeaBank Indonesia) - `seabank` or `bank_kesejahteraan_ekonomi`

    - And 120+ more banks

    Use the **Get Available Banks** endpoint to see the complete list of supported banks.


    ## Bank Code Format

    You can input bank codes in two formats:

    - **Short format**: `mandiri`, `bca`, `bri` (automatically mapped to full format)

    - **Full format**: `bank_mandiri`, `bank_bca`, `bank_bri` (used as-is)

    Both formats work the same way and will be processed correctly.


    ## Response Fields

    - **is_valid**: Boolean indicating if account validation passed

    - **score**: Float value (0.0 to 10.0) representing name match confidence

    - **name**: Masked account name showing first 3 chars + **** (only if valid, null if invalid)

    - **message**: Status message describing the validation result

    - **note**: Additional note (empty string if valid, "Name was not returned" if validation failed)


    ## Use Cases

    - Payment gateway account verification

    - E-wallet registration

    - Financial service onboarding

    - KYC (Know Your Customer) compliance

    - Account ownership verification

    - Fraud prevention
  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: Bank Validation
    description: Bank account validation endpoints for verifying account numbers and account holder names. Supports 130+ Indonesian banks with flexible bank code input.
paths:
  /validation/bank:
    get:
      tags:
        - Bank Validation
      summary: Validate Bank Account
      description: >-
        Validate a bank account number and account holder name.


        ### Example Request

        ```bash
        curl --location 'http://localhost:3003/validation/bank?bank_code=bank_bri&account_number=110601003647539&account_name=John%20Doe' \
        --header 'x-api-co-id: your-api-key'
        ```


        ### Query Parameters

        - `bank_code` (required): Bank code identifier
          - Can be short format: `mandiri`, `bca`, `bri`, `bni`, `bsi`, `seabank`
          - Or full format: `bank_mandiri`, `bank_bca`, `bank_bri`, `bank_bni`, `bank_bsm`, `bank_kesejahteraan_ekonomi`
          - Use `GET /validation/bank/available` to see all 130+ supported banks
        - `account_number` (required): Bank account number to validate
        - `account_name` (required): Account holder name to match against bank records


        ### Response

        Returns validation result with:

        - **is_valid**: Boolean indicating if validation passed

        - **score**: Name matching score (0.0 to 10.0, >= 7.0 is valid)

        - **name**: Masked account name showing first 3 chars + **** (only if valid, null if invalid)

        - **message**: Status message

        - **note**: Additional note (empty if valid, "Name was not returned on invalid validation" if failed)


        ### Validation Logic

        1. Validates bank account number and account holder name

        2. Returns match score (0.0 to 10.0) indicating validation confidence

        3. Score >= 7.0 indicates successful validation

        4. Valid names are masked for privacy (e.g., "Rif**** Eln****")
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          required: true
          example: '{{api_key}}'
        - name: bank_code
          in: query
          schema:
            type: string
          required: true
          description: 'Bank code - can be short format (mandiri, bca, bri) or full format (bank_mandiri, bank_bca, bank_bri). Use GET /validation/bank/available to see all supported banks.'
          example: bank_bri
        - name: account_number
          in: query
          schema:
            type: string
          required: true
          description: Bank account number
          example: '110601003647539'
        - name: account_name
          in: query
          schema:
            type: string
          required: true
          description: Account holder name to validate
          example: 'John Doe'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      is_valid:
                        type: boolean
                        description: Boolean indicating if account validation passed
                        example: true
                      score:
                        type: number
                        format: float
                        description: 'Name matching score (0.0 to 10.0, >= 7.0 is valid)'
                        example: 8.5
                      name:
                        type: string
                        nullable: true
                        description: 'Masked account name showing first 3 chars + **** (only if valid, null if invalid)'
                        example: 'Rif**** Eln****'
                      message:
                        type: string
                        description: Status message describing the validation result
                        example: 'Validation successful'
                      note:
                        type: string
                        description: 'Additional note (empty string if valid, "Name was not returned" if validation failed)'
                        example: ''
              examples:
                success:
                  summary: Success
                  value:
                    is_success: true
                    message: Success
                    data:
                      is_valid: true
                      score: 8.5
                      name: 'Rif**** Eln****'
                      message: 'Validation successful'
                      note: ''
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: false
                  message:
                    type: string
              examples:
                missingParameters:
                  summary: Error - Missing Parameters
                  value:
                    is_success: false
                    message: "Key: 'BankValidationRequest.BankCode' Error:Field validation for 'BankCode' failed on the 'required' tag"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: false
                  message:
                    type: string
              examples:
                missingApiKey:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: false
                  message:
                    type: string
              examples:
                rateLimitExceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
  /validation/bank/available:
    get:
      tags:
        - Bank Validation
      summary: Get Available Banks
      description: >-
        Get the complete list of all available banks supported by the validation API.


        ### Response

        Returns a list of all supported banks with:

        - **banks**: Array of bank objects
          - **bank_name**: Full name of the bank (e.g., "MANDIRI", "BCA", "BRI")
          - **bank_code**: Bank code to use in validation requests (e.g., "bank_mandiri", "bank_bca", "bank_bri")
        - **total**: Total number of supported banks (130+)


        ### Usage

        Use this endpoint to:

        - Discover all supported banks

        - Get the correct bank code for validation requests

        - Build dynamic bank selection dropdowns in your application


        ### Bank Code Format

        You can use either:

        - **Short format**: Remove `bank_` prefix (e.g., use `mandiri` instead of `bank_mandiri`)

        - **Full format**: Use the exact `bank_code` from the response

        Both formats work the same way in validation requests.
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          required: true
          example: '{{api_key}}'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      banks:
                        type: array
                        items:
                          type: object
                          properties:
                            bank_name:
                              type: string
                              example: MANDIRI
                            bank_code:
                              type: string
                              example: bank_mandiri
                      total:
                        type: integer
                        description: Total number of supported banks
                        example: 130
              examples:
                success:
                  summary: Success - Available Banks List
                  value:
                    is_success: true
                    message: Success
                    data:
                      banks:
                        - bank_name: MANDIRI
                          bank_code: bank_mandiri
                        - bank_name: BCA
                          bank_code: bank_bca
                        - bank_name: BRI
                          bank_code: bank_bri
                        - bank_name: BNI
                          bank_code: bank_bni
                        - bank_name: 'BSI (BANK SYARIAH INDONESIA)'
                          bank_code: bank_bsm
                        - bank_name: 'SEABANK/BANK BKE'
                          bank_code: bank_kesejahteraan_ekonomi
                      total: 130
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: false
                  message:
                    type: string
              examples:
                missingApiKey:
                  summary: Missing API Key
                  value:
                    is_success: false
                    message: 'Missing API key in x-api-co-id header'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_success:
                    type: boolean
                    example: false
                  message:
                    type: string
              examples:
                rateLimitExceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
