Dùng với AI agent

Skill tích hợp

Skill là một file SKILL.md theo định dạng Agent Skills: agent tự đọc khi bạn nhờ làm việc liên quan tới thanh toán chuyển khoản. File gồm luồng tích hợp, các endpoint và trường dữ liệu, cách dựng VietQR, verify webhook và chống xử lý trùng, kèm code mẫu Node.js, PHP, Python. Nội dung khớp với tài liệu này.

Tải SKILL.md

Cài skill cho Claude Code

Chạy ở thư mục gốc của dự án (chỉ dự án này), hoặc cài cho mọi dự án trên máy:

mkdir -p .claude/skills/bankopenapi
curl -fsSL https://bankopenapi.com/skills/bankopenapi/SKILL.md -o .claude/skills/bankopenapi/SKILL.md

mkdir -p ~/.claude/skills/bankopenapi
curl -fsSL https://bankopenapi.com/skills/bankopenapi/SKILL.md -o ~/.claude/skills/bankopenapi/SKILL.md

Mở lại Claude Code rồi nhờ việc như bình thường, ví dụ:

• Tích hợp thanh toán chuyển khoản BankOpenAPI vào trang checkout: tạo yêu cầu thanh toán khi đặt đơn, hiện mã VietQR, nhận webhook để chuyển đơn sang đã thanh toán.
• Viết endpoint /webhooks/bankopenapi cho app Next.js này, verify chữ ký và chống xử lý trùng bằng Prisma.

Agent khác:

• Cursor, Codex, GitHub Copilot, Claude Code và các agent khác: chạynpx skills add https://bankopenapi.com (cần Node.js 22.20 trở lên), rồi chọn agent cần cài skill.
• claude.ai: tạo thư mục bankopenapi chứa SKILL.md, nén thành file zip rồi tải lên ở mục Skills trong phần cài đặt.
• Cursor, GitHub Copilot, agent đọc AGENTS.md: lưu file vào repo (ví dụ docs/bankopenapi.md) và thêm một dòng vào file quy tắc của agent: "Khi làm thanh toán chuyển khoản, đọc docs/bankopenapi.md".

MCP server Mới

MCP (Model Context Protocol) là chuẩn để AI agent gọi công cụ bên ngoài. MCP server của BankOpenAPI cho agent tạo yêu cầu thanh toán, xem trạng thái, xem giao dịch ngay trong cuộc trò chuyện, dùng API key của bạn.

Kết nối MCP

Tạo một API key riêng cho agent ở trang API key (đặt tên "MCP"), lưu vào biến môi trường BANKOPENAPI_API_KEY, rồi thêm MCP server:

claude mcp add --transport http bankopenapi https://app.bankopenapi.com/api/mcp \
  --header "Authorization: Bearer $BANKOPENAPI_API_KEY"

Muốn chia sẻ cấu hình với cả team qua file .mcp.json trong repo, dùng biến môi trường thay cho khóa thật (mỗi người tự đặt BANKOPENAPI_API_KEY trên máy mình):

{
  "mcpServers": {
    "bankopenapi": {
      "type": "http",
      "url": "https://app.bankopenapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${BANKOPENAPI_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "bankopenapi": {
      "url": "https://app.bankopenapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BANKOPENAPI_API_KEY}"
      }
    }
  }
}

Client MCP khác: khai báo MCP server dạng HTTP với URL ở trên và header Authorization. Client chỉ hỗ trợ OAuth cho MCP server từ xa thì chưa kết nối được.

Danh sách tool

Ví dụ câu nhờ agent khi đã kết nối:

• Tạo yêu cầu thanh toán 250.000đ cho đơn DH2041 rồi gửi tôi link thanh toán.
• Hôm nay có bao nhiêu khoản tiền vào chưa khớp đơn nào?

Tham số và kết quả của tool giống API v1 (số tiền là số nguyên VND, cùng trạng thái, cùng mã lỗi). Xem API yêu cầu thanh toán.

An toàn

• MCP chạy theo API key: key boa_test_… chỉ thấy dữ liệu sandbox, key boa_live_… làm việc với dữ liệu thật (yêu cầu agent tạo là yêu cầu thật, hủy là hủy thật). Cho agent dùng key sandbox khi thử, và để agent hỏi bạn trước khi chạy tool ghi (create_payment_request, cancel_payment_request).
• Không dán API key vào khung chat hay commit vào file cấu hình; dùng biến môi trường như ví dụ trên.
• Dùng khóa riêng cho agent để thu hồi được ngay mà không ảnh hưởng hệ thống production.
• Skill và MCP không cho agent quyền chuyển tiền đi: BankOpenAPI chỉ nhận thông tin tiền vào.