Tạo phiên liên kết

API này cho phép máy chủ của đối tác (Backend) khởi tạo một phiên liên kết tài khoản ngân hàng (Bank Link Session) trên hệ thống Tingee và nhận về một URL SDK bảo mật.

POST

URLhttps://open-api.tingee.vn/v1/create-bank-link-session

Tạo một phiên liên kết tài khoản ngân hàng để lấy URL SDK hiển thị ở client.

1. Request Headers

Header	Kiểu	Bắt buộc	Mô tả
Content-Type	string	✓	Định dạng dữ liệu. Bắt buộc: application/json
x-client-id	string	✓	Client ID được Tingee cấp cho đối tác.
x-request-timestamp	string	✓	Thời gian gửi request (format: yyyyMMddHHmmssSSS, ví dụ: 20260701153045999).
x-signature	string	✓	Chữ ký HMAC-SHA512 xác thực tính toàn vẹn của dữ liệu request. Chi tiết xem tại Cách sinh chữ ký.

---

2. Request Body (JSON)

Thuộc tính	Kiểu dữ liệu	Bắt buộc	Mô tả
type	string	✕	Loại session. Giá trị: bank-link hoặc bank-config. Mặc định của đối tác là bank-link. Nếu cần mở màn cấu hình, truyền bank-config.
shopId	number	✕	ID cửa hàng cần liên kết tài khoản ngân hàng sau khi hoàn tất.
allowedBanks	array[string]	✕	Danh sách mã ngân hàng được hiển thị trong SDK (ví dụ: ["BIDV", "VCB", "ACB"]). Nếu không truyền, hệ thống hiển thị toàn bộ ngân hàng được hỗ trợ.
bankName	string	✕	Chỉ định mã một ngân hàng duy nhất để tự động khóa luồng và chuyển khách hàng vào thẳng giao diện liên kết của ngân hàng đó.
redirectUrl	string	✕	URL của bạn để chuyển tiếp trình duyệt của khách hàng sau khi hoàn tất liên kết trên SDK di động hoặc web.
merchantId	number	✕	ID Merchant. Chỉ bắt buộc và được truyền khi sử dụng tài khoản Master Merchant để tạo session cho một Merchant con.

Ví dụ Request Body:

{
  "shopId": 123,
  "type": "bank-link",
  "allowedBanks": ["BIDV", "VCB", "ACB"],
  "redirectUrl": "https://merchant.example.vn/bank-link/callback"
}

---

3. Response Dữ Liệu

Tingee OpenAPI sẽ trả về kết quả dưới dạng JSON:

Thuộc tính	Kiểu dữ liệu	Mô tả
code	string	Mã trạng thái kết quả. 00 biểu thị khởi tạo thành công.
message	string	Thông báo mô tả trạng thái phản hồi.
data	string	Đường dẫn URL SDK liên kết ngân hàng hoàn chỉnh chứa token bảo mật.

Ví dụ Response Thành công:

{
  "code": "00",
  "message": "Success",
  "data": "https://uat-bank-link.tingee.vn?token=eyJtZXJjaGFudElkIjoxMDAxfQ&s=7d5b6e..."
}

Ví dụ Response Lỗi:

{
  "code": "97",
  "message": "Invalid signature",
  "data": null
}

Danh sách mã lỗi nghiệp vụ:

Mã lỗi	Ý nghĩa	Hướng xử lý
90	Sai định dạng timestamp	Đảm bảo đúng định dạng yyyyMMddHHmmssSSS.
91	Request quá hạn	Đồng bộ lại thời gian máy chủ của bạn với múi giờ UTC+7.
92	Sai credentials	Kiểm tra lại x-client-id hoặc cấu hình Merchant.
97	Sai chữ ký	Kiểm tra lại secretToken và thuật toán sinh signature.

---

4. Ví dụ Backend (Node.js)

Dưới đây là mã nguồn minh họa cách gọi API tạo session liên kết từ máy chủ của bạn:

// timestamp và signature được sinh theo hướng dẫn tại mục "Bắt đầu ngay"
export async function createBankLinkSession(timestamp, signature) {
  const body = {
    shopId: 123,
    type: 'bank-link',
    redirectUrl: 'https://merchant.example.vn/bank-link/callback'
  };

  const response = await fetch(`${process.env.TINGEE_OPEN_API_URL}/v1/create-bank-link-session`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-client-id': process.env.TINGEE_CLIENT_ID,
      'x-request-timestamp': timestamp,
      'x-signature': signature
    },
    body: JSON.stringify(body)
  });

  const result = await response.json();
  if (result.code !== '00') {
    throw new Error(`[${result.code}] ${result.message}`);
  }

  // data chính là URL SDK hoàn chỉnh dùng ở Client
  return {
    url: result.data
  };
}