{
  "openapi": "3.1.0",
  "info": {
    "title": "Blaaiz Platform API - Resolve Bank Account",
    "version": "1.0.0",
    "description": "Verify and resolve bank account details"
  },
  "tags": [
    {
      "name": "Bank"
    }
  ],
  "servers": [
    {
      "url": "https://api-prod.blaaiz.com"
    },
    {
      "url": "https://api-dev.blaaiz.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "oauth2ClientCredentials": {
        "type": "oauth2",
        "description": "Use your OAuth client credentials to obtain a short-lived Bearer token from POST /oauth/token.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "/oauth/token",
            "scopes": {
              "bank:read": "Read bank and bank account data."
            }
          }
        }
      }
    },
    "schemas": {
      "AccountLookupRequest": {
        "type": "object",
        "description": "This endpoint allows you to verify the validity of a bank account by providing the account number and the associated bank ID. It returns information about the account, such as the account holder's name, to ensure accuracy before initiating transactions. \n We advise using this to confirm recipient details for payments, transfers, or any transaction involving a bank account. \n **Example Use Cases:** \n - Validate a recipient's bank account details during payment setup. \n - Ensure accurate data entry before processing a transaction. \n - Provide real-time verification for user onboarding or payout processes.",
        "properties": {
          "account_number": {
            "type": "string",
            "description": "Bank account number to verify"
          },
          "bank_id": {
            "type": "string",
            "description": "Bank ID (see List Banks endpoint)"
          }
        },
        "required": [
          "account_number",
          "bank_id"
        ]
      },
      "AccountLookupResponse": {
        "type": "object",
        "properties": {
          "account_name": {
            "type": "string",
            "description": "Name of the account holder"
          }
        },
        "required": [
          "account_name"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      }
    }
  },
  "paths": {
    "/api/external/bank/account-lookup": {
      "post": {
        "summary": "Resolve bank account",
        "description": "Verify the validity of a bank account by providing account number and bank_id. Required scope: `bank:read`.",
        "tags": [
          "Bank"
        ],
        "security": [
          {
            "oauth2ClientCredentials": [
              "bank:read"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountLookupRequest"
              },
              "example": {
                "account_number": "0123456789",
                "bank_id": "044"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account resolved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountLookupResponse"
                },
                "example": {
                  "message": "Account resolved successfully",
                  "account_name": "John Doe"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Invalid account number or bank code"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Invalid or missing access token"
                }
              }
            }
          }
        }
      }
    }
  }
}