Developers

Tiếng Việt

English

Tiếng Việt

English

Appearance

Môi trường ​

SDK kết nối đến các domain API và iframe khác nhau tùy theo tùy chọn environment.

Cấu hình ​

typescript
const bahn = new Bahn({
  pk: "pk_test_...",
  environment: "sandbox",   // hoặc "production"
});
Môi trườngTrường hợp sử dụng
"sandbox"Kiểm thử và phát triển. Sử dụng các domain .tech.
"production"Thanh toán thật. Sử dụng các domain .vn.

Ánh xạ domain ​

SDK phân giải môi trường thành các domain cụ thể tại thời điểm khởi tạo. Các domain này được hardcode — bạn không thể ghi đè chúng:

Thành phầnSandboxProduction
Domain iframehttps://bn.cakedigibank.tech/bn-sdk/v2/componentshttps://bn.cake.vn/bn-sdk/v2/components
Domain APIhttps://bn.cakedigibank.techhttps://bn.cake.vn

Script bundle (CDN): https://bn.cake.vn/bn-sdk/v<version>/index.js — chỉ có một host script duy nhất, được dùng cho cả hai môi trường. Tùy chọn environment bạn truyền vào new Bahn() mới là thứ kiểm soát domain iframe/API nào được sử dụng tại runtime, không phải URL script bạn tải.

Phiên bản & tính toàn vẹn của script bundle ​

Mỗi bản phát hành của Bahn Web SDK được publish tại đường dẫn riêng, gắn theo phiên bản SDK — ví dụ v2.4.0:

https://bn.cake.vn/bn-sdk/v2.4.0/index.js

Một file sẽ không bao giờ thay đổi sau khi đã được publish dưới một phiên bản nhất định, vì vậy hãy pin đúng phiên bản bạn đã kiểm thử thay vì dùng một alias có thể thay đổi. Mỗi bundle đều đi kèm một hash Subresource Integrity tại index.js.sha384:

https://bn.cake.vn/bn-sdk/v2.4.0/index.js.sha384

Sử dụng nó cùng với các thuộc tính integrity + crossorigin để trình duyệt xác minh file không bị thay đổi trong quá trình truyền tải:

html
<script
  src="https://bn.cake.vn/bn-sdk/v2.4.0/index.js"
  integrity="sha384-jBbonUZLgKU82F+X/ITqcmeInXYYwZYdmCDoPFX8wkWL9dCkeUHyi0Fs1EUnkeDS"
  crossorigin="anonymous"
></script>

Lưu ý: crossorigin="anonymous" khiến đây trở thành một request CORS — response phải bao gồm header Access-Control-Allow-Origin để trình duyệt cho phép script chạy. Hãy xác nhận điều này đã được bật trên domain lưu trữ trước khi phụ thuộc vào integrity trong môi trường production.

Cùng một domain iframe phục vụ:

  • Iframe nhập thẻ (card-number-iframe.html, expiry-iframe.html, cvc-iframe.html)
  • Iframe QR (qr-iframe.html)
  • Iframe 3DS (3ds.html)

Domain API phục vụ:

  • POST /bn/sdk/payment_intents/confirm
  • POST /bn/sdk/confirmation_token
  • Truy vấn và polling payment intent

Kiểu SDKEnvironment ​

typescript
type SDKEnvironment = "sandbox" | "production";

Sandbox vs Production ​

Sandbox ​

Sử dụng "sandbox" để phát triển và kiểm thử:

  • Tất cả lệnh gọi API đi đến môi trường sandbox
  • Không có thanh toán thật nào được xử lý
  • Dùng các thẻ test sandbox bên dưới
  • Các thử thách 3DS sử dụng ACS sandbox
typescript
const bahn = new Bahn({
  pk: "pk_test_abc123",
  environment: "sandbox",
});

Production ​

Sử dụng "production" cho thanh toán thật:

  • Tất cả lệnh gọi API đi đến môi trường production
  • Các thanh toán thật được xử lý
  • Các thử thách 3DS sử dụng ACS production
typescript
const bahn = new Bahn({
  pk: "pk_live_xyz789",
  environment: "production",
});

Thẻ test sandbox ​

Dùng các thẻ này với environment: "sandbox" và publishable key sandbox. Chúng bị từ chối ở production.

Thương hiệuSố thẻNgày hết hạnCVC
Visa4229 9899 9900 001212/31871
Mastercard5204 5001 3000 000512/35112

Việc một thanh toán sandbox qua 3DS không cần thử thách (frictionless), có thử thách (challenge) hay bị từ chối phụ thuộc vào số tiền, không phụ thuộc vào thẻ. Xem ngưỡng 3DS sandbox ở trang 3DS để kiểm thử cả ba kết quả.

Content Security Policy ​

Nếu trang checkout của bạn gửi header Content-Security-Policy, hãy cho phép các host Bahn của môi trường bạn dùng. Script SDK luôn được tải từ https://bn.cake.vn. Các iframe và API chạy trên host riêng của từng môi trường.

DirectiveSandboxProductionLý do
script-srchttps://bn.cake.vnhttps://bn.cake.vnBundle SDK
frame-srchttps://bn.cakedigibank.techhttps://bn.cake.vnCác iframe thẻ, QR, Apple Pay, Google Pay và 3DS
connect-srchttps://bn.cakedigibank.techhttps://bn.cake.vngetConfig(), bahn.applePay.* và lệnh cập nhật kết quả 3DS, do SDK gửi trực tiếp từ trang của bạn

Một policy production ví dụ:

http
Content-Security-Policy:
  script-src 'self' https://bn.cake.vn;
  frame-src https://bn.cake.vn;
  connect-src 'self' https://bn.cake.vn

Nếu bạn gọi bahn.isGooglePayAvailable(), SDK sẽ tải thêm https://pay.google.com/gp/p/js/pay.js của Google vào trang của bạn. Hãy thêm https://pay.google.com vào script-src, và làm theo hướng dẫn CSP của Google cho những gì pay.js cần thêm.

Dữ liệu thẻ không bao giờ đi qua trang của bạn, nên bạn không cần cho phép thêm origin nào khác của Bahn. Mọi thứ còn lại, như script Apple Pay, reCAPTCHA và trang thử thách 3DS, đều chạy bên trong các iframe của Bahn.

Trình duyệt được hỗ trợ ​

Các iframe thẻ, QR và 3DS được build cho các trình duyệt sau trở lên:

Trình duyệtPhiên bản tối thiểu
Chrome / Edge111
Firefox111
Safari (macOS)13
Safari (iOS / iPadOS)13

Developers

© 2026 Cake Digital Bank