Giới thiệu

Mỗi lệnh gọi đến Bahn REST API phải đáp ứng ba yêu cầu: một API key hợp lệ, một request body đã được ký (hoặc mã hóa), và các header idempotency. Trang này giải thích từng yêu cầu và những gì bạn cần thiết lập trước khi thực hiện lệnh gọi đầu tiên.

Base URL

Gửi mọi request đến base URL tương ứng với môi trường mục tiêu của bạn:

Môi trường	Base URL	Trường hợp sử dụng
Sandbox	`https://bn.cakedigibank.tech`	Kiểm thử và phát triển — không có giao dịch thật.
Production	`https://bn.cake.vn`	Thanh toán thật.

Trước khi bắt đầu

Trong quá trình onboarding, hoàn tất các bước sau một lần duy nhất:

Tạo hai cặp khóa P-256 — một để ký request, một để giải mã response. Xem Tạo khóa.
Chia sẻ cả hai public key với Bahn — private key của bạn không bao giờ rời khỏi hệ thống của bạn.
Nhận API key từ Bahn.

API key

Đính kèm API key của bạn trên mọi request bằng header Bn-Api-Key:

http

Bn-Api-Key: <your-api-key>

INFO

API key của bạn được cấp một lần trong quá trình onboarding. Hãy giữ bảo mật và không bao giờ chia sẻ nó. Nếu bị lộ, liên hệ đội hỗ trợ Bahn để được cấp lại (rotate).

Ký request (JOSE)

Đối với các request có body, Bahn sử dụng framework JOSE để xác minh tính toàn vẹn và bảo mật của dữ liệu trong quá trình truyền.

Header Bn-Jose-Method là bắt buộc trên mọi request có body. Nó cho Bahn biết cách diễn giải payload:

Bn-Jose-Method	Mô tả
`jws`	Body được ký bằng private signing key của bạn. Bahn xác minh bằng public key đã đăng ký của bạn.
`jwe`	Body được mã hóa bằng public key của Bahn. Chỉ Bahn mới có thể giải mã.
`jws+jwe`	Body được ký trước (JWS), sau đó token kết quả được mã hóa (JWE). Cung cấp cả tính xác thực và tính bảo mật.

Quan trọng

Hiện tại, tất cả các lệnh gọi API từ merchant phải sử dụng Bn-Jose-Method: jws. Xem JWS để biết toàn bộ quy trình ký.

Content type

Bahn chấp nhận hai định dạng serialize cho body đã ký:

application/jose — Compact Serialization

Token JWS dưới dạng chuỗi phân tách bằng dấu chấm được gửi trực tiếp làm request body:

<base64url(header)>.<base64url(payload)>.<base64url(signature)>

application/jose+json — JSON Serialization

JWS General JSON Serialization dưới dạng đối tượng JSON:

json

{
  "payload": "<base64url(payload)>",
  "signatures": [
    {
      "protected": "<base64url(header)>",
      "signature": "<base64url(signature)>"
    }
  ]
}

Khi sử dụng application/jose+json với nhiều chữ ký, Bahn sử dụng mục đầu tiên để xác minh.

Các tham số header JOSE bắt buộc

JWS

Tham số	Mô tả
`alg`	Thuật toán ký (ví dụ `ES256`).
`kid`	Key ID của public signing key đã đăng ký của merchant.
`url`	Đường dẫn endpoint của request. Ràng buộc token với endpoint này và ngăn chặn tấn công replay.
`iat`	Timestamp thời điểm phát hành (Unix seconds). Cho phép Bahn từ chối các token đã cũ.

JWE

Tham số	Mô tả
`alg`	Thuật toán quản lý khóa dùng để bọc (wrap) content encryption key.
`enc`	Thuật toán mã hóa nội dung.
`kid`	Key ID của public encryption key của Bahn được sử dụng.

Lưu ý

Đối với jws+jwe, các header JWS áp dụng cho bước ký bên trong và các header JWE áp dụng cho bước mã hóa bên ngoài.

Yêu cầu đối với public key

Khi gửi public key của bạn cho Bahn, mỗi key phải:

Ở định dạng JWK (JSON Web Key).
Bao gồm trường kid (Key ID) — Bahn sử dụng trường này để tra cứu key chính xác.
Bao gồm trường use được đặt là sig (ký) hoặc enc (mã hóa).

Idempotency

WARNING

Idempotency hiện chỉ được bật trên một số API nhất định. Trước khi phụ thuộc vào Bn-Idempotency-Key cho một endpoint cụ thể, hãy liên hệ Bahn để xác nhận nó đã được bật cho tài khoản của bạn.

Hai header idempotency là bắt buộc để ngăn chặn các thao tác trùng lặp và cho phép retry an toàn:

Header	Bắt buộc trên	Mô tả
`Bn-Request-Id`	Mọi request	Một định danh duy nhất cho mỗi lần thử request riêng lẻ. Tạo một giá trị mới cho mỗi lần thử, kể cả khi retry.
`Bn-Idempotency-Key`	Mọi request không phải GET	Một key ổn định đại diện cho thao tác logic. Nếu một request với key này đã thành công trước đó, Bahn sẽ trả về response đã lưu (cached) thay vì thực hiện lại thao tác.

http

Bn-Request-Id: 7f3e9c1a-4b2d-4e8f-a1c0-123456789abc
Bn-Idempotency-Key: order_001_create_payment

TIP

Sử dụng một giá trị xác định (deterministic) cho Bn-Idempotency-Key — chẳng hạn như order ID nội bộ của bạn — để các lần retry do lỗi mạng hoặc timeout luôn mang cùng một key và không bao giờ dẫn đến giao dịch bị tính tiền trùng lặp.

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 với ví dụ bằng Go.
JSON Web Signature — tìm hiểu sâu về quy trình ký JWS.

Giới thiệu ​

Base URL ​

Trước khi bắt đầu ​

API key ​

Ký request (JOSE) ​

Content type ​

Các tham số header JOSE bắt buộc ​

Yêu cầu đối với public key ​

Idempotency ​

Bước tiếp theo ​