Onboarding

Trước khi bạn có thể gọi Bahn REST API hoặc nhúng Web SDK, bạn cần hoàn tất một lần onboarding với đội ngũ Bahn. Onboarding tạo ra các thông tin xác thực (credentials) mà mọi bước sau đó phụ thuộc vào: tài khoản merchant của bạn, một bộ public key đã được trao đổi, một API key phía server, và một publishable key phía client.

Một số bước được xử lý thủ công bởi đội ngũ Bahn — việc tạo tài khoản merchant của bạn không phải là tự phục vụ (self-service).

Tổng quan

sequenceDiagram
    autonumber
    participant You as You (Merchant)
    participant Bahn as Bahn Team
    participant API as Bahn API

    Note over You, Bahn: Step 1 — Create merchant account (manual)
    You ->> Bahn: Request onboarding (business details)
    Bahn -->> You: Merchant account created

    Note over You, API: Step 2 — Exchange public keys
    You ->> You: Generate P-256 key pairs (sig + enc)
    You ->> Bahn: Submit your public keys (JWK)
    You ->> API: GET /api/public-keys
    API -->> You: Bahn's public keys (JWK)

    Note over You, Bahn: Step 3 — Receive API key
    Bahn -->> You: Bn-Api-Key (secret, server-side)

    Note over You, Bahn: Step 4 — Receive publishable key
    Bahn -->> You: Publishable key (pk_..., client-side)

Bước 1 — Tạo tài khoản merchant của bạn

Việc tạo tài khoản merchant là một bước thủ công. Liên hệ Bahn (account manager của bạn) để được onboarding. Đội ngũ Bahn sẽ khởi tạo tài khoản merchant của bạn để các thông tin xác thực ở các bước tiếp theo có thể được cấp.

Cung cấp các thông tin sau để Bahn có thể thiết lập tài khoản của bạn:

Thông tin tài khoản

Trường	Mô tả
`name`	Tên merchant / doanh nghiệp của bạn.
`mcc`	Merchant Category Code (ISO 18245) mô tả lĩnh vực kinh doanh của bạn.
`city_code`	Mã thành phố nơi đặt trụ sở doanh nghiệp của bạn.
`country_code`	Mã quốc gia nơi đặt trụ sở doanh nghiệp của bạn.
`settlement_currency`	Loại tiền tệ mà Bahn dùng để thanh toán (settle) tiền cho bạn.
`payment_currency`	Loại tiền tệ mà người mua của bạn bị tính phí.

Thông tin doanh nghiệp

Trường	Mô tả
`website_url`	Website doanh nghiệp của bạn.
`contact_person`	Tên người liên hệ chính.
`contact_phone`	Số điện thoại liên hệ.
`contact_email`	Địa chỉ email liên hệ.
`description`	Mô tả ngắn về doanh nghiệp của bạn.
`city`	Thành phố.
`country`	Quốc gia.
`address_line1`	Địa chỉ, dòng 1.
`address_line2`	Địa chỉ, dòng 2 (tùy chọn).

Cấu hình webhook

Trường	Mô tả
`webhook_url`	Endpoint HTTPS nơi Bahn gửi webhook event.
`webhook_enabled_events`	Các loại event bạn muốn được gửi đến webhook của mình.

INFO

Không có API tự phục vụ để tạo merchant — bước này được đội ngũ Bahn hoàn tất trong quá trình onboarding.

Bước 2 — Trao đổi public key

Bahn bảo mật payload của request và response bằng framework JOSE, vì vậy bạn và Bahn trao đổi public key với nhau một lần.

Tạo hai cặp khóa P-256 — một để ký request (JWS), một để giải mã response (JWE). Xem Tạo cặp khóa. Private key của bạn không bao giờ rời khỏi hệ thống của bạn.
Gửi public key của bạn cho Bahn — gửi cả hai public key ở định dạng JWK. Mỗi key phải bao gồm một kid và một use (sig hoặc enc). Xem Yêu cầu đối với public key.
Lấy public key của Bahn — lấy về các JWK key mà Bahn sử dụng để bạn có thể mã hóa dữ liệu thẻ nhạy cảm phía client và xác minh các response đã được ký:

http

GET /api/public-keys

Bước 3 — Nhận API key của bạn

Sau khi tài khoản merchant của bạn được tạo, Bahn sẽ cấp API key của bạn. Gửi nó trên mọi REST request bằng header Bn-Api-Key — xem API key.

WARNING

API key là một bí mật phía server. Không bao giờ để lộ nó trong trình duyệt, ứng dụng di động, hoặc repository công khai. Nếu bị lộ, liên hệ đội hỗ trợ Bahn để được cấp lại (rotate).

Bước 4 — Nhận publishable key của bạn

Để thu thập thông tin thẻ phía client với Web SDK, Bahn cấp một publishable key (pk_...). Không giống như API key, publishable key có thể được nhúng an toàn vào frontend của bạn. Sử dụng nó để khởi tạo SDK — xem Web SDK · Bắt đầu.

Tóm tắt thông tin xác thực

Thông tin xác thực	Loại	Dùng cho	Được cung cấp bởi
Cặp khóa ký & mã hóa	Khóa của bạn (private key giữ ở phía bạn)	Ký JWS / Giải mã JWE	Bạn — Bước 2
Public key của Bahn	Công khai (JWK)	Mã hóa dữ liệu thẻ, xác minh response	Bahn — `GET /api/public-keys`
API key (`Bn-Api-Key`)	Bí mật	Lệnh gọi REST phía server	Bahn — Bước 3
Publishable key (`pk_...`)	Công khai	Web SDK (phía client)	Bahn — Bước 4

Bước tiếp theo

Tạo cặp khóa — tạo và xuất cặp khóa ký và mã hóa P-256 của bạn.
Thực hiện request đầu tiên — ký và gửi một request end-to-end.
Web SDK · Bắt đầu — khởi tạo SDK với publishable key của bạn.

Onboarding ​

Tổng quan ​

Bước 1 — Tạo tài khoản merchant của bạn ​

Bước 2 — Trao đổi public key ​

Bước 3 — Nhận API key của bạn ​

Bước 4 — Nhận publishable key của bạn ​

Tóm tắt thông tin xác thực ​

Bước tiếp theo ​