Create a link session

This API lets the partner's server (backend) create a bank account link session (Bank Link Session) on the Tingee system and receive a secure SDK URL.

POST

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

Create a bank account link session to get the SDK URL to display on the client.

1. Request Headers

Header	Type	Required	Description
Content-Type	string	✓	Data format. Required: application/json
x-client-id	string	✓	Client ID issued to the partner by Tingee.
x-request-timestamp	string	✓	Time the request is sent (format: yyyyMMddHHmmssSSS, e.g. 20260701153045999).
x-signature	string	✓	HMAC-SHA512 signature that verifies the integrity of the request data. See How to generate the signature for details.

---

2. Request Body (JSON)

Property	Data type	Required	Description
type	string	✕	Session type. Values: bank-link or bank-config. The partner default is bank-link. To open the configuration screen, pass bank-config.
shopId	number	✕	ID of the shop to link the bank account to once linking is complete.
allowedBanks	array[string]	✕	List of bank codes shown in the SDK (e.g. ["BIDV", "VCB", "ACB"]). If omitted, the system shows all supported banks. Values are bank codes (code in Supported banks), not BINs.
disallowedBanks	array[string]	✕	List of bank codes to hide from the SDK (e.g. ["TPB"]). After exclusion, at least one bank must remain available.
bankName	string	✕	Specify a single bank code (e.g. BIDV) to lock the flow and take the customer straight to that bank's linking screen.
bankAccountType	string	✕	Type of account to link: personal-account (personal), business-account (business), business-household-account (household business).
redirectUrl	string	✕	Your URL to redirect the customer's browser to after linking is complete on the mobile or web SDK.
metadata	string	✕	Custom partner data (up to 1000 characters). This value is sent back in the Account linking webhook.
isEnableQRScan	boolean	✕	Show a QR scan button on the mobile SDK screen to auto-fill account details from a bank QR code. Disabled by default. Only shown for some banks / account types supported by the SDK.
merchantId	number	~	Sub-merchant ID. Required when you use a Master Merchant account to create a session for a sub-merchant; the sub-merchant must belong to the Master Merchant calling the API.

Sample Request Body:

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

---

3. Response Data

Tingee OpenAPI returns the result as JSON:

Property	Data type	Description
code	string	Result status code. 00 means the session was created successfully.
message	string	Message describing the response status.
data	string	Full bank link SDK URL containing the security token.

Sample Success Response:

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

Sample Error Response:

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

Business error codes:

Error code	Meaning	How to handle
1063	No banks available	Make sure allowedBanks contains at least one supported bank.
1031	Shop not found	Check that shopId exists and belongs to the right Merchant, or leave shopId empty.
1094	Shop does not belong to the Master Merchant	Check that shopId is assigned to the Master Merchant, or leave shopId empty.
1095, 1096	Master Merchant merchantId error	Pass the merchantId of a sub-merchant that belongs to the Master Merchant calling the API.
90, 91, 92, 97	Request authentication error (timestamp, client-id, signature)	See System error codes.
Others	Other errors	See Error codes.

---

4. Backend example (Node.js)

The following code shows how to call the create link session API from your server:

// timestamp and signature are generated as described in "Get started"
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 is the full SDK URL used on the client
  return {
    url: result.data
  };
}