Tổng quan Web SDK

Bahn Web SDK là một script chạy trên trình duyệt. Nó thu thập thông tin thanh toán bên trong các iframe do Bahn host và xác nhận thanh toán với Bahn API. Số thẻ, ngày hết hạn và CVC được nhập vào iframe, không bao giờ đi qua trang hay server của bạn.

Trang này giải thích các thành phần kết hợp với nhau thế nào và nên chọn luồng nào. Nếu muốn viết code ngay, xem Bắt đầu.

Cách hoạt động

Một tích hợp gồm ba phần:

Thành phần	Chạy ở	Vai trò
Backend của bạn	Server của bạn	Tạo PaymentIntent bằng API key bí mật và nhận webhook
Trang checkout + Bahn SDK	Trình duyệt của người mua	Tải SDK, mount các ô thanh toán và xác nhận thanh toán bằng `client_secret`
Iframe + API của Bahn	`bn.cake.vn` (production) / `bn.cakedigibank.tech` (sandbox)	Giữ dữ liệu thẻ, gọi Bahn API và chạy thử thách 3DS

sequenceDiagram
    participant Browser as Trang checkout + SDK
    participant Backend as Backend của bạn
    participant Bahn as Bahn API + iframe

    Browser->>Backend: Bắt đầu checkout
    Backend->>Bahn: Tạo PaymentIntent (API key)
    Bahn-->>Backend: PaymentIntent + client_secret
    Backend-->>Browser: client_secret
    Browser->>Bahn: confirmPayment({ client_secret }) qua iframe thẻ
    Bahn-->>Browser: payment_intent (+ payload 3DS nếu cần)
    Browser->>Bahn: mount3DS(...) — người mua hoàn tất thử thách
    Bahn-->>Backend: Webhook với trạng thái cuối cùng

Các loại key

Key	Dùng ở đâu	Có được công khai không?
Publishable key (`pk`)	Truyền vào `new Bahn({ pk })` trên trình duyệt	Có. Key này chỉ nhận diện tài khoản merchant của bạn.
API key	Header `Bn-Api-Key` trong các lệnh gọi server-to-server, kèm body được ký JWS	Không. Tuyệt đối không đặt vào code chạy trên trình duyệt.

Sandbox và production là hai môi trường riêng biệt. Hãy dùng key được cấp cho đúng môi trường bạn truyền vào new Bahn({ environment }). Key được cấp trong quá trình Onboarding.

Các đối tượng chính

Đối tượng	Ý nghĩa
PaymentIntent	Một lần thanh toán với số tiền xác định. Backend của bạn tạo nó.
`client_secret`	Chuỗi bí mật riêng của từng PaymentIntent, backend giao cho trình duyệt. SDK dùng nó để xác nhận đúng PaymentIntent đó và không làm được gì khác.
Confirmation token	Token dùng một lần đại diện cho thẻ người mua đã nhập. Tạo trên trình duyệt bằng `createConfirmationToken()` rồi gửi lên backend; backend dùng nó để tạo và xác nhận thanh toán.
SetupIntent	Lưu thẻ để dùng sau mà không trừ tiền. Xác nhận bằng `confirmCardSetup()`.
Phiên 3DS	Thử thách 3D Secure mà ngân hàng phát hành yêu cầu. SDK hiển thị nó qua `mount3DS()` hoặc `handleNextAction()`.

Chọn luồng

Bạn muốn…	Dùng	Hướng dẫn
Thanh toán thẻ với số tiền biết trước	Xác nhận trực tiếp. Backend tạo PaymentIntent, trình duyệt gọi `confirmPayment()`.	Xác nhận thanh toán
Chốt số tiền trên server sau khi biết thẻ (giảm giá, phụ phí, kiểm tra gian lận)	Luồng dựa trên token. Trình duyệt gọi `createConfirmationToken()`, backend tạo và xác nhận, rồi trình duyệt gọi `handleNextAction()`.	Luồng dựa trên token
Lưu thẻ mà không trừ tiền	SetupIntent với `confirmCardSetup()`	Lưu thẻ
Cho người mua quét mã QR ngân hàng	QR Napas với `mountPaymentQR()`	Thanh toán QR
Có nút ví thanh toán một chạm	Apple Pay / Google Pay với `mountApplePay()` / `mountGooglePay()`	Apple Pay, Google Pay

Tin webhook, không tin trình duyệt

Kết quả trên trình duyệt chỉ cho bạn biết nên hiển thị gì tiếp cho người mua. Backend chỉ nên đánh dấu đơn hàng đã thanh toán sau khi nhận được webhook với trạng thái cuối cùng. Xem Webhook.

Các bước tích hợp

Nhận key trong quá trình Onboarding.
Tải SDK và mount các ô nhập thẻ. Xem Bắt đầu.
Tạo PaymentIntent trên backend. Xem Xác thực để biết cách ký request.
Xác nhận thanh toán và xử lý 3DS trên trình duyệt. Xem Xác nhận thanh toán và Xác thực 3DS.
Xử lý webhook trên backend. Xem Webhook.
Kiểm thử trên sandbox với các thẻ test sandbox.
Go live theo Checklist go-live.

Tổng quan Web SDK ​

Cách hoạt động ​

Các loại key ​

Các đối tượng chính ​