openapi: 3.0.3
info:
  title: VietQR Core Gateway API
  description: |
    VietQR Core Enterprise PaaS / SaaS Gateway API.
    Zero-dependency on 3rd-party links, 100% self-hosted, supporting EMVCo standard,
    QuickLink URL generation, Deeplink Hub, and Bank Catalog.
  version: 1.0.0
  contact:
    name: VietQR Core SDK Team
    url: https://github.com/hitechcloud-vietnam/vietqr-core-sdk
servers:
  - url: http://localhost:8080
    description: Local Gateway Instance
  - url: https://{domain}
    description: Custom Domain Production SaaS Instance
    variables:
      domain:
        default: qr.yourdomain.com
        description: Your custom configured domain

paths:
  /health:
    get:
      summary: Health check
      description: Returns service health status and current domain configuration.
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                    example: 1.0.0
                  domain:
                    type: string
                    example: qr.yourdomain.com

  /image/{slug}.png:
    get:
      summary: Generate VietQR image via QuickLink URL
      description: |
        Generates a VietQR PNG image directly via URL.
        Format of slug: `{bin}-{account}-{template}` (e.g. `970436-1234567890-compact2.png` or `VCB-1234567890-compact2.png`).
        Available templates: `compact`, `compact2`, `qr_only`, `standee`, `sepay`.
      parameters:
        - name: slug
          in: path
          required: true
          description: Slug pattern `bin-account-template`
          schema:
            type: string
            example: "970436-1234567890-compact2"
        - name: amount
          in: query
          required: false
          description: Transfer amount in VND
          schema:
            type: integer
            example: 100000
        - name: addInfo
          in: query
          required: false
          description: Transfer description / memo (max 50 chars)
          schema:
            type: string
            example: "DH12345 thanh toan"
        - name: accountName
          in: query
          required: false
          description: Beneficiary account name (uppercase ASCII)
          schema:
            type: string
            example: "NGUYEN VAN A"
      responses:
        '200':
          description: VietQR PNG image
          content:
            image/png:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid bank or account format

  /qr/pay:
    get:
      summary: Interactive Deeplink Payment Hub
      description: |
        Renders a responsive, mobile-optimized HTML pay hub with local bank logos and
        one-click deep links opening 35+ banking apps directly on iOS/Android devices.
      parameters:
        - name: bin
          in: query
          required: true
          description: Bank BIN code or short name
          schema:
            type: string
            example: "970436"
        - name: acc
          in: query
          required: true
          description: Beneficiary account number
          schema:
            type: string
            example: "1234567890"
        - name: amount
          in: query
          required: false
          description: Transfer amount in VND
          schema:
            type: integer
            example: 50000
        - name: desc
          in: query
          required: false
          description: Transfer note
          schema:
            type: string
            example: "Thanh toan hoa don"
        - name: name
          in: query
          required: false
          description: Beneficiary name
          schema:
            type: string
            example: "NGUYEN VAN A"
      responses:
        '200':
          description: HTML Web Pay Hub
          content:
            text/html:
              schema:
                type: string

  /api/v1/generate:
    post:
      summary: Generate VietQR payload and image
      description: Generates an EMVCo QR code string, Base64 PNG, self-hosted QuickLink, and Deeplinks.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - bank
                - account
              properties:
                bank:
                  type: string
                  description: Bank BIN (e.g. "970436") or code (e.g. "VCB")
                  example: "970436"
                account:
                  type: string
                  description: Account number
                  example: "1234567890"
                amount:
                  type: integer
                  description: Amount in VND (optional)
                  example: 100000
                memo:
                  type: string
                  description: Transfer memo / description (optional)
                  example: "Thanh toan don hang #100"
                account_name:
                  type: string
                  description: Account holder name (optional)
                  example: "NGUYEN VAN A"
                template:
                  type: string
                  enum: [compact, compact2, qr_only, standee, sepay]
                  default: compact2
                return_base64:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Generation successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  qr_data:
                    type: string
                    description: EMVCo QR TLV payload
                    example: "00020101021238540010A00000072701240006970436011012345678900208QRIBFTTA530370454061000005802VN62250821Thanh toan don hang 1006304C92E"
                  quicklink_url:
                    type: string
                    description: Self-hosted image link using custom domain
                    example: "https://qr.yourdomain.com/image/970436-1234567890-compact2.png?amount=100000&addInfo=Thanh+toan+don+hang+100"
                  deeplink_url:
                    type: string
                    description: Self-hosted Deeplink Hub URL
                    example: "https://qr.yourdomain.com/qr/pay?bin=970436&acc=1234567890&amount=100000"
                  qr_base64:
                    type: string
                    nullable: true
                    description: Base64 data URI of the rendered PNG image

  /api/v1/parse:
    post:
      summary: Parse and validate EMVCo VietQR payload
      description: Decodes an EMVCo string and extracts bank BIN, account number, amount, memo, and validates CRC16.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - qr_data
              properties:
                qr_data:
                  type: string
                  example: "00020101021238540010A00000072701240006970436011012345678900208QRIBFTTA530370454061000005802VN62250821Thanh toan don hang 1006304C92E"
      responses:
        '200':
          description: Parse result
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid_crc:
                    type: boolean
                  bin:
                    type: string
                  account_number:
                    type: string
                  amount:
                    type: integer
                  memo:
                    type: string
                  account_name:
                    type: string
                  service_code:
                    type: string
                  bank_info:
                    type: object

  /api/v1/banks:
    get:
      summary: List all supported Vietnamese banks
      description: Returns the complete bank catalog with BIN codes, short names, full names, and local asset icon URLs.
      responses:
        '200':
          description: Bank list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    bin:
                      type: string
                      example: "970436"
                    code:
                      type: string
                      example: "VCB"
                    name:
                      type: string
                      example: "Vietcombank"
                    short_name:
                      type: string
                      example: "Vietcombank"
                    logo_url:
                      type: string
                      example: "https://qr.yourdomain.com/assets/banks/VCB.png"

  /api/v1/deeplinks:
    get:
      summary: Get Deeplinks for banking apps
      description: Returns direct URL schemes for 35+ Vietnamese banking mobile applications.
      parameters:
        - name: bin
          in: query
          required: true
          schema:
            type: string
            example: "970436"
        - name: acc
          in: query
          required: true
          schema:
            type: string
            example: "1234567890"
        - name: amount
          in: query
          required: false
          schema:
            type: integer
            example: 100000
        - name: desc
          in: query
          required: false
          schema:
            type: string
            example: "DH12345"
      responses:
        '200':
          description: Deeplink list
          content:
            application/json:
              schema:
                type: object
                properties:
                  web_hub_url:
                    type: string
                  apps:
                    type: array
                    items:
                      type: object
                      properties:
                        bank_code:
                          type: string
                        app_name:
                          type: string
                        scheme_url:
                          type: string
                        icon_url:
                          type: string