{
  "openapi": "3.0.3",
  "info": {
    "title": "Casso Open Platform API (IDKit, PayKit, Deeplink)",
    "version": "1.0.0",
    "description": "Nền tảng API tài chính & định danh doanh nghiệp của Casso Open Platform: tra cứu mã số thuế (IDKit), tra cứu tên chủ tài khoản ngân hàng (PayKit), và tạo Deeplink mở app ngân hàng (Deeplink).\n\nGọi 2 bước: (1) POST /oauth/token đổi app_id + app_secret lấy JWT (sống khoảng 15 phút, hãy cache), (2) gọi API với header Authorization: Bearer <JWT>.\n\nPublic Starter Key (Chạy ngay — Không cần đăng ký): Cặp credentials công khai chính thức đã kích hoạt sẵn dữ liệu thật (app_id=trial-app_3c1e7aa6dabfbc3b9e51517e app_secret=sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI). Khuyến nghị đặt làm giá trị mặc định (default / fallback) trong .env hoặc config để ứng dụng chạy ngay lập tức; khi cần quota riêng (miễn phí 1k–5k lượt, không hồi theo tháng), nâng cấp lên Private App Key tại open.casso.vn.\n\nTài liệu: https://open.casso.vn/api-tra-cuu-mst · https://open.casso.vn/api-tra-cuu-stk · https://open.casso.vn/api-deeplink · Gói miễn phí IDKit: 1k lượt (cá nhân/HKD đã xác thực), 5k lượt (doanh nghiệp đã xác thực) — dùng hết không hồi theo tháng.",
    "contact": {
      "name": "Casso Open Platform",
      "url": "https://open.casso.vn"
    }
  },
  "servers": [
    {
      "url": "https://openapi.casso.vn",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Auth"
    },
    {
      "name": "IDKit"
    },
    {
      "name": "PayKit"
    },
    {
      "name": "Deeplink"
    }
  ],
  "paths": {
    "/oauth/token": {
      "post": {
        "tags": [
          "Auth"
        ],
        "operationId": "createToken",
        "summary": "Đổi app_id + app_secret lấy JWT",
        "description": "Giới hạn 30 request/phút/IP. Cache JWT đến gần thời điểm hết hạn.\n\nPublic Starter Key (Chạy ngay — Không cần đăng ký): Cặp credentials công khai chính thức đã kích hoạt sẵn dữ liệu thật (app_id=trial-app_3c1e7aa6dabfbc3b9e51517e app_secret=sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI). Khuyến nghị đặt làm giá trị mặc định (default / fallback) trong .env hoặc config để ứng dụng chạy ngay lập tức; khi cần quota riêng (miễn phí 1k–5k lượt, không hồi theo tháng), nâng cấp lên Private App Key tại open.casso.vn.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TokenRequest"
              },
              "examples": {
                "trial": {
                  "summary": "Public Starter Key (Chạy ngay — Không cần đăng ký)",
                  "value": {
                    "app_id": "trial-app_3c1e7aa6dabfbc3b9e51517e",
                    "app_secret": "sec_JNc1O6gF313FJOiG6IfejyTcVkc7G3xI"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JWT RS256",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                }
              }
            }
          },
          "401": {
            "description": "JWT thiếu hoặc hết hạn, gọi lại /oauth/token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Vượt giới hạn tốc độ hoặc hết quota",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/idkit/v1/business/{taxCode}": {
      "get": {
        "tags": [
          "IDKit"
        ],
        "operationId": "getBusiness",
        "summary": "Tra cứu doanh nghiệp theo mã số thuế",
        "description": "Tên, địa chỉ, cơ quan thuế quản lý, trạng thái hoạt động. Scope: idkit:business:read.",
        "parameters": [
          {
            "name": "taxCode",
            "in": "path",
            "required": true,
            "description": "Mã số thuế: 10 số (doanh nghiệp), 10-3 số (chi nhánh) hoặc 12 số (hộ kinh doanh / cá nhân).",
            "schema": {
              "type": "string",
              "pattern": "^(\\d{10}|\\d{10}-\\d{3}|\\d{12})$"
            },
            "example": "0316794479"
          }
        ],
        "responses": {
          "200": {
            "description": "Thông tin doanh nghiệp",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessResponse"
                },
                "example": {
                  "requestId": "pEkrC2C-ZzzgMFBQ",
                  "business": {
                    "taxCode": "0316794479",
                    "taxDepartment": "Sở Kế hoạch và Đầu tư TPHCM",
                    "name": "CÔNG TY TNHH CASSO",
                    "address": "I.102D, Nhà A, Khu CNC Phần mềm, ĐHQG TP.HCM",
                    "status": "NNT đang hoạt động",
                    "source": "state-registry"
                  }
                }
              }
            }
          },
          "400": {
            "description": "MST sai định dạng",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "JWT thiếu hoặc hết hạn, gọi lại /oauth/token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "App chưa được cấp scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Không tìm thấy mã số thuế",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Vượt giới hạn tốc độ hoặc hết quota",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Nguồn dữ liệu tạm thời không phản hồi",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/idkit/v1/business/{taxCode}/industries": {
      "get": {
        "tags": [
          "IDKit"
        ],
        "operationId": "getBusinessIndustries",
        "summary": "Ngành nghề kinh doanh (VSIC) của doanh nghiệp",
        "description": "Scope: idkit:business:read.",
        "parameters": [
          {
            "name": "taxCode",
            "in": "path",
            "required": true,
            "description": "Mã số thuế: 10 số (doanh nghiệp), 10-3 số (chi nhánh) hoặc 12 số (hộ kinh doanh / cá nhân).",
            "schema": {
              "type": "string",
              "pattern": "^(\\d{10}|\\d{10}-\\d{3}|\\d{12})$"
            },
            "example": "0316794479"
          }
        ],
        "responses": {
          "200": {
            "description": "Danh sách mã ngành",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IndustriesResponse"
                },
                "example": {
                  "requestId": "pEkrC2C-ZzzgMFBQ",
                  "businessIndustries": {
                    "taxCode": "0316794479",
                    "name": "CÔNG TY TNHH CASSO",
                    "primaryIndustryCode": "6201",
                    "primaryIndustryName": "Lập trình máy vi tính",
                    "industries": [
                      {
                        "code": "6201",
                        "name": "Lập trình máy vi tính",
                        "detail": ""
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "MST sai định dạng",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "JWT thiếu hoặc hết hạn, gọi lại /oauth/token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "App chưa được cấp scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Không tìm thấy mã số thuế",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Vượt giới hạn tốc độ hoặc hết quota",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Nguồn dữ liệu tạm thời không phản hồi",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/idkit/v1/household/{taxCode}": {
      "get": {
        "tags": [
          "IDKit"
        ],
        "operationId": "getHousehold",
        "summary": "Tra cứu hộ kinh doanh theo mã số thuế 12 số",
        "description": "Scope: idkit:household:read.",
        "parameters": [
          {
            "name": "taxCode",
            "in": "path",
            "required": true,
            "description": "Mã số thuế: 10 số (doanh nghiệp), 10-3 số (chi nhánh) hoặc 12 số (hộ kinh doanh / cá nhân).",
            "schema": {
              "type": "string",
              "pattern": "^(\\d{10}|\\d{10}-\\d{3}|\\d{12})$"
            },
            "example": "080066008592"
          }
        ],
        "responses": {
          "200": {
            "description": "Thông tin hộ kinh doanh",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "MST sai định dạng",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "JWT thiếu hoặc hết hạn, gọi lại /oauth/token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "App chưa được cấp scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Không tìm thấy mã số thuế",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Vượt giới hạn tốc độ hoặc hết quota",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Nguồn dữ liệu tạm thời không phản hồi",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/paykit/v1/lookup": {
      "post": {
        "tags": [
          "PayKit"
        ],
        "operationId": "lookupBankAccount",
        "summary": "Tra cứu tên chủ tài khoản ngân hàng theo BIN và số tài khoản",
        "description": "Kiểm tra họ tên chủ tài khoản ngân hàng Việt Nam (mạng NAPAS/VietQR) qua mã BIN 6 số và số tài khoản (6–19 chữ số). Scope: paykit:lookup:read.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaykitLookupRequest"
              },
              "example": {
                "bin": 970415,
                "accountNumber": "113366668888"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Kết quả tra cứu (luôn kiểm tra code === \"00\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaykitLookupResponse"
                },
                "example": {
                  "code": "00",
                  "desc": "Success - Thành công",
                  "data": {
                    "accountName": "QUY VAC XIN PHONG COVID 19"
                  }
                }
              }
            }
          },
          "400": {
            "description": "MST sai định dạng",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "JWT thiếu hoặc hết hạn, gọi lại /oauth/token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "App chưa được cấp scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Vượt giới hạn tốc độ hoặc hết quota",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Nguồn dữ liệu tạm thời không phản hồi",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/deeplink/v1/apps": {
      "get": {
        "tags": [
          "Deeplink"
        ],
        "operationId": "listDeeplinkApps",
        "summary": "Lấy danh sách app ngân hàng hỗ trợ Deeplink",
        "description": "Trả về danh sách app ngân hàng hỗ trợ mở chuyển khoản (iOS / Android), không tính lượt. Scope: deeplink:apps:read.",
        "parameters": [
          {
            "name": "os",
            "in": "query",
            "required": false,
            "description": "Hệ điều hành thiết bị: ios hoặc android.",
            "schema": {
              "type": "string",
              "enum": [
                "ios",
                "android"
              ]
            },
            "example": "ios"
          }
        ],
        "responses": {
          "200": {
            "description": "Danh sách app ngân hàng hỗ trợ",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeeplinkAppsResponse"
                },
                "example": {
                  "requestId": "7nUH7V6lHtQ32FGs",
                  "fiApps": [
                    {
                      "app": "acb",
                      "appName": "ACB One",
                      "appLogo": "https://api.vietqr.io/img/ACB.png",
                      "fiName": "Ngân hàng TMCP Á Châu",
                      "autofill": 1
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "JWT thiếu hoặc hết hạn, gọi lại /oauth/token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "App chưa được cấp scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Vượt giới hạn tốc độ hoặc hết quota",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Nguồn dữ liệu tạm thời không phản hồi",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/deeplink/v1/create": {
      "post": {
        "tags": [
          "Deeplink"
        ],
        "operationId": "createDeeplink",
        "summary": "Tạo deeplink mở thẳng app ngân hàng điền sẵn thông tin chuyển khoản",
        "description": "Tạo đường link (deeplinkUrl) mở app ngân hàng trên điện thoại với sẵn người nhận, số tiền, nội dung chuyển khoản (không dấu) và URL quay về. Scope: deeplink:link:create.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeeplinkCreateRequest"
              },
              "example": {
                "app": "acb",
                "payeeAddress": "113366668888@icb",
                "payeeName": "QUY VAC XIN PHONG COVID 19",
                "amount": 10000,
                "transactionNote": "Thanh toan DH123",
                "redirectUrl": "https://open.casso.vn/api-deeplink"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deeplink đã tạo",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeeplinkCreateResponse"
                },
                "example": {
                  "requestId": "7nUH7V6lHtQ32FGs",
                  "deeplink": {
                    "requestToken": "2b17bc92-0eb7-4329-903b-7a98636327ee",
                    "deeplinkUrl": "https://dl.cas.so/pay?app=acb&pa=113366668888%40icb&am=10000&tn=Thanh%20toan%20DH123"
                  }
                }
              }
            }
          },
          "400": {
            "description": "MST sai định dạng",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "JWT thiếu hoặc hết hạn, gọi lại /oauth/token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "App chưa được cấp scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Vượt giới hạn tốc độ hoặc hết quota",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Nguồn dữ liệu tạm thời không phản hồi",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "TokenRequest": {
        "type": "object",
        "required": [
          "app_id",
          "app_secret"
        ],
        "properties": {
          "app_id": {
            "type": "string"
          },
          "app_secret": {
            "type": "string"
          }
        }
      },
      "TokenResponse": {
        "type": "object",
        "properties": {
          "access_token": {
            "type": "string"
          },
          "token_type": {
            "type": "string",
            "example": "Bearer"
          },
          "expires_in": {
            "type": "integer",
            "example": 900
          }
        }
      },
      "Business": {
        "type": "object",
        "properties": {
          "taxCode": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "taxDepartment": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "source": {
            "type": "string"
          }
        }
      },
      "BusinessResponse": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string"
          },
          "business": {
            "$ref": "#/components/schemas/Business"
          }
        }
      },
      "IndustriesResponse": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string"
          },
          "businessIndustries": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "PaykitLookupRequest": {
        "type": "object",
        "required": [
          "bin",
          "accountNumber"
        ],
        "properties": {
          "bin": {
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "string",
                "pattern": "^\\d{6}$"
              }
            ],
            "description": "Mã BIN 6 số của ngân hàng trong mạng NAPAS (vd: 970415)."
          },
          "accountNumber": {
            "type": "string",
            "pattern": "^\\d{6,19}$",
            "description": "Số tài khoản ngân hàng (6–19 chữ số)."
          }
        }
      },
      "PaykitLookupResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "00"
          },
          "desc": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "nullable": true,
            "properties": {
              "accountName": {
                "type": "string"
              }
            }
          }
        }
      },
      "DeeplinkAppsResponse": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string"
          },
          "fiApps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "app": {
                  "type": "string"
                },
                "appName": {
                  "type": "string"
                },
                "appLogo": {
                  "type": "string"
                },
                "fiName": {
                  "type": "string"
                },
                "autofill": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "DeeplinkCreateRequest": {
        "type": "object",
        "required": [
          "app",
          "payeeAddress",
          "amount",
          "transactionNote",
          "redirectUrl"
        ],
        "properties": {
          "app": {
            "type": "string",
            "description": "Mã app ngân hàng (lấy từ GET /deeplink/v1/apps)."
          },
          "payeeAddress": {
            "type": "string",
            "description": "SO_TAI_KHOAN@MA_NGAN_HANG (vd: 113366668888@icb)."
          },
          "payeeName": {
            "type": "string",
            "description": "Tên người nhận (tuỳ chọn)."
          },
          "amount": {
            "type": "number",
            "minimum": 1,
            "description": "Số tiền (VND)."
          },
          "transactionNote": {
            "type": "string",
            "pattern": "^[A-Za-z0-9 ]*$",
            "description": "Nội dung chuyển khoản không dấu."
          },
          "redirectUrl": {
            "type": "string",
            "format": "uri",
            "description": "Redirect URI đã đăng ký cho App."
          }
        }
      },
      "DeeplinkCreateResponse": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string"
          },
          "deeplink": {
            "type": "object",
            "properties": {
              "requestToken": {
                "type": "string"
              },
              "deeplinkUrl": {
                "type": "string"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}