{ "openapi": "3.0.3", "info": { "title": "TINGEE Open API", "version": "1.2.2", "description": "Every request needs 3 headers: `x-client-id`, `x-request-timestamp` (yyyyMMddHHmmssSSS, UTC+7) and `x-signature`.\n\n`x-signature = HMAC_SHA512(\"{x-request-timestamp}:{JSON.stringify(body)}\", secretKey)` as hex. Requests without a body (GET/DELETE with query) sign the string `{}`.\n\nEvery API returns HTTP 200; the outcome is in the `code` field (`00` = success). Details: https://developers.tingee.vn/en/docs/config-info" }, "servers": [ { "url": "https://open-api.tingee.vn", "description": "PROD" }, { "url": "https://uat-open-api.tingee.vn", "description": "UAT" } ], "tags": [ { "name": "Accounts & Identification" }, { "name": "Payment solutions" }, { "name": "Disbursement" }, { "name": "Devices & Hardware" }, { "name": "Operations & Extensions" }, { "name": "E-invoices" }, { "name": "Other" } ], "components": { "securitySchemes": { "clientId": { "type": "apiKey", "in": "header", "name": "x-client-id" }, "timestamp": { "type": "apiKey", "in": "header", "name": "x-request-timestamp" }, "signature": { "type": "apiKey", "in": "header", "name": "x-signature", "description": "HMAC_SHA512(\"{timestamp}:{JSON body}\", secretKey) as hex" } } }, "paths": { "/v1/get-banks": { "get": { "tags": [ "Accounts & Identification" ], "summary": "List supported banks and e-wallets", "description": "Get the full list of banks and e-wallets supported by Tingee, e.g. to let users pick one.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/get-banks", "operationId": "get_get_banks", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": [ { "code": "BIDV", "name": "Ngân hàng TMCP Đầu tư và Phát triển Việt Nam", "bin": "970418", "shortName": "BIDV", "urlLogo": "https://app.tingee.vn/assets/media/logo/bank/bidv.png", "termsAndConditions": { "urlVA": "https://bidv.com.vn/uudai/DKDKSDDV_VIETQR_HENO_140324.pdf" } }, { "code": "BAOKIM", "name": "Ví điện tử BAOKIM", "bin": "BAOKIM", "shortName": "BAOKIM", "urlLogo": "https://app.tingee.vn/assets/media/logo/bank/baokim.png", "termsAndConditions": { "url": "" } } ] } } } } } }, "/v1/get-va-paging": { "post": { "tags": [ "Accounts & Identification" ], "summary": "Query the account list", "description": "Get a paginated list of VAs. You can filter by creation time, bank code or account type.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/get-va-paging", "operationId": "post_get_va_paging", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "totalCount": 1, "items": [ { "bankName": "BIDV", "bankBin": "970418", "accountType": "personal-account", "accountName": "LE DUY NGHIEM", "accountNumber": "0123456789111", "vaAccountNumber": "VQRQAHFVA0551", "status": "active", "creationTime": "2025-09-04T08:12:32.160Z", "shopId": 1001, "transactionType": "credit" } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "type": "string", "description": "Search keyword (partial match on the original account number, virtual account number or account holder name)." }, "skipCount": { "type": "number", "description": "Number of records to skip (e.g. `0` for the first page)." }, "maxResultCount": { "type": "number", "description": "Maximum number of records per page (e.g. `10`, up to `2000`)." }, "startTime": { "type": "string", "description": "Filter by account creation time, from this point (ISO 8601 date-time, e.g. `2025-09-01T00:00:00+07:00`). Only takes effect when passed together with `endTime`." }, "endTime": { "type": "string", "description": "Filter by account creation time, up to this point (ISO 8601 date-time, e.g. `2025-09-30T23:59:59+07:00`). Only takes effect when passed together with `startTime`." }, "merchantId": { "type": "number", "description": "Merchant ID (required if you connect with a Master Merchant account)." }, "bankBin": { "type": "string", "description": "Bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks)." }, "accountType": { "type": "string", "description": "Account type (`personal-account`, `business-account`, `business-household-account`)." }, "shopId": { "type": "number", "description": "Filter by shop ID." }, "status": { "type": "string", "description": "Account status: `active`, `inactive`, `lock`." }, "transactionType": { "type": "string", "description": "Registered transaction type: `credit` or `debit`." } } }, "example": { "skipCount": 0, "maxResultCount": 10, "bankBin": "970418", "accountType": "personal-account" } } } } } }, "/v1/create-va": { "post": { "tags": [ "Accounts & Identification" ], "summary": "Create a virtual account (VA)", "description": "Start a request to create or link a virtual account with the bank. The result returns a confirmId to use in the next confirmation step.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/create-va", "operationId": "post_create_va", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "confirmId": "886b05e9-2d94-4b41-9839-138c941fd1d9" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "bankBin": "970418", "accountType": "personal-account", "accountNumber": "0935926988", "accountName": "NGUYEN THI HUYEN", "identity": "040191014068", "mobile": "0123456789", "isNotifyAccountNumber": false } } } } } }, "/v1/confirm-va": { "post": { "tags": [ "Accounts & Identification" ], "summary": "Confirm a virtual account (VA)", "description": "Confirm a VA creation request with the confirmId received from the create-va API. Some banks also require otpNumber.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/confirm-va", "operationId": "post_confirm_va", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "bankName": "BIDV", "accountType": "personal-account", "accountNumber": "0935926988", "vaAccountNumber": "88880935926988", "shopId": 1024 } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (required if you connect with a Master Merchant account)." }, "bankBin": { "type": "string", "description": "Bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks)." }, "confirmId": { "type": "string", "description": "Confirmation ID received from the `create-va` API." }, "otpNumber": { "type": "string", "description": "OTP the bank sends to the account holder (SMS / bank app)." } }, "required": [ "bankBin", "confirmId", "otpNumber" ] }, "example": { "bankBin": "970418", "confirmId": "886b05e9-2d94-4b41-9839-138c941fd1d9", "otpNumber": "123456" } } } } } }, "/v1/register-notify": { "post": { "tags": [ "Accounts & Identification" ], "summary": "Register for balance notifications (VA Notify)", "description": "Start a balance notification registration request. For some banks, the result includes a confirmId for the next verification step.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/register-notify", "operationId": "post_register_notify", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "confirmId": "72496bf2-ba25-4397-bd38-b9c04baedfd7" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (required if you connect with a Master Merchant account)." }, "vaAccountNumber": { "type": "string", "description": "Virtual account number to receive notifications for (must belong to the Merchant calling the API)." }, "bankBin": { "type": "string", "description": "Bank BIN. Currently only ACB (`970416`) is supported." } }, "required": [ "vaAccountNumber", "bankBin" ] }, "example": { "vaAccountNumber": "V1T199988811", "bankBin": "970416" } } } } } }, "/v1/confirm-register-notify": { "post": { "tags": [ "Accounts & Identification" ], "summary": "Confirm balance notification registration (VA Notify)", "description": "Confirm the registration request with the confirmId and the OTP (if any). After this step, balance notifications are officially activated for the virtual account.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/confirm-register-notify", "operationId": "post_confirm_register_notify", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (required if you connect with a Master Merchant account)." }, "bankBin": { "type": "string", "description": "Bank BIN. Currently only ACB (`970416`) is supported." }, "confirmId": { "type": "string", "description": "Confirmation ID received from the [Register for balance notifications](https://developers.tingee.vn/en/docs/banking/register-notify) API (valid for 4 minutes)." }, "otpNumber": { "type": "string", "description": "OTP the bank sends to the account holder (SMS / bank app)." } }, "required": [ "bankBin", "confirmId", "otpNumber" ] }, "example": { "bankBin": "970416", "confirmId": "886b05e9-2d94-4b41-9839-138c941fd1d9", "otpNumber": "123456" } } } } } }, "/v1/delete-va": { "post": { "tags": [ "Accounts & Identification" ], "summary": "Delete a virtual account (VA)", "description": "Send a VA deletion request. The bankBin and vaAccountNumber parameters are passed as Query Parameters.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/delete-va", "operationId": "post_delete_va", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "confirmId": "DEL_CONFIRM_123456" } } } } } }, "parameters": [ { "name": "merchantId", "in": "query", "required": false, "description": "Merchant ID (required if you connect with a Master Merchant account).", "schema": { "type": "number" } }, { "name": "bankBin", "in": "query", "required": true, "description": "Bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks).", "schema": { "type": "string" }, "example": "970422" }, { "name": "vaAccountNumber", "in": "query", "required": true, "description": "Virtual account number to delete.", "schema": { "type": "string" }, "example": "VQRs23GG4" } ] } }, "/v1/confirm-delete-va": { "post": { "tags": [ "Accounts & Identification" ], "summary": "Confirm virtual account (VA) deletion", "description": "Confirm a VA deletion request with the confirmId received from the delete-va API. Depending on the bank, you may also need to pass otpNumber.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/confirm-delete-va", "operationId": "post_confirm_delete_va", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "id": 12345, "creationTime": "2025-09-04T08:12:32.160Z", "merchantId": 1001, "shopId": 1024, "cashFlowSource": "bank-transfer", "name": "ACB - 88889999", "bankName": "ACB", "bankBin": "970416", "accountType": "personal-account", "linkType": "api-exact", "accountName": "NGUYEN VAN A", "accountNumber": "88889999", "vaAccountNumber": "88889999", "realVANumber": "88889999", "isNotifyAccountNumber": true, "status": "active", "transactionType": "credit" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (required if you connect with a Master Merchant account)." }, "bankBin": { "type": "string", "description": "Bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks)." }, "confirmId": { "type": "string", "description": "Confirmation ID received from the [Delete virtual account number](https://developers.tingee.vn/en/docs/banking/delete-va) API." }, "otpNumber": { "type": "string", "description": "OTP the bank sends to the account holder (SMS / bank app)." } }, "required": [ "bankBin", "confirmId", "otpNumber" ] }, "example": { "bankBin": "970418", "confirmId": "72496bf2-ba25-4397-bd38-b9c04baedfd7", "otpNumber": "123456" } } } } } }, "/v1/create-debit": { "post": { "tags": [ "Accounts & Identification" ], "summary": "Register for debit notifications", "description": "Start a request to register for debit notifications on an ACB account. The result returns a confirmId used for the OTP confirmation step.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/create-debit", "operationId": "post_create_debit", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "confirmId": "c2a8f3e0-4b1d-4e0a-9a51-7d2f0e6b9c11" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Always `970416` (ACB)." }, "accountType": { "type": "string", "description": "Account type: `personal-account`, `business-account`, `business-household-account`." }, "accountNumber": { "type": "string", "description": "ACB account number to register." }, "accountName": { "type": "string", "description": "Account holder name (uppercase, without diacritics)." }, "mobile": { "type": "string", "description": "Phone number registered with ACB, used to receive the OTP. Format: 10 digits, starting with `0`." }, "acbUserId": { "type": "string", "description": "ACB Online / Biz login user ID. Required for business and household business accounts." }, "merchantId": { "type": "number", "description": "Merchant ID (required if you connect with a Master Merchant account)." }, "shopId": { "type": "number", "description": "ID of the shop to assign the account to. If left empty, the system creates a new shop on confirmation." }, "name": { "type": "string", "description": "Account nickname. Default: `ACB - {accountNumber} - Ghi nợ`." }, "merchantName": { "type": "string", "description": "Shop name (used when the system creates a new shop)." }, "merchantAddress": { "type": "string", "description": "Shop address (used when the system creates a new shop)." } }, "required": [ "bankBin", "accountType", "accountNumber", "accountName", "mobile" ] }, "example": { "bankBin": "970416", "accountType": "personal-account", "accountNumber": "12345678", "accountName": "NGUYEN VAN A", "mobile": "0935926988" } } } } } }, "/v1/delete-debit": { "delete": { "tags": [ "Accounts & Identification" ], "summary": "Cancel debit notification registration", "description": "Start a request to cancel debit notifications on an ACB account. The result returns a confirmId used for the OTP confirmation step.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/delete-debit", "operationId": "delete_delete_debit", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "confirmId": "7f4c1e9a-2d3b-4c8e-b1a0-5e6f7a8b9c0d" } } } } } }, "parameters": [ { "name": "bankBin", "in": "query", "required": true, "description": "Always `970416` (ACB).", "schema": { "type": "string" }, "example": "970416" }, { "name": "vaAccountNumber", "in": "query", "required": true, "description": "ACB account number registered for debit notifications.", "schema": { "type": "string" }, "example": "12345678" }, { "name": "merchantId", "in": "query", "required": false, "description": "Merchant ID (required if you connect with a Master Merchant account).", "schema": { "type": "number" } } ] } }, "/v1/transaction/get-paging": { "post": { "tags": [ "Accounts & Identification" ], "summary": "Transaction history", "description": "Query the detailed transaction history. The result includes the amount, transaction type, time and transfer description.\n\nDocumentation: https://developers.tingee.vn/en/docs/banking/get-paging-transaction", "operationId": "post_transaction_get_paging", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "totalCount": 1, "items": [ { "transactionId": "3f1c2a9e-8b4d-4e57-9a61-2c7d5b0e8f14", "merchantId": 1001, "shopId": 1024, "bankBin": "970418", "cashFlowSource": "bank-transfer", "code": "FT25283123456", "amount": 100000, "type": "credit", "content": "Thanh toan don hang 123", "currency": "VND", "accountNumber": "0935926988", "vaAccountNumber": "88880935926988", "transactionDate": "20251010103000", "billId": null } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skipCount": { "type": "number", "description": "Number of records to skip (pagination)." }, "maxResultCount": { "type": "number", "description": "Maximum number of records per page (up to `200`)." }, "merchantId": { "type": "number", "description": "Merchant ID (required if you connect with a Master Merchant account)." }, "shopIds": { "type": "array", "items": {}, "description": "List of shop IDs to filter by." }, "vaAccountNumbers": { "type": "array", "items": {}, "description": "List of virtual account numbers to filter by." }, "bankBin": { "type": "string", "description": "Bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks)." }, "billId": { "type": "string", "description": "Filter payment transactions for a dynamic QR code (the `billId` returned by the create dynamic QR API)." }, "startTime": { "type": "string", "description": "Start time (format: `yyyyMMddHHmmss`, UTC+7)." }, "endTime": { "type": "string", "description": "End time (format: `yyyyMMddHHmmss`, UTC+7)." } }, "required": [ "startTime", "endTime" ] }, "example": { "skipCount": 0, "maxResultCount": 50, "vaAccountNumbers": [ "88880935926988" ], "bankBin": "970418", "startTime": "20251001000000", "endTime": "20251010235959" } } } } } }, "/v1/create-bank-link-session": { "post": { "tags": [ "Accounts & Identification" ], "summary": "Create a link session", "description": "Create a bank account link session to get the SDK URL to display on the client.\n\nDocumentation: https://developers.tingee.vn/en/docs/bank-link/create-session", "operationId": "post_create_bank_link_session", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } } } } } } } }, "/v1/payment-gateway/create-link": { "post": { "tags": [ "Payment solutions" ], "summary": "Create a payment link", "description": "Create a payment link (Checkout URL) to send to the customer.\n\nDocumentation: https://developers.tingee.vn/en/docs/payment-gateway/create-payment-link", "operationId": "post_payment_gateway_create_link", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } } } } } } } }, "/v1/generate-viet-qr": { "post": { "tags": [ "Payment solutions" ], "summary": "Create a static QR code (VietQR)", "description": "Create a static QR code in the VietQR standard. Customers can scan it to transfer money manually to your account.\n\nDocumentation: https://developers.tingee.vn/en/docs/qr/static/generate-viet-qr", "operationId": "post_generate_viet_qr", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "qrCode": "00020101021238540010A0000007270124000697041801102151000286...", "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSU..." } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks)." }, "accountNumber": { "type": "string", "description": "Receiving account number (original account number or virtual account number). For `bankBin = BAOKIM`, it must be a Bảo Kim virtual account number linked on TINGEE." }, "amount": { "type": "number", "description": "Default amount (VND, shown when scanned). Leave empty to let the payer enter the amount." }, "content": { "type": "string", "description": "Default transfer description." } }, "required": [ "bankBin", "accountNumber" ] }, "example": { "bankBin": "970418", "accountNumber": "21510002865945", "amount": 100000, "content": "Thanh toan don hang" } } } } } }, "/v1/generate-dynamic-qr": { "post": { "tags": [ "Payment solutions" ], "summary": "Create a dynamic QR code (Dynamic QR)", "description": "Create a dynamic QR code for each transaction. The result includes the QR code string and the bill information in the system.\n\nDocumentation: https://developers.tingee.vn/en/docs/qr/dynamic/generate-dynamic-qr", "operationId": "post_generate_dynamic_qr", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "qrCode": "00020101021238570010A000000727012700069704180113V1TQRD7F3A9C1B2E40208QRIBFTTA53037045406500000...", "qrAccount": "V1TQRD7F3A9C1B2E4", "billId": "V1TQRD7F3A9C1B2E4" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "vaAccountNumber": { "type": "string", "description": "The Merchant's linked virtual account (VA) number, up to 50 characters." }, "qrCodeType": { "type": "string", "description": "QR type: - `dynamic-one-time-payment`: one-time payment QR. - `dynamic-recurring-payment`: recurring payment QR." }, "bankBin": { "type": "string", "description": "Bank BIN of the `vaAccountNumber`. Supported: OCB (`970448`), MB (`970422`), BIDV (`970418`), VietinBank (`970415`), Vietcombank (`970436`), VPBank (`970432`), Bảo Kim (`BAOKIM`). See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks)." }, "amount": { "type": "number", "description": "Amount to pay (VND, minimum `1`)." }, "name": { "type": "string", "description": "Display name of the dynamic QR. Applies to Bảo Kim only; if left empty, the system uses the account holder name." }, "purpose": { "type": "string", "description": "Payment description." }, "expireInMinute": { "type": "number", "description": "Dynamic QR expiry time (minutes), from `1` to `43200` (30 days). Default `43200`. Required for OCB (`970448`)." }, "extraInfo": { "type": "string", "description": "Additional partner-defined information, up to 200 characters. Returned in the [Get dynamic QR status](https://developers.tingee.vn/en/docs/qr/dynamic/get-status-dynamic-qr) API." } }, "required": [ "vaAccountNumber", "qrCodeType", "bankBin", "amount" ] }, "example": { "vaAccountNumber": "V1T199988811", "qrCodeType": "dynamic-one-time-payment", "bankBin": "970418", "amount": 500000, "purpose": "Thanh toan cho hoa don HD2918732312" } } } } } }, "/v1/delete-dynamic-qr": { "post": { "tags": [ "Payment solutions" ], "summary": "Delete a dynamic QR code (Dynamic QR)", "description": "Deactivate a dynamic QR code. After deletion, customers can no longer pay with this QR code.\n\nDocumentation: https://developers.tingee.vn/en/docs/qr/dynamic/delete-dynamic-qr", "operationId": "post_delete_dynamic_qr", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "qrAccount": { "type": "string", "description": "QR account (`data.qrAccount`) returned by the [Create dynamic QR](https://developers.tingee.vn/en/docs/qr/dynamic/generate-dynamic-qr) API." }, "billId": { "type": "string", "description": "Dynamic QR ID (`data.billId`) returned by the [Create dynamic QR](https://developers.tingee.vn/en/docs/qr/dynamic/generate-dynamic-qr) API." } }, "required": [ "qrAccount", "billId" ] }, "example": { "qrAccount": "V1TQRD7F3A9C1B2E4", "billId": "V1TQRD7F3A9C1B2E4" } } } } } }, "/v1/get-status-dynamic-qr": { "post": { "tags": [ "Payment solutions" ], "summary": "Get dynamic QR code status", "description": "Check the status of a dynamic QR code. The result includes the bill information and related transactions (if any).\n\nDocumentation: https://developers.tingee.vn/en/docs/qr/dynamic/get-status-dynamic-qr", "operationId": "post_get_status_dynamic_qr", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "billInfo": { "billId": "V1TQRD7F3A9C1B2E4", "qrCodeType": "dynamic-one-time-payment", "bankBin": "970418", "accountNumber": "21510002865945", "vaAccountNumber": "V1T199988811", "qrAccount": "V1TQRD7F3A9C1B2E4", "amount": 500000, "purpose": "Thanh toan cho hoa don HD2918732312", "totalAmountPaid": 500000, "totalPaymentsCount": 1, "expireInMinute": 43185, "extraInfo": null, "status": "fully-paid" }, "transactionInfos": [ { "transactionId": "3f1c2a9e-8b4d-4e57-9a61-2c7d5b0e8f14", "merchantId": 1001, "shopId": 1024, "bankBin": "970418", "cashFlowSource": "bank-transfer", "code": "FT25283123456", "amount": 500000, "type": "credit", "content": "Thanh toan cho hoa don HD2918732312", "currency": "VND", "accountNumber": "21510002865945", "vaAccountNumber": "V1TQRD7F3A9C1B2E4", "transactionDate": "20251010103000", "billId": "V1TQRD7F3A9C1B2E4" } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "qrAccount": { "type": "string", "description": "QR account (`data.qrAccount`) returned by the [Create dynamic QR](https://developers.tingee.vn/en/docs/qr/dynamic/generate-dynamic-qr) API." }, "billId": { "type": "string", "description": "Dynamic QR ID (`data.billId`) returned by the [Create dynamic QR](https://developers.tingee.vn/en/docs/qr/dynamic/generate-dynamic-qr) API." } }, "required": [ "qrAccount", "billId" ] }, "example": { "qrAccount": "V1TQRD7F3A9C1B2E4", "billId": "V1TQRD7F3A9C1B2E4" } } } } } }, "/v1/deep-link/generate": { "post": { "tags": [ "Payment solutions" ], "summary": "Create a Deep Link", "description": "Create a Deep Link for opening a payment app, making a transfer or paying a bill.\n\nDocumentation: https://developers.tingee.vn/en/docs/deeplink/deep-link", "operationId": "post_deep_link_generate", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": "mbbank://applink?targetPage=QRPay&source=HENO&qrContent=00020101021238..." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "type": { "type": "string", "description": "Deep Link type (`qr-code`, `payment-with-bank-account`, `bill-payment`). Currently the system only processes `qr-code` and `payment-with-bank-account`; `bill-payment` is not supported yet." }, "qrCode": { "type": "string", "description": "VietQR (EMVCo) data string to pay (Required if type is `qr-code`)." }, "redirectUrl": { "type": "string", "description": "URL to redirect to after the user finishes in the app. Required for all banks except MB Bank (`970422`)." }, "bankBin": { "type": "string", "description": "BIN of the bank (app) used to pay. Supported banks: ACB (`970416`), Sacombank (`970403`), BIDV (`970418`), OCB (`970448`), MB Bank (`970422`), VPBank (`970432`)." }, "destinationBankBin": { "type": "string", "description": "Beneficiary bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks). (Required if type is `payment-with-bank-account`)." }, "accountNumber": { "type": "string", "description": "Beneficiary account number. (Required if type is `payment-with-bank-account` or `bill-payment`)." }, "accountName": { "type": "string", "description": "Beneficiary account holder name. (Required if type is `bill-payment`)." }, "billNumber": { "type": "string", "description": "Bill number (Required if type is `bill-payment`)." }, "amount": { "type": "number", "description": "Transaction amount (used when type is `payment-with-bank-account`)." }, "content": { "type": "string", "description": "Transfer description (used when type is `payment-with-bank-account`)." } }, "required": [ "type", "bankBin" ] }, "example": { "type": "qr-code", "qrCode": "base64_data", "redirectUrl": "https://your-app.com/callback", "bankBin": "970422", "accountNumber": "0123456789", "amount": 50000, "content": "Thanh toan don hang" } } } } } }, "/v1/create-pos-bill": { "post": { "tags": [ "Payment solutions" ], "summary": "Create a POS order", "description": "Create a payment order on a Payoo POS terminal. The returned billId is used for lookup, cancellation and Webhook reconciliation.\n\nDocumentation: https://developers.tingee.vn/en/docs/pos-bill/create-pos-bill", "operationId": "post_create_pos_bill", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "billId": "9f1c2b7e4a5d4c3b8e2f1a0b9c8d7e6f", "amount": 150000, "expireInMinute": 30, "purpose": "Thanh toan don hang DH001" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "ID of the Merchant that owns the POS terminal. Required if you connect with a Master Merchant account." }, "bankBin": { "type": "string", "description": "Always pass `PAYOO`." }, "vaAccountNumber": { "type": "string", "description": "Device code of the linked Payoo POS terminal (up to 50 characters)." }, "amount": { "type": "number", "description": "Amount to pay (VND, positive integer)." }, "paymentMethod": { "type": "string", "description": "Payment method shown on the POS terminal: - `card`: Card payment - `qr`: QR code payment Leave empty (or any other value) to let the customer choose on the POS terminal." }, "purpose": { "type": "string", "description": "Payment description, shown on the POS terminal." }, "expireInMinute": { "type": "number", "description": "Order validity period (minutes), from `1` to `43200`. Default `43200` (30 days)." }, "extraInfo": { "type": "string", "description": "Additional partner information (up to 200 characters), included in the payment Webhook." } }, "required": [ "bankBin", "vaAccountNumber", "amount" ] }, "example": { "bankBin": "PAYOO", "vaAccountNumber": "POS00012345", "amount": 150000, "paymentMethod": "card", "purpose": "Thanh toan don hang DH001", "expireInMinute": 30, "extraInfo": "DH001" } } } } } }, "/v1/get-detail-pos-bill": { "get": { "tags": [ "Payment solutions" ], "summary": "POS order details", "description": "Look up POS order details by billId.\n\nDocumentation: https://developers.tingee.vn/en/docs/pos-bill/get-detail-pos-bill", "operationId": "get_get_detail_pos_bill", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "orderId": "9f1c2b7e4a5d4c3b8e2f1a0b9c8d7e6f", "amount": 150000, "expirationTime": "20261014153000", "createTime": "20261014150000", "status": 1, "transactionCode": "PY123456789" } } } } } }, "parameters": [ { "name": "bankBin", "in": "query", "required": true, "description": "Always pass `PAYOO`.", "schema": { "type": "string" }, "example": "PAYOO" }, { "name": "vaAccountNumber", "in": "query", "required": true, "description": "Payoo POS device code.", "schema": { "type": "string" }, "example": "POS00012345" }, { "name": "billId", "in": "query", "required": true, "description": "Order ID received from the [Create a POS order](https://developers.tingee.vn/en/docs/pos-bill/create-pos-bill) API.", "schema": { "type": "string" }, "example": "9f1c2b7e4a5d4c3b8e2f1a0b9c8d7e6f" } ] } }, "/v1/update-pos-bill": { "put": { "tags": [ "Payment solutions" ], "summary": "Cancel a POS order", "description": "Cancel a POS order by billId on the Payoo system.\n\nDocumentation: https://developers.tingee.vn/en/docs/pos-bill/update-pos-bill", "operationId": "put_update_pos_bill", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "ReturnCode": "0", "Description": "Success" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Always pass `PAYOO`." }, "vaAccountNumber": { "type": "string", "description": "Payoo POS device code." }, "billId": { "type": "string", "description": "ID of the order to cancel, received from the [Create a POS order](https://developers.tingee.vn/en/docs/pos-bill/create-pos-bill) API." } }, "required": [ "bankBin", "vaAccountNumber", "billId" ] }, "example": { "bankBin": "PAYOO", "vaAccountNumber": "POS00012345", "billId": "9f1c2b7e4a5d4c3b8e2f1a0b9c8d7e6f" } } } } } }, "/v1/direct-debit/register": { "post": { "tags": [ "Payment solutions" ], "summary": "Link an account", "description": "Create a request to link a bank account. Returns a URL where the user completes the verification steps on the Tingee interface.\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-debit/register", "operationId": "post_direct_debit_register", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": "https://direct-debit.tingee.vn/direct-debit?requestId=..." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for each request, in UUID format. Reuse this `requestId` to look up the result with the [Query account status](https://developers.tingee.vn/en/docs/direct-debit/get-subscription-status) API." }, "phone": { "type": "string", "description": "Phone number registered with the bank account." }, "returnUrl": { "type": "string", "description": "URL to return to your application after completion." }, "bankBin": { "type": "string", "description": "Bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks)." }, "accountName": { "type": "string", "description": "Account holder name (prefilled as a suggestion for the user)." }, "email": { "type": "string", "description": "Customer's email." } }, "required": [ "requestId", "phone", "returnUrl" ] }, "example": { "requestId": "550760e0-1cc2-44b9-85ba-eb318e228b4d", "phone": "0974444479", "returnUrl": "https://example.com" } } } } } }, "/v1/direct-debit/payment-bill": { "post": { "tags": [ "Payment solutions" ], "summary": "Pay a bill", "description": "Request a bill payment from a linked customer account. Supports automatic payment or payment with confirmation.\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-debit/payment-bill", "operationId": "post_direct_debit_payment_bill", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "code": "00", "status": "success", "transactionCode": "TXN-0123456789", "returnUrl": "https://example.com?message=Success&type=direct-debit-transaction" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "ID of the request to Tingee (UUID), unique for each payment. This value is used as the `transactionId` of the debit transaction on TINGEE." }, "subscriptionId": { "type": "string", "description": "ID of the linked bank account (UUID). The account must be `active`." }, "tokenRef": { "type": "string", "description": "Reference code of the customer's account." }, "amount": { "type": "string", "description": "Bill amount to pay (VND), sent as a numeric string. Example: `\"500000\"`." }, "description": { "type": "string", "description": "Payment description." }, "partnerCode": { "type": "string", "description": "Debit partner. Valid value: `one-pay`." }, "serviceProviderName": { "type": "string", "description": "Name of the partner using the service (shown in the confirmation notification sent to the customer)." }, "returnUrl": { "type": "string", "description": "URL to redirect back to the partner after completion." }, "accountNumber": { "type": "string", "description": "Customer's account number. The system always debits the account linked to `subscriptionId`." }, "additionalData": { "type": "object", "description": "Additional data (bill number, customer name, ...). The object's JSON string is at most 500 characters. The `billNumber` field (if any) is shown as the bill number in the Email/Zalo confirmation." } }, "required": [ "requestId", "subscriptionId", "tokenRef", "amount", "description", "partnerCode", "serviceProviderName", "returnUrl" ] }, "example": { "requestId": "550760e0-1cc2-44b9-85ba-eb318e228b4f", "subscriptionId": "89188e53-eba3-40fa-9323-04422ced3637", "tokenRef": "TKN-123456789", "amount": "500000", "description": "THANH TOAN HOA DON DV HD123456", "partnerCode": "one-pay", "serviceProviderName": "Công ty TMCP ABC", "returnUrl": "https://example.com" } } } } } }, "/v1/direct-debit/delete-subscription": { "delete": { "tags": [ "Payment solutions" ], "summary": "Unlink an account", "description": "Create a request to unlink a bank account. The unlinking either completes immediately or returns an OTP verification URL.\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-debit/delete-subscription", "operationId": "delete_direct_debit_delete_subscription", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "code": "00" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "ID of the request to Tingee (UUID)." }, "subscriptionId": { "type": "string", "description": "ID of the linked bank account (UUID). The account must be `active`." }, "tokenRef": { "type": "string", "description": "Reference code of the customer's account." }, "returnUrl": { "type": "string", "description": "URL to redirect back to the partner after completion." } }, "required": [ "requestId", "subscriptionId", "tokenRef", "returnUrl" ] }, "example": { "requestId": "550760e0-1cc2-44b9-85ba-eb318e228b4f", "subscriptionId": "89188e53-eba3-40fa-9323-04422ced3637", "tokenRef": "TKN-12345678", "returnUrl": "https://example.com" } } } } } }, "/v1/direct-debit/refund": { "post": { "tags": [ "Payment solutions" ], "summary": "Refund a transaction", "description": "Request a refund for a successful transaction. Supports partial or full refunds.\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-debit/refund", "operationId": "post_direct_debit_refund", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "status": "success", "transactionId": "550760e0-1cc2-44b9-85ba-eb318e228b4f", "refundAmount": 50000 } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionId": { "type": "string", "description": "ID of the linked bank account (UUID)." }, "tokenRef": { "type": "string", "description": "Reference code of the customer's account." }, "transactionId": { "type": "string", "description": "ID of the transaction to refund (the RequestId of the payment order)." }, "amount": { "type": "number", "description": "Amount to refund." } }, "required": [ "subscriptionId", "tokenRef", "transactionId", "amount" ] }, "example": { "subscriptionId": "89188e53-eba3-40fa-9323-04422ced3637", "tokenRef": "TKN-12345678", "transactionId": "550760e0-1cc2-44b9-85ba-eb318e228b4f", "amount": 50000 } } } } } }, "/v1/direct-debit/edit-confirm-payment-method": { "put": { "tags": [ "Payment solutions" ], "summary": "Update the payment confirmation method", "description": "Create a request to change the payment confirmation method (Email/Zalo). Returns a URL where the customer completes the configuration.\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-debit/edit-confirm-payment-method", "operationId": "put_direct_debit_edit_confirm_payment_method", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": "https://direct-debit.tingee.vn/edit-confirm-payment-method?requestId=..." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "ID of the request to Tingee (UUID)." }, "subscriptionId": { "type": "string", "description": "ID of the linked bank account (UUID)." }, "returnUrl": { "type": "string", "description": "URL to redirect back to the partner after completion." } }, "required": [ "requestId", "subscriptionId", "returnUrl" ] }, "example": { "requestId": "550760e0-1cc2-44b9-85ba-eb318e228b4f", "subscriptionId": "89188e53-eba3-40fa-9323-04422ced3637", "returnUrl": "https://example.com" } } } } } }, "/v1/direct-debit/get-subscription-status": { "get": { "tags": [ "Payment solutions" ], "summary": "Query account status", "description": "Get the details and current status (active/inactive) of a linked account.\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-debit/get-subscription-status", "operationId": "get_direct_debit_get_subscription_status", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "tokenRef": "TKN-12345678", "bankName": "VCB", "bankBin": "970436", "accountName": "NGUYEN VAN A", "accountNumber": "0123456789", "phone": "0974444479", "email": "nguyenvana@example.com", "confirmPaymentByEmail": true, "confirmEmail": "nguyenvana@example.com", "confirmPaymentByZalo": false, "confirmPhoneNumber": null, "customerKey": null, "status": "active", "lastModificationTime": "2026-01-15T05:20:49.000Z", "lastModifierUserId": null } } } } } }, "parameters": [ { "name": "requestId", "in": "query", "required": false, "description": "ID of the request used when registering (UUID). Send `requestId`, or the `subscriptionId` + `tokenRef` pair.", "schema": { "type": "string" }, "example": "550760e0-1cc2-44b9-85ba-eb318e228b4f" }, { "name": "subscriptionId", "in": "query", "required": false, "description": "ID of the linked bank account (UUID). Required when `requestId` is not sent.", "schema": { "type": "string" }, "example": "89188e53-eba3-40fa-9323-04422ced3637" }, { "name": "tokenRef", "in": "query", "required": false, "description": "Reference code of the customer's account. Required when `requestId` is not sent.", "schema": { "type": "string" }, "example": "TKN-12345678" } ] } }, "/v1/direct-debit/get-transaction-status": { "get": { "tags": [ "Payment solutions" ], "summary": "Query transaction status", "description": "Get the detailed status of a specific transaction by transactionId (the transaction ID on the TINGEE system).\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-debit/get-transaction-status", "operationId": "get_direct_debit_get_transaction_status", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "transactionId": "550760e0-1cc2-44b9-85ba-eb318e228b4f", "subscriptionId": "89188e53-eba3-40fa-9323-04422ced3637", "tokenRef": "TKN-12345678", "bankBin": "970436", "customer": { "name": "NGUYEN VAN A", "phone": "0974444479", "email": "nguyenvana@example.com" }, "accountNumber": "0123456789", "accountName": "NGUYEN VAN A", "code": "DD-20260113001", "amount": "200000", "currency": "VND", "content": "THANH TOAN HOA DON DV HD123456", "transactionDate": "2026-01-13T09:30:00.000Z", "status": "success" } } } } } }, "parameters": [ { "name": "transactionId", "in": "query", "required": true, "description": "ID of the debit transaction on the TINGEE system (UUID), taken from the `transactionId` field of the [Transaction history](https://developers.tingee.vn/en/docs/direct-debit/get-paging-transactions) API.", "schema": { "type": "string" }, "example": "550760e0-1cc2-44b9-85ba-eb318e228b4f" }, { "name": "subscriptionId", "in": "query", "required": true, "description": "ID of the linked bank account (UUID).", "schema": { "type": "string" }, "example": "89188e53-eba3-40fa-9323-04422ced3637" }, { "name": "tokenRef", "in": "query", "required": true, "description": "Reference code of the customer's account.", "schema": { "type": "string" }, "example": "TKN-12345678" } ] } }, "/v1/direct-debit/get-paging-transactions": { "get": { "tags": [ "Payment solutions" ], "summary": "Query transaction history", "description": "Get the list of completed payment transactions, with time filtering and pagination.\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-debit/get-paging-transactions", "operationId": "get_direct_debit_get_paging_transactions", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "totalCount": 1, "items": [ { "transactionId": "550760e0-1cc2-44b9-85ba-eb318e228b4f", "code": "FT123372233", "bankName": "VCB", "bankBin": "970436", "amount": "150000", "content": "Thanh toan don hang #12345", "accountNumber": "0123456789", "transactionDate": "2026-01-15T05:20:49.000Z", "subscriptionId": "89188e53-eba3-40fa-9323-04422ced3637", "tokenRef": "TKN-12345678", "status": "success", "additionalData": { "billNumber": "HD123456" } } ] } } } } } }, "parameters": [ { "name": "subscriptionId", "in": "query", "required": true, "description": "ID of the linked bank account (UUID).", "schema": { "type": "string" }, "example": "89188e53-eba3-40fa-9323-04422ced3637" }, { "name": "tokenRef", "in": "query", "required": true, "description": "Reference code of the customer's account.", "schema": { "type": "string" }, "example": "TKN-12345678" }, { "name": "startTime", "in": "query", "required": false, "description": "Start time (yyyy-MM-dd HH:mm:ss). Default: 30 days before the API call. The system filters from the start of the `startTime` day.", "schema": { "type": "string" }, "example": "2025-12-16 12:20:49" }, { "name": "endTime", "in": "query", "required": false, "description": "End time (yyyy-MM-dd HH:mm:ss). Default: the time of the API call. The system filters up to the end of the `endTime` day. The `startTime` – `endTime` range is at most 30 days.", "schema": { "type": "string" }, "example": "2026-01-15 12:20:49" }, { "name": "skipCount", "in": "query", "required": false, "description": "Number of transactions to skip (default: 0).", "schema": { "type": "number" }, "example": "0" }, { "name": "maxResultCount", "in": "query", "required": false, "description": "Number of transactions to return (default: 10).", "schema": { "type": "number" }, "example": "10" } ] } }, "/v1/direct-link/get-authorization-url": { "get": { "tags": [ "Disbursement" ], "summary": "Get authorization URL", "description": "Get the account authorization URL (BIDV only)\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/get-authorization-url", "operationId": "get_direct_link_get_authorization_url", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": "https://www.bidv.net/bidvdirectuat/auth/realms/ibank/protocol/openid-connect/auth?client_id=a2910ceecf2841ac9797aff5312e5530&redirect_uri=https%3A%2F%2Fuat-open-api.tingee.vn%2Fv1%2Fdirect-link%2Fcallback&response_type=code&scope=openid&code_challenge=pqnBhc_OSs0P-GrSa26mNI5dE7kVfACuOgyfngO4JsM&code_challenge_method=S256&app_code=25607354&device_id=f7a3b2c1-9d4e-4f8b-a6c5-3e2d1b0a9f8e&ui_locales=vi-vn&state=4c951682-2285-473c-98e3-0f1a7901c04c" } } } } }, "parameters": [ { "name": "bankBin", "in": "query", "required": true, "description": "Bank BIN. Pass 970418, the BIN of BIDV, by default", "schema": { "type": "string" }, "example": "970418" }, { "name": "role", "in": "query", "required": true, "description": "Role of the account to authorize - Maker: Account that creates disbursement payment orders - Checker: Account that approves disbursement payment orders", "schema": { "type": "string" }, "example": "Maker" }, { "name": "returnUrl", "in": "query", "required": true, "description": "URL the user is redirected back to after signing in and authorizing successfully on BIDV (TINGEE redirects to exactly this URL, without adding any parameters).", "schema": { "type": "string" }, "example": "https://yourdomain.com/callback" } ] } }, "/v1/direct-link/create-transfer": { "post": { "tags": [ "Disbursement" ], "summary": "Create payment order", "description": "Create a disbursement payment order using the Maker/Checker model (BIDV only)\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/create-transfer-maker-checker\n\nSee also: https://developers.tingee.vn/en/docs/direct-link/create-transfer-direct", "operationId": "post_direct_link_create_transfer", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "status": "SUCCESS", "totalRecords": 1, "validRecords": 1, "invalidRecords": 0, "requireAuth": false, "transAuth": null, "records": [ { "requestId": "TRANS_1006_A04", "status": "INIT", "transactionId": "PM0226061000074420", "transactionCode": "PM02", "message": null, "feeTotal": 11000 } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Bank BIN. Always pass 970418 (BIDV's BIN)" }, "action": { "type": "string", "description": "Action performed by the maker of the disbursement order - `REQUEST_APPROVAL`: Save and submit the disbursement transaction for approval immediately - `INIT`: Save the disbursement transaction as a draft to submit for approval later" }, "actionType": { "type": "string", "description": "Purpose of the disbursement order - `INTERNAL_TRANSFER`: Domestic transfer - `SALARY`: Salary payment - `BILL_PAYMENT`: Bill / statement payment" }, "debitAccountNumber": { "type": "string", "description": "Payment (debit) account number" }, "debitAccountName": { "type": "string", "description": "Payment account holder name (for reference only, not sent to BIDV)." }, "transactionType": { "type": "string", "description": "Transaction type *(global)* - `in-bank` : Within the bank - `fast-out`: NAPAS 247 fast transfer - `regular-out`: Standard interbank transfer Required if not passed at the record level." }, "feeMethod": { "type": "string", "description": "Fee method *(global)* - `O` : The payment account pays the fee - `B`: The receiving account pays the fee Required, except for `INTERNAL_TRANSFER` batch orders (`records` has more than 1 item) — in that case you can pass it per record via `records[].feeMethod` (default `O`). For `SALARY` / `BILL_PAYMENT`, only this global value is used." }, "effectiveDate": { "type": "string", "description": "Posting date of the transaction at the bank (format: `yyyy-MM-dd`) *(global)* Required when `action = REQUEST_APPROVAL` and `actionType` is not `INTERNAL_TRANSFER`." }, "remark": { "type": "string", "description": "Transfer description / general description of the batch (used for `SALARY` / `BILL_PAYMENT`; for `INTERNAL_TRANSFER` the system uses `records[].remark`). Required when `action = REQUEST_APPROVAL` and `actionType` is not `INTERNAL_TRANSFER`." }, "approvalNote": { "type": "string", "description": "Note from the maker sent along when submitting for approval (`action = REQUEST_APPROVAL`). Currently only applies to `SALARY` / `BILL_PAYMENT`." }, "currency": { "type": "string", "description": "Posting currency of the payment account (default: VND)" }, "creditAccountType": { "type": "string", "description": "How the recipient receives the money *(global)*, used when a record does not pass `records[].creditAccountType`: - `ACCOUNT`: Receive to an account number - `ID`: Receive in cash at the counter with an identity document" }, "records": { "type": "array", "items": {}, "description": "List of transaction records to create - Single order: array with 1 item - Batch order: array with n items (`INTERNAL_TRANSFER`: up to 500 items)" } }, "required": [ "bankBin", "action", "actionType", "debitAccountNumber", "records" ] }, "examples": { "example1": { "summary": "INIT (Single)", "value": { "actionType": "INTERNAL_TRANSFER", "action": "INIT", "bankBin": "970418", "debitAccountNumber": "8600007007", "currency": "VND", "feeMethod": "O", "effectiveDate": "2026-06-04", "records": [ { "requestId": "TRANS_1006_A04", "creditAccountType": "ACCOUNT", "creditAccountNumber": "2220366666", "creditAccountName": "NGUYEN VAN A", "amount": 32987, "creditBankBin": "970418", "remark": "Chuyen tien" } ] } }, "example2": { "summary": "INIT (Batch)", "value": { "actionType": "INTERNAL_TRANSFER", "action": "INIT", "bankBin": "970418", "debitAccountNumber": "8600007007", "currency": "VND", "feeMethod": "O", "effectiveDate": "2026-06-04", "remark": "Chuyen tien nhieu nguoi", "records": [ { "requestId": "TRANS_0406_A04", "creditAccountType": "ACCOUNT", "creditAccountNumber": "2220366666", "creditAccountName": "NGUYEN VAN A", "amount": 32987, "creditBankBin": "970418", "transactionType": "in-bank", "remark": "Thanh toan 1" }, { "requestId": "TRANS_0406_A05", "creditAccountType": "ACCOUNT", "creditAccountNumber": "6666688822", "creditAccountName": "NGUYEN LOC PHAT", "amount": 12098, "creditBankBin": "970406", "transactionType": "fast-out", "remark": "Thanh toan 2" }, { "requestId": "TRANS_0406_A06", "creditId": "034201000243", "creditAccountType": "ID", "creditAccountName": "TRAN NHAT LE", "amount": 32987, "creditBankBin": "970406", "transactionType": "fast-out", "creditIssueDate": "2022-06-02", "creditIssueAddress": "Ha Noi", "creditBranchCode": "96304004", "remark": "Thanh toan 3" } ] } }, "example3": { "summary": "REQUEST_APPROVAL (Single)", "value": { "actionType": "INTERNAL_TRANSFER", "action": "REQUEST_APPROVAL", "bankBin": "970418", "debitAccountNumber": "8600007007", "currency": "VND", "feeMethod": "O", "approvalNote": "Duyet gap", "effectiveDate": "2026-06-04", "records": [ { "requestId": "TRANS_1006_A04", "creditAccountType": "ACCOUNT", "creditAccountNumber": "2220366666", "creditAccountName": "NGUYEN VAN A", "amount": 32987, "creditBankBin": "970418", "remark": "Chuyen tien" } ] } }, "example4": { "summary": "REQUEST_APPROVAL (Batch)", "value": { "actionType": "INTERNAL_TRANSFER", "action": "REQUEST_APPROVAL", "bankBin": "970418", "debitAccountNumber": "8600007007", "currency": "VND", "feeMethod": "O", "approvalNote": "Duyet gap", "effectiveDate": "2026-06-04", "remark": "Chuyen tien nhieu nguoi", "records": [ { "requestId": "TRANS_0406_A04", "creditAccountType": "ACCOUNT", "creditAccountNumber": "2220366666", "creditAccountName": "NGUYEN VAN A", "amount": 32987, "creditBankBin": "970418", "transactionType": "in-bank", "remark": "Thanh toan 1" }, { "requestId": "TRANS_0406_A05", "creditAccountType": "ACCOUNT", "creditAccountNumber": "6666688822", "creditAccountName": "NGUYEN LOC PHAT", "amount": 12098, "creditBankBin": "970406", "transactionType": "fast-out", "remark": "Thanh toan 2" }, { "requestId": "TRANS_0406_A06", "creditId": "034201000243", "creditAccountType": "ID", "creditAccountName": "TRAN NHAT LE", "amount": 32987, "creditBankBin": "970406", "transactionType": "fast-out", "creditIssueDate": "2022-06-02", "creditIssueAddress": "Ha Noi", "creditBranchCode": "96304004", "remark": "Thanh toan 3" } ] } } } } } } } }, "/v1/direct-link/delete-transfer": { "delete": { "tags": [ "Disbursement" ], "summary": "Delete payment order", "description": "Delete a disbursement payment order you created (Maker)\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/delete-transfer", "operationId": "delete_direct_link_delete_transfer", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "listIdSuccess": [ "PM0226061000074420" ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Bank BIN. Currently only 970418 (BIDV) is supported. The API uses the BIDV authorization session of the `Maker` role." }, "actionType": { "type": "string", "description": "Disbursement order type - `INTERNAL_TRANSFER`: Domestic transfer - `SALARY`: Salary payment - `BILL_PAYMENT`: Bill / statement payment" }, "ids": { "type": "array", "items": {}, "description": "List of transaction IDs to delete. - `INTERNAL_TRANSFER`: the `records[].transactionId` values returned by [Create payment order](https://developers.tingee.vn/en/docs/direct-link/create-transfer-maker-checker); every ID must be a transaction created through TINGEE — if any ID is not found, the whole request is rejected. - `SALARY` / `BILL_PAYMENT`: the `data.transactionId` value (batch-level transaction ID)." } }, "required": [ "bankBin", "actionType", "ids" ] }, "example": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "ids": [ "PM0226061000074420" ] } } } } } }, "/v1/direct-link/process-transaction": { "post": { "tags": [ "Disbursement" ], "summary": "Submit a saved disbursement order for approval", "description": "Submit a saved disbursement order for approval\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/process-transaction", "operationId": "post_direct_link_process_transaction", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "successfulTransactions": [], "failedTransactions": [], "requireAuth": true, "transAuth": { "authType": "SMARTOTP", "expTime": 120, "qrData": "OTkwMDVCMDUwMDMyMTc4MTE0MjI4NDkwNS1kYjdjZWU3NC1hNTdjLTQxMjItODljZi1jZmEyYWNjMDkyZjgwNjAwMDQ3OTczMjAwMDEzQklEVklCQU5LX1RSQU5TX09UUA==" }, "confirmId": "TXNKEY_APPROVAL_25607354makerotv_a8993883-d5fe-4ced-a0c0-20cff5b5120b", "confirmUrl": null } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Bank BIN. Currently only 970418 (BIDV) is supported. The API uses the BIDV authorization session of the `Maker` role." }, "actionType": { "type": "string", "description": "Disbursement order type - `INTERNAL_TRANSFER`: Domestic transfer - `SALARY`: Salary payment - `BILL_PAYMENT`: Bill payment (payment list)" }, "transactionIds": { "type": "array", "items": {}, "description": "List of transaction IDs (in draft status `INIT`) to submit for approval. - `INTERNAL_TRANSFER`: the `records[].transactionId` value returned when you [Create a disbursement order](https://developers.tingee.vn/en/docs/direct-link/create-transfer-maker-checker) with `action = INIT` - `SALARY` / `BILL_PAYMENT`: the `data.transactionId` value (batch-level transaction ID)" } }, "required": [ "bankBin", "actionType", "transactionIds" ] }, "example": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "transactionIds": [ "PM0226061000074420" ] } } } } } }, "/v1/direct-link/confirm-transfer": { "put": { "tags": [ "Disbursement" ], "summary": "Confirm payment order", "description": "Authenticate and complete the approval request for a disbursement payment order you created\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/confirm-transfer", "operationId": "put_direct_link_confirm_transfer", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "successfulTransactions": [ { "transactionId": "PM2226061600075162", "amount": 101418, "currency": "VND", "feeAccountNumber": "8600007007", "transactionCode": "PM22", "effectiveDate": "2026-06-16", "processDate": "2026-06-16T11:20:19.448429323", "feeTotal": 27500, "feeMethod": "O", "remark": "Chuyen luong", "approvalNote": "", "originId": "8AFF13679AC48563911C4B50BA857E8E", "priority": true, "status": "PENDING_APPROVAL", "creditAccountType": "ACCOUNT", "creditAccountNumber": "2220366666", "creditAccountName": "TITLE 1 2220366666", "debitAccountNumber": "8600007007", "debitAccountName": "Title 1 8600007007" } ], "failedTransactions": [] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Bank BIN. Currently only 970418 (BIDV) is supported. The API uses the BIDV authorization session of the `Maker` role." }, "actionType": { "type": "string", "description": "Purpose of the disbursement order (must match the `actionType` used when creating the order) - `INTERNAL_TRANSFER`: Domestic transfer - `SALARY`: Salary payment - `BILL_PAYMENT`: Bill / statement payment" }, "confirmId": { "type": "string", "description": "Confirmation key, taken from `data.confirmId` of the [Create payment order](https://developers.tingee.vn/en/docs/direct-link/create-transfer-maker-checker) API (`action = REQUEST_APPROVAL`) or the [Submit payment order for approval](https://developers.tingee.vn/en/docs/direct-link/process-transaction) API (when `requireAuth = true`)." }, "otp": { "type": "string", "description": "Confirmation value (OTP / SmartOTP). Required for BIDV." } }, "required": [ "bankBin", "actionType", "confirmId" ] }, "example": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "confirmId": "TXNKEY_INIT_PM13_25607354makerotv_2827594e-037d-434b-b534-b1ff52adad4a", "otp": "123456" } } } } } }, "/v1/direct-link/approve-transfer": { "post": { "tags": [ "Disbursement" ], "summary": "Approve payment order", "description": "Approve a disbursement payment order (Checker)\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/approve-transfer", "operationId": "post_direct_link_approve_transfer", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "successfulTransactions": [], "failedTransactions": [], "requireAuth": true, "transAuth": { "authType": "SMARTOTP", "expTime": 120, "qrData": "OTkwMDVCMDUwMDMyMTc4MTE0MjI4NDkwNS1kYjdjZWU3NC1hNTdjLTQxMjItODljZi1jZmEyYWNjMDkyZjgwNjAwMDQ3OTczMjAwMDEzQklEVklCQU5LX1RSQU5TX09UUA==" }, "confirmId": "TXNKEY_APPROVAL_25607354makerotv_a8993883-d5fe-4ced-a0c0-20cff5b5120b", "confirmUrl": null } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Bank BIN. Currently only 970418 (BIDV) is supported. The API uses the BIDV authorization session of the `Checker` role." }, "actionType": { "type": "string", "description": "Disbursement order type - `INTERNAL_TRANSFER`: Domestic transfer - `SALARY`: Salary payment - `BILL_PAYMENT`: Bill / statement payment" }, "transactionIds": { "type": "array", "items": {}, "description": "List of pending transaction IDs to approve (the `id` field in the [Transaction inquiry](https://developers.tingee.vn/en/docs/direct-link/transaction-inquiry-maker-checker) result with `inquiryType = PENDING_APPROVAL_LIST`)." } }, "required": [ "bankBin", "actionType", "transactionIds" ] }, "example": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "transactionIds": [ "PM0226061000074420" ] } } } } } }, "/v1/direct-link/approve-confirm": { "put": { "tags": [ "Disbursement" ], "summary": "Confirm disbursement approval", "description": "Confirm the approval of a disbursement payment order (Checker)\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/approve-confirm", "operationId": "put_direct_link_approve_confirm", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "successfulTransactions": [ { "transactionId": "PM1326061500074977", "transactionType": "regular-out", "amount": 52525, "currency": "VND", "feeAccountNumber": "8600007007", "transactionCode": "PM13", "effectiveDate": "2026-06-15", "acceptedDate": null, "approvedDate": null, "processDate": "2026-06-15T14:54:25.985408353", "amountText": "Năm mươi hai nghìn năm trăm hai mươi lăm đồng", "feeAmount": 10000, "feeTotal": 11000, "feeVAT": 1000, "feeMethod": "O", "remark": "Thanh toan don hang", "originId": "TRANS_1506_A1", "priority": false, "status": "SUCCESS", "creditAccountType": "ACCOUNT", "creditAccountNumber": "123456789", "creditAccountName": "NGUYEN VAN A", "creditBankCode": "01202001", "creditBankName": "Ngân hàng Đầu tư và Phát triển Việt Nam", "creditBankShortName": "BIDV", "debitAccountNumber": "987654321", "debitAccountName": "CONG TY ABC" } ], "failedTransactions": [] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Bank BIN. Supports 970418 (BIDV, uses the authorization session of the `Checker` role) and 970448 (OCB)." }, "actionType": { "type": "string", "description": "Disbursement order type - `INTERNAL_TRANSFER`: Domestic transfer - `SALARY`: Salary payment - `BILL_PAYMENT`: Bill / statement payment" }, "confirmId": { "type": "string", "description": "Transaction confirmation key. For BIDV: the `data.confirmId` value returned by the [Approve payment order](https://developers.tingee.vn/en/docs/direct-link/approve-transfer) API (when `requireAuth = true`)." }, "otp": { "type": "string", "description": "OTP / SmartOTP generated by the bank app. Required for BIDV." }, "batchId": { "type": "string", "description": "Transaction batch ID. Required for OCB." } }, "required": [ "bankBin", "actionType", "confirmId" ] }, "example": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "confirmId": "TXNKEY_APPROVAL_25607354makerotv_a8993883-d5fe-4ced-a0c0-20cff5b5120b", "otp": "12345678" } } } } } }, "/v1/direct-link/reject-transaction": { "delete": { "tags": [ "Disbursement" ], "summary": "Reject a disbursement order", "description": "Reject approval of a disbursement order (Checker)\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/reject-transaction", "operationId": "delete_direct_link_reject_transaction", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "successfulTransactions": [ { "transactionId": "PM0226061000074420", "transactionType": "in-bank", "amount": 32987, "currency": "VND", "feeAccountNumber": "8600007007", "transactionCode": "PM02", "effectiveDate": "2026-06-10", "amountText": "Ba mươi hai nghìn chín trăm tám mươi bảy đồng", "feeTotal": 11000, "feeMethod": "O", "remark": "Chuyen tien", "originId": "TRANS_1006_A04", "priority": true, "status": "REJECTED", "creditAccountType": "ACCOUNT", "creditAccountNumber": "2220366666", "creditAccountName": "NGUYEN VAN A", "creditBankCode": "01202001", "creditBankShortName": "BIDV", "debitAccountNumber": "8600007007", "debitAccountName": "Title 1 8600007007" } ], "failedTransactions": [] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Bank BIN. Currently only 970418 (BIDV) is supported. The API uses the BIDV authorization session of the `Checker` role." }, "actionType": { "type": "string", "description": "Disbursement order type - `INTERNAL_TRANSFER`: Domestic transfer - `SALARY`: Salary payment - `BILL_PAYMENT`: Bill payment (payment list)" }, "transactionIds": { "type": "array", "items": {}, "description": "List of pending-approval transaction IDs to reject (the `id` field in the result of [Transaction inquiry](https://developers.tingee.vn/en/docs/direct-link/transaction-inquiry-maker-checker) with `inquiryType = PENDING_APPROVAL_LIST`)." }, "rejectReason": { "type": "string", "description": "Reason for rejection (if any)." } }, "required": [ "bankBin", "actionType", "transactionIds" ] }, "example": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "transactionIds": [ "PM0226061000074420" ], "rejectReason": "Thông tin không chính xác" } } } } } }, "/v1/direct-link/transaction-inquiry": { "post": { "tags": [ "Disbursement" ], "summary": "Query transaction list/details (BIDV)", "description": "Query the list and details of transactions in the Maker/Checker flow (BIDV).\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/transaction-inquiry-maker-checker\n\nSee also: https://developers.tingee.vn/en/docs/direct-link/transaction-inquiry-direct", "operationId": "post_direct_link_transaction_inquiry", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "enableUpdateName": false, "items": [ { "id": "6dbf35f0-99b2-4d63-8ab3-3027e8cc263d", "transactionType": "in-bank", "errorDescription": null, "debitAccountNumber": "8600007007", "amount": "32987", "currency": "VND", "remark": "Check1", "feeMethod": "O", "feeAccountNumber": "8600007007", "originId": "TRANS_1106_A04", "notAuthorized": false, "batchId": "2667c208-a5ab-4c9c-af4d-cbd4de24b817", "effectiveDate": "11/06/2026", "status": "VALID", "creditAccountType": "ACCOUNT", "creditAccountNumber": "2220366666", "creditAccountName": "TITLE 1 2220366666", "creditBankName": "Ngan hang TMCP Dau tu va Phat trien Viet Nam", "creditBranchCode": "222000" } ], "validRows": 1, "invalidRows": 0, "total": 1 } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Bank BIN (always `970418` - BIDV)." }, "actionType": { "type": "string", "description": "Operation type: - `INTERNAL_TRANSFER` - `SALARY` - `BILL_PAYMENT`" }, "inquiryType": { "type": "string", "description": "Inquiry type. Possible values: `PENDING_APPROVAL_LIST`: Get the list of transactions pending approval. (Always uses the authorization session of the `Checker` role).`MAKER_PENDING_LIST`: Get the list of transactions created by the Maker (draft / pending approval). (Always uses the authorization session of the `Maker` role).`FO_REPORT_LIST`: Summary report of the posting status of transactions. (Available to both `Maker` and `Checker`, according to `role`).`BATCH_UPLOAD_INQUIRY`: Query the child transaction records by `batchId` after uploading a batch disbursement order. (Always uses the authorization session of the `Maker` role).`TRANSFER_DETAIL`: View the posting details of a specific transaction by `id`. (Available to both `Maker` and `Checker`, according to `role`).`EDIT_TRANSFER_DETAIL`: Get a draft transaction by `id` for editing. For `INTERNAL_TRANSFER`, the transaction must have been created through TINGEE and still be in draft status. (Always uses the authorization session of the `Maker` role).The `BATCH_DETAIL` value does not apply to BIDV (it is only used for BaoKim — see [Transaction inquiry for the automatic disbursement flow](https://developers.tingee.vn/en/docs/direct-link/transaction-inquiry-direct))." }, "role": { "type": "string", "description": "Role (`Maker` / `Checker`). Determines which BIDV authorization session is used with `FO_REPORT_LIST` and `TRANSFER_DETAIL`." }, "id": { "type": "string", "description": "Transaction ID in the BIDV system (the `records[].transactionId` value when creating an `INTERNAL_TRANSFER` order, or `data.transactionId` for `SALARY` / `BILL_PAYMENT`; or the `id` field in the lists). Required when `inquiryType` is `TRANSFER_DETAIL` or `EDIT_TRANSFER_DETAIL`." }, "batchId": { "type": "string", "description": "Transaction batch ID (the `data.batchId` value returned when creating a batch payment order). Required when `inquiryType = BATCH_UPLOAD_INQUIRY`." }, "status": { "type": "string", "description": "Status to filter by. - For `BATCH_UPLOAD_INQUIRY`: `VALID` (valid record) or `INVALID` (invalid record) - For `FO_REPORT_LIST`, `MAKER_PENDING_LIST`: BIDV transaction status (the `status` value returned in `items`, e.g. `INIT`, `PENDING_APPROVAL`, `SUCCESS`)" }, "filter": { "type": "string", "description": "General search keyword. Applies to the list inquiry types and `BATCH_UPLOAD_INQUIRY`." }, "startDate": { "type": "string", "description": "Filter by creation date greater than or equal to the given value (format `YYYY-MM-DD`). Applies to: `FO_REPORT_LIST`, `MAKER_PENDING_LIST`; for `INTERNAL_TRANSFER` it also applies to `PENDING_APPROVAL_LIST`." }, "endDate": { "type": "string", "description": "Filter by creation date less than or equal to the given value (format `YYYY-MM-DD`). Applies the same way as `startDate`." }, "startEffectiveDate": { "type": "string", "description": "Filter by effective date greater than or equal to the given value (format `YYYY-MM-DD`). Applies to: `FO_REPORT_LIST`, `PENDING_APPROVAL_LIST`, `MAKER_PENDING_LIST`." }, "endEffectiveDate": { "type": "string", "description": "Filter by effective date less than or equal to the given value (format `YYYY-MM-DD`). Applies the same way as `startEffectiveDate`." }, "debitAccountNumber": { "type": "string", "description": "Filter by payment (debit) account number. Applies to: `FO_REPORT_LIST`, `PENDING_APPROVAL_LIST`, `MAKER_PENDING_LIST`." }, "receiverValue": { "type": "string", "description": "Filter by recipient information (account number / ID document number). Applies to: `PENDING_APPROVAL_LIST`, `MAKER_PENDING_LIST`; for `INTERNAL_TRANSFER` it also applies to `FO_REPORT_LIST`." }, "amountMin": { "type": "number", "description": "Filter by minimum amount. Applies to: `FO_REPORT_LIST`, `PENDING_APPROVAL_LIST`, `MAKER_PENDING_LIST`." }, "amountMax": { "type": "number", "description": "Filter by maximum amount. Applies the same way as `amountMin`." }, "currency": { "type": "string", "description": "Filter by currency (e.g. `VND`). Applies to: `FO_REPORT_LIST`, `PENDING_APPROVAL_LIST`, `MAKER_PENDING_LIST`." }, "channel": { "type": "array", "items": {}, "description": "Filter by the channel that created the transaction (e.g. `[\"ERP\"]`). Applies to: `FO_REPORT_LIST`, `PENDING_APPROVAL_LIST`, `MAKER_PENDING_LIST`." }, "batchNo": { "type": "string", "description": "Filter by BIDV batch number (`batchNo`). Applies to: `PENDING_APPROVAL_LIST`, `MAKER_PENDING_LIST`; for `INTERNAL_TRANSFER` it also applies to `FO_REPORT_LIST`." }, "receiverBankCode": { "type": "array", "items": {}, "description": "Filter by a list of receiving bank codes in CITAD format (e.g. `[\"01202001\"]`). Applies to: `PENDING_APPROVAL_LIST`, `MAKER_PENDING_LIST`; for `INTERNAL_TRANSFER` it also applies to `FO_REPORT_LIST`." }, "transactionType": { "type": "array", "items": {}, "description": "Filter by a list of transaction types, using BIDV codes: `I` (within BIDV), `O` (outside BIDV), `F` (247 fast transfer). Only applies to `INTERNAL_TRANSFER`: `FO_REPORT_LIST`, `PENDING_APPROVAL_LIST`, `MAKER_PENDING_LIST`." }, "coreRef": { "type": "string", "description": "Filter by the bank's core posting reference (core reference). Only applies to `INTERNAL_TRANSFER` + `FO_REPORT_LIST`." }, "createdBy": { "type": "string", "description": "Filter by the order creator (Maker username on BIDV). Applies to: `PENDING_APPROVAL_LIST`." }, "myTransfer": { "type": "string", "description": "Filter transactions created by the currently authorized user. Only applies to `INTERNAL_TRANSFER` + `MAKER_PENDING_LIST`." }, "validCreateDateRange": { "type": "boolean", "description": "Enable filtering by creation date range (`startDate` – `endDate`). Only applies to `INTERNAL_TRANSFER`: `PENDING_APPROVAL_LIST`, `MAKER_PENDING_LIST`." }, "validEffDateRange": { "type": "boolean", "description": "Enable filtering by effective date range (`startEffectiveDate` – `endEffectiveDate`). Applies the same way as `validCreateDateRange`." }, "amountRange": { "type": "boolean", "description": "Enable filtering by amount range (`amountMin` – `amountMax`). Applies the same way as `validCreateDateRange`." }, "skipCount": { "type": "number", "description": "Number of records to skip (pagination). For example, page 2 with 50 records per page: `skipCount = 50`. Pass a multiple of `maxResultCount` (the system converts it to a BIDV page number)." }, "maxResultCount": { "type": "number", "description": "Maximum number of records per page (default `10`, maximum `2000`)." } }, "required": [ "bankBin", "actionType", "inquiryType", "role" ] }, "examples": { "example1": { "summary": "BATCH_UPLOAD_INQUIRY", "value": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "inquiryType": "BATCH_UPLOAD_INQUIRY", "role": "Maker", "batchId": "2667c208-a5ab-4c9c-af4d-cbd4de24b817", "status": "VALID", "skipCount": 0, "maxResultCount": 50 } }, "example2": { "summary": "PENDING_APPROVAL_LIST", "value": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "inquiryType": "PENDING_APPROVAL_LIST", "role": "Checker", "skipCount": 0, "maxResultCount": 3 } }, "example3": { "summary": "MAKER_PENDING_LIST", "value": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "inquiryType": "MAKER_PENDING_LIST", "role": "Maker", "skipCount": 0, "maxResultCount": 3 } }, "example4": { "summary": "TRANSFER_DETAIL", "value": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "inquiryType": "TRANSFER_DETAIL", "role": "Maker", "id": "PM0226060400073501" } }, "example5": { "summary": "FO_REPORT_LIST", "value": { "bankBin": "970418", "actionType": "INTERNAL_TRANSFER", "inquiryType": "FO_REPORT_LIST", "role": "Maker", "startEffectiveDate": "2026-06-10", "endEffectiveDate": "2026-06-10", "skipCount": 0, "maxResultCount": 3 } } } } } } } }, "/v1/direct-link/financial-utility/transaction-log-inquiry": { "get": { "tags": [ "Disbursement" ], "summary": "Query the action history of a transaction", "description": "Lets partners query the action history of a specific transaction by ID (including actions such as submit for approval, approve, reject... and processing by the bank)\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/transaction-log-inquiry", "operationId": "get_direct_link_financial_utility_transaction_log_inquiry", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "items": [ { "id": 1, "transactionId": "TXN001", "transactionCode": "CT", "logType": "INIT", "logTypeDesc": "Khởi tạo", "status": "SUCCESS", "statusDesc": "Thành công", "createdDate": "2025-01-01 10:00:00", "createdBy": "system", "channel": "API", "appcode": "TINGEE", "source": "PARTNER", "logNote": "" } ], "total": 1 } } } } } }, "parameters": [ { "name": "bankBin", "in": "query", "required": true, "description": "Bank BIN. Currently only 970418 (BIDV) is supported.", "schema": { "type": "string" }, "example": "970418" }, { "name": "role", "in": "query", "required": false, "description": "User role: `Maker` or `Checker` (uses the BIDV authorization session of that role). Required for BIDV.", "schema": { "type": "string" }, "example": "Maker" }, { "name": "transactionCode", "in": "query", "required": true, "description": "BIDV transaction type code (e.g. `PM02`) — taken from the transaction's `transactionCode` field.", "schema": { "type": "string" }, "example": "PM02" }, { "name": "transactionId", "in": "query", "required": true, "description": "BIDV transaction ID — taken from the `transactionId` field in the result of [Transaction inquiry](https://developers.tingee.vn/en/docs/direct-link/transaction-inquiry-maker-checker) (`TRANSFER_DETAIL`, `FO_REPORT_LIST`).", "schema": { "type": "string" }, "example": "TRANS_001" } ] } }, "/v1/direct-link/financial-utility/get-domestic-bank-list": { "get": { "tags": [ "Disbursement" ], "summary": "Get recipient banks", "description": "Get the list of recipient banks used when creating disbursement payment orders\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/get-domestic-bank-list", "operationId": "get_direct_link_financial_utility_get_domestic_bank_list", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "items": [ { "code": "01202001", "bin": "970418", "externalBankCode": "01202001", "name": "NHTMCP DTPT VN-HOI SO CHINH-HA NOI (BIDV)", "shortName": "Ngan hang TMCP Dau tu va Phat trien Viet Nam", "abbreName": "BIDV", "nameEn": "bidv", "transferType": "NORMAL", "bankLogoUrl": "https://www.bidv.net/bidvdirectuat/media/logobank/01202001.png" } ], "total": 1 } } } } } }, "parameters": [ { "name": "listTypeTransfer", "in": "query", "required": false, "description": "Filter recipient banks by transfer type - 1: NAPAS 247 fast transfer - 0: Standard interbank transfer - 2: Both types Required for BIDV (the API currently only supports BIDV).", "schema": { "type": "number" }, "example": "1" }, { "name": "bankBin", "in": "query", "required": true, "description": "BIN of the sending bank. Currently only 970418 (BIDV) is supported.", "schema": { "type": "string" }, "example": "970418" }, { "name": "role", "in": "query", "required": false, "description": "User role: `Maker` or `Checker` (uses the BIDV authorization session of that role). Required for BIDV.", "schema": { "type": "string" }, "example": "Maker" } ] } }, "/v1/direct-link/bank-branches": { "get": { "tags": [ "Disbursement" ], "summary": "Get bank branches", "description": "List of recipient bank branches used when creating disbursement payment orders\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/bank-branches", "operationId": "get_direct_link_bank_branches", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": [ { "id": 355, "creationTime": "2026-01-15T03:20:11.000Z", "creatorUserId": null, "bankCode": "01202001", "bankBranchName": "NHTMCP DTPT VN-HOI SO CHINH-HA NOI (BIDV)", "bankBranchCode": "01202001" } ] } } } } }, "parameters": [ { "name": "bankBin", "in": "query", "required": true, "description": "Bank BIN. Currently only 970418 (BIDV) is supported — the API returns the list of BIDV branches, used for the `creditBranchCode` field when creating a BIDV disbursement payment order.", "schema": { "type": "string" }, "example": "970418" } ] } }, "/v1/direct-link/batch-result-download": { "get": { "tags": [ "Disbursement" ], "summary": "Export transaction results to Excel", "description": "Download the batch processing result file\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/batch-result-download", "operationId": "get_direct_link_batch_result_download", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "url": "https://storage.tingee.vn/downloads/batch_result_123.xlsx", "name": "batch_result_123.xlsx" } } } } } }, "parameters": [ { "name": "batchId", "in": "query", "required": true, "description": "Transaction batch ID — the `data.batchId` value returned by the [Create payment order](https://developers.tingee.vn/en/docs/direct-link/create-transfer-maker-checker) API when you create an `INTERNAL_TRANSFER` batch order.", "schema": { "type": "string" }, "example": "YOUR_BATCH_ID" }, { "name": "bankBin", "in": "query", "required": true, "description": "Bank BIN. Currently only 970418 (BIDV) is supported. The API uses the BIDV authorization session of the `Maker` role.", "schema": { "type": "string" }, "example": "970418" } ] } }, "/v1/direct-link/financial-utility/account-inquiry": { "get": { "tags": [ "Disbursement" ], "summary": "Beneficiary inquiry (BIDV, VietinBank, BaoKim)", "description": "Look up the beneficiary account information\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/account-inquiry", "operationId": "get_direct_link_financial_utility_account_inquiry", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "creditAccountNumber": "1234567890", "creditAccountName": "NGUYEN VAN A", "creditBankBin": "970418" } } } } } }, "parameters": [ { "name": "bankBin", "in": "query", "required": true, "description": "BIN of the bank that performs the inquiry. Pass 970418 (BIDV), 970415 (VietinBank) or BAOKIM (BaoKim).", "schema": { "type": "string" }, "example": "970418" }, { "name": "creditAccountNumber", "in": "query", "required": true, "description": "Beneficiary account number / card number / wallet number to look up.", "schema": { "type": "string" }, "example": "1234567890" }, { "name": "creditBankBin", "in": "query", "required": false, "description": "Beneficiary bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks). Required, except for BAOKIM with `accountType = WALLET`.", "schema": { "type": "string" }, "example": "970418" }, { "name": "creditBankBranchCode", "in": "query", "required": false, "description": "Beneficiary bank branch code. Only applies to VietinBank.", "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "description": "User role: `Maker` or `Checker`. Required for BIDV.", "schema": { "type": "string" }, "example": "Maker" }, { "name": "accountType", "in": "query", "required": false, "description": "Beneficiary account type (only applies to BAOKIM): - `ACCOUNT`: Bank account number - `CARD`: Card number - `WALLET`: BaoKim wallet (`creditBankBin` not needed) The values `ID` and `PHONE` are also accepted and handled as `ACCOUNT`. Required for BAOKIM.", "schema": { "type": "string" } }, { "name": "walletId", "in": "query", "required": false, "description": "Username of the business's BaoKim wallet linked to TINGEE (the wallet used for the lookup). Required for BAOKIM.", "schema": { "type": "string" } } ] } }, "/v1/direct-link/financial-utility/account-balance-detail": { "get": { "tags": [ "Disbursement" ], "summary": "Get financial account details", "description": "Account balance details\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/account-balance-detail", "operationId": "get_direct_link_financial_utility_account_balance_detail", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "accountNumber": "1234567890", "accountName": "NGUYEN VAN A", "status": "ACTIVE", "cif": "12345678", "branchCode": "001", "currency": "VND", "holdBalance": 0, "minBalance": 50000, "overdraftBalance": 0, "availableBalance": 10000000, "acctRelation": "OWNER", "currentBalance": 10050000, "maturityDate": "", "parentBoo": "HO", "boo": "001", "productCode": "CA01", "purposeCode": "001", "default": true } } } } } }, "parameters": [ { "name": "bankBin", "in": "query", "required": true, "description": "Bank BIN. Currently only 970418 (BIDV) is supported.", "schema": { "type": "string" }, "example": "970418" }, { "name": "role", "in": "query", "required": false, "description": "User role: `Maker` or `Checker` (uses the BIDV authorization session of that role). Required for BIDV.", "schema": { "type": "string" }, "example": "Maker" }, { "name": "accountNumber", "in": "query", "required": true, "description": "BIDV payment account number to query (owned by the authorizing business).", "schema": { "type": "string" }, "example": "1234567890" } ] } }, "/v1/direct-link/financial-utility/validate-charge-account": { "post": { "tags": [ "Disbursement" ], "summary": "Check fee account information", "description": "Validate the fee account\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/validate-charge-account", "operationId": "post_direct_link_financial_utility_validate_charge_account", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "currentBalance": 10000000, "feeCcy": "VND", "accountType": "PAYMENT", "status": "ACTIVE", "availableBalance": 9500000, "minBalance": 50000, "accountNumber": "1234567890" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bankBin": { "type": "string", "description": "Bank BIN. Currently only 970418 (BIDV) is supported. The API uses the BIDV authorization session of the `Maker` role." }, "accountNumber": { "type": "string", "description": "Fee account number to check." }, "cif": { "type": "string", "description": "Customer number (Customer Information File)" } }, "required": [ "bankBin", "accountNumber" ] }, "example": { "bankBin": "970418", "accountNumber": "1234567890", "cif": "12345678" } } } } } }, "/v1/direct-link/account-statement/payment-account-detail": { "get": { "tags": [ "Disbursement" ], "summary": "Payment account details", "description": "Query the information and balance of a payment account (BIDV, VietinBank)\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/payment-detail", "operationId": "get_direct_link_account_statement_payment_account_detail", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "accountNumber": "1234567890", "accountName": "NGUYEN VAN A", "status": "ACTIVE", "currency": "VND", "branchName": "CN Hà Nội", "availableBalance": 10000000, "balance": 10050000 } } } } } }, "parameters": [ { "name": "bankBin", "in": "query", "required": true, "description": "Bank BIN. Supports 970418 (BIDV) and 970415 (VietinBank).", "schema": { "type": "string" }, "example": "970418" }, { "name": "role", "in": "query", "required": false, "description": "User role: `Maker` or `Checker` (uses the BIDV authorization session of that role). Required for BIDV.", "schema": { "type": "string" }, "example": "Maker" }, { "name": "accountNumber", "in": "query", "required": true, "description": "Payment account number to query.", "schema": { "type": "string" }, "example": "1234567890" } ] } }, "/v1/direct-link/account-statement/payment-transaction-history": { "get": { "tags": [ "Disbursement" ], "summary": "Payment account transaction history", "description": "Payment transaction history\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/payment-transaction-history", "operationId": "get_direct_link_account_statement_payment_transaction_history", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "items": [ { "coreRefNo": "REF001", "transTime": "2025-01-01 10:00:00", "debitAmount": 1000000, "creditAmount": 0, "remark": "Thanh toan hoa don", "nextRUNBAL": "9000000", "postingDate": "2025-01-01", "postingOrder": "001", "moreRecordIndicator": "N" } ], "total": 1 } } } } } }, "parameters": [ { "name": "bankBin", "in": "query", "required": true, "description": "Bank BIN. Currently only 970418 (BIDV) is supported.", "schema": { "type": "string" }, "example": "970418" }, { "name": "role", "in": "query", "required": true, "description": "User role: `Maker` or `Checker` (uses the BIDV authorization session of that role).", "schema": { "type": "string" }, "example": "Maker" }, { "name": "accountNumber", "in": "query", "required": true, "description": "Payment account number to get the transaction history for.", "schema": { "type": "string" }, "example": "1234567890" }, { "name": "startDate", "in": "query", "required": false, "description": "Search start time (yyyy-MM-dd)", "schema": { "type": "string" }, "example": "2025-11-01" }, { "name": "endDate", "in": "query", "required": false, "description": "Search end time (yyyy-MM-dd)", "schema": { "type": "string" }, "example": "2025-11-10" }, { "name": "moreRecordIndicator", "in": "query", "required": false, "description": "Pagination key: pass back the `moreRecordIndicator` value of the last record on the previous page to get the next page.", "schema": { "type": "string" } }, { "name": "postingDate", "in": "query", "required": false, "description": "Pagination key: pass back the `postingDate` value of the last record on the previous page.", "schema": { "type": "string" } }, { "name": "postingOrder", "in": "query", "required": false, "description": "Pagination key: pass back the `postingOrder` value of the last record on the previous page.", "schema": { "type": "string" } }, { "name": "balanceAfterTxn", "in": "query", "required": false, "description": "Pagination key: pass back the `nextRUNBAL` value (balance after the transaction) of the last record on the previous page.", "schema": { "type": "string" } }, { "name": "totalRecords", "in": "query", "required": false, "description": "Number of records to get per query.", "schema": { "type": "number" } } ] } }, "/v1/device/read-security-code": { "post": { "tags": [ "Devices & Hardware" ], "summary": "Have the device read out its security code (Read Security Code)", "description": "Send a command so that the TINGEEBOX device (identified by UUID) reads its security code aloud, for the step that links the device to a shop.\n\nDocumentation: https://developers.tingee.vn/en/docs/tingee-box/read-security-code", "operationId": "post_device_read_security_code", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "uuid": { "type": "string", "description": "Unique device identifier (Device UUID). If the device is already linked, it must belong to the calling Merchant (or the `merchantId` passed)." } }, "required": [ "uuid" ] }, "example": { "uuid": "DEVICE-001" } } } } } }, "/v1/device/read-amount-link-to-merchant": { "post": { "tags": [ "Devices & Hardware" ], "summary": "Read an amount aloud on the device", "description": "Send a command to the TingeeBox device to read out the amount.\n\nDocumentation: https://developers.tingee.vn/en/docs/tingee-box/read-amount", "operationId": "post_device_read_amount_link_to_merchant", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "uuid": { "type": "string", "description": "Device identifier (the device must be linked to the Merchant)." }, "transactionId": { "type": "string", "description": "ID of the transaction whose amount is read out." }, "amount": { "type": "number", "description": "Transaction amount (VND)." }, "bankBin": { "type": "string", "description": "Bank BIN of the transaction. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks). If the device is locked to a bank, it only reads the amount when `bankBin` belongs to the locked bank." }, "firstDisplayText": { "type": "string", "description": "Accompanying display text (line 1)." }, "secondDisplayText": { "type": "string", "description": "Accompanying display text (line 2)." }, "thirdDisplayText": { "type": "string", "description": "Accompanying display text (line 3)." }, "playSound": { "type": "boolean", "description": "`true` to play a \"ting ting\" sound before reading the amount (Sacombank `970403` and VIB `970441` transactions always include this sound)." }, "isPrint": { "type": "boolean", "description": "Also print a receipt when reading the amount (for TINGEE MAX devices). Default `false`." }, "printData": { "type": "object", "description": "Receipt print data, required when `isPrint = true` (ignored when `isPrint` is not `true`). [See the printData structure](#cấu-trúc-printdata)" } }, "required": [ "uuid", "transactionId", "amount" ] }, "example": { "uuid": "DEVICE-001", "transactionId": "TX123456", "amount": 150000, "bankBin": "970422" } } } } } }, "/v1/device/print-receipt": { "post": { "tags": [ "Devices & Hardware" ], "summary": "Print a receipt from the device", "description": "Send a print receipt command to a Tingee Box MAX device.\n\nDocumentation: https://developers.tingee.vn/en/docs/tingee-box/print-receipt", "operationId": "post_device_print_receipt", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "uuid": "DEVICE-001" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Device identifier (the device must be linked to the Merchant)." }, "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "templateType": { "type": "number", "description": "Receipt template: - `1`: Simple retail - `2`: Detailed sales Default `1`." }, "lineWidth": { "type": "number", "description": "Print line width (number of characters), from `20` to `80`. Default `30`." }, "qrAlignment": { "type": "number", "description": "QR code alignment: `0` (Left), `1` (Center), `2` (Right). Default `1`." }, "logo": { "type": "string", "description": "Name of a logo preloaded on the device. Valid values: `printer_receipt_logo`, `printer_receipt_logo2`, `printer_receipt_logo3`, `printer_receipt_logo4`. If omitted, no logo is printed." }, "copies": { "type": "number", "description": "Number of copies to print, from `1` to `9`. Default `1`. Applies to: template 1." }, "voiceFile": { "type": "number", "description": "Notification sound file, from `1` to `6` (`1`–`5`: `noti_voice1-5.mp3`, `6`: print only, no sound). Default `1`." }, "title": { "type": "string", "description": "Receipt title (max 100 characters), printed in uppercase. If omitted, the template's default title is used." }, "storeName": { "type": "string", "description": "Store name (max 100 characters)." }, "branchName": { "type": "string", "description": "Branch name (max 100 characters). Applies to: template 1." }, "address": { "type": "string", "description": "Store address (max 200 characters). Applies to: template 1." }, "hotline": { "type": "string", "description": "Phone number / hotline (max 20 characters). Applies to: template 1." }, "sellerAddressLines": { "type": "array", "items": {}, "description": "Seller address lines; each element is printed on its own line. Applies to: template 2." }, "taxCode": { "type": "string", "description": "Store tax code (max 50 characters). Applies to: template 2." }, "orderCode": { "type": "string", "description": "Order code / waybill code (max 50 characters). Printed as the receipt number when `invoiceNo` is not passed." }, "invoiceNo": { "type": "string", "description": "Receipt number (max 50 characters)." }, "createdAt": { "type": "string", "description": "Receipt creation time (ISO 8601, e.g. `2026-10-14T15:30:00+07:00`), printed as `dd/MM/yyyy HH:mm`. Defaults to the time of the API call." }, "channelName": { "type": "string", "description": "Sales channel (max 50 characters, e.g. `Bán tại quầy`, `App`). Applies to: template 2." }, "employeeCode": { "type": "string", "description": "Sales employee code (max 20 characters). Applies to: template 2." }, "customerName": { "type": "string", "description": "Customer name (max 100 characters)." }, "customerId": { "type": "string", "description": "Customer code (max 50 characters). Applies to: template 2." }, "items": { "type": "array", "items": {}, "description": "List of products. [See the `items` element structure](#cấu-trúc-phần-tử-items)." }, "totalAmount": { "type": "number", "description": "Total amount (VND), minimum `0`. Note: this value is not printed; the total on the receipt is calculated by the system from `items`." }, "discount": { "type": "number", "description": "Discount on the whole receipt (VND), minimum `0`. Default `0`." }, "vatReduction": { "type": "number", "description": "VAT reduction (VND), minimum `0`." }, "invoiceStage": { "type": "string", "description": "Receipt stage: - `PRE_PAYMENT`: Provisional bill (before payment) - `POST_PAYMENT`: Receipt (after payment) Default `POST_PAYMENT`." }, "paidAmount": { "type": "number", "description": "Amount tendered by the customer (VND), minimum `0`. Applies to: template 1, when `invoiceStage = POST_PAYMENT`." }, "customerPaid": { "type": "number", "description": "Amount tendered by the customer (VND), minimum `0`. If omitted, it equals the amount due. Applies to: template 2, when `invoiceStage = POST_PAYMENT`." }, "paymentMethodLabel": { "type": "string", "description": "Payment method label (max 30 characters, e.g. `Tiền mặt`, `Chuyển khoản`). Template 2 defaults to `Tiền mặt`. Applies to: when `invoiceStage = POST_PAYMENT`." }, "paymentAmount": { "type": "number", "description": "Actual payment amount (VND), minimum `0`, printed next to `paymentMethodLabel`. If omitted, `customerPaid` or the amount due is used. Applies to: template 2, when `invoiceStage = POST_PAYMENT`." }, "changeAmount": { "type": "number", "description": "Change returned to the customer (VND), minimum `0`. Applies to: when `invoiceStage = POST_PAYMENT`." }, "note": { "type": "string", "description": "Receipt note (max 200 characters). Applies to: template 1." }, "qrCode": { "type": "string", "description": "Content of the QR code printed on the receipt (max 500 characters)." }, "qrHint": { "type": "string", "description": "Message shown with the QR code, e.g. scanning instructions (max 500 characters). Applies to: when `invoiceStage = PRE_PAYMENT` (template 1 also requires `qrCode`)." }, "bankAccountName": { "type": "string", "description": "Receiving account holder name (max 50 characters). Applies to: template 1, when `invoiceStage = PRE_PAYMENT`." }, "bankAccountNo": { "type": "string", "description": "Receiving account number (max 100 characters). Applies to: template 1, when `invoiceStage = PRE_PAYMENT`." }, "bankName": { "type": "string", "description": "Receiving bank name (max 50 characters, e.g. `MBB`, `VCB`). Applies to: template 1, when `invoiceStage = PRE_PAYMENT`." }, "barcode": { "type": "string", "description": "Code128 barcode (max 20 characters). Note: not printed on the receipt yet." }, "footerNote": { "type": "string", "description": "Note / thank-you message at the bottom of the receipt (max 200 characters)." } }, "required": [ "uuid", "storeName", "items", "totalAmount" ] }, "example": { "uuid": "DEVICE-001", "copies": 1, "storeName": "Cửa hàng tiện lợi", "orderCode": "DH123456", "totalAmount": 150000, "items": [ { "name": "Sản phẩm A", "quantity": 1, "unitPrice": 100000 }, { "name": "Sản phẩm B", "quantity": 1, "unitPrice": 50000 } ], "voiceFile": 6 } } } } } }, "/v1/device/show-dynamic-qr-code": { "post": { "tags": [ "Devices & Hardware" ], "summary": "Show QR Code", "description": "Send a dynamic QR code to the TINGEEBOX device to show to customers.\n\nDocumentation: https://developers.tingee.vn/en/docs/tingee-box/show-qr-code", "operationId": "post_device_show_dynamic_qr_code", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "uuid": { "type": "string", "description": "Device code. Pass `uuid`, or the trio `bankBin` (or `bankName`) + `vaAccountNumber` + `deviceType` so the system finds the devices attached to the account (via the account or the shop that contains it). When `uuid` is passed, `vaAccountNumber`, `bankBin`, `bankName` and `deviceType` are ignored. Currently only TingeeBox 6XS and TingeeBox 3LS devices can show QR codes." }, "vaAccountNumber": { "type": "string", "description": "VA account number or identification account. Required when `uuid` is not passed." }, "amount": { "type": "number", "description": "Amount to pay (VND)." }, "qrCode": { "type": "string", "description": "Dynamic QR Code string (Dynamic QR)." }, "bankBin": { "type": "string", "description": "Bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks). When `uuid` is not passed, you must pass `bankBin` or `bankName`." }, "bankName": { "type": "string", "description": "Bank name (per `BankNameEnum`): `OCB`, `BIDV`, `MBB`, `ACB`, `VPB`, `PGB`, `VIB`, `STB`, `CTG`, `VCB`, `AGRIBANK`, `SHINHAN`, `COB`, `MSB`, `NEXTPAY`, `PAYOO`, `BAOKIM`, `TPB`. When `uuid` is not passed, you must pass `bankBin` or `bankName`; if `bankBin` is passed, `bankName` is derived from `bankBin`." }, "deviceType": { "type": "string", "description": "Type of device to show the QR on: `tingee-box-6xs` or `tingee-box-3ls`. Required when `uuid` is not passed." }, "firstText": { "type": "string", "description": "Text shown with the QR (line 1)." }, "secondText": { "type": "string", "description": "Text shown with the QR (line 2)." }, "thirdText": { "type": "string", "description": "Text shown with the QR (line 3)." }, "showTime": { "type": "number", "description": "How long the QR is shown on the screen (seconds). Default `90`. Applies to TingeeBox 6XS (TingeeBox 3LS always shows it for 30 seconds)." }, "isStaticQr": { "type": "boolean", "description": "`true`: show it as a static QR (equivalent to the static QR API). Default `false` (dynamic QR)." }, "playSound": { "type": "boolean", "description": "`true` to play a beep when showing the QR." } }, "required": [ "amount", "qrCode" ] }, "example": { "vaAccountNumber": "V1T123456789", "amount": 150000, "qrCode": "00020101021138580010A000000727...", "bankBin": "970422", "deviceType": "tingee-box-3ls" } } } } } }, "/v1/device/show-static-qr-code": { "post": { "tags": [ "Devices & Hardware" ], "summary": "Show QR Code", "description": "Send a static QR code to the TINGEEBOX device to show to customers.\n\nDocumentation: https://developers.tingee.vn/en/docs/tingee-box/show-qr-code", "operationId": "post_device_show_static_qr_code", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "uuid": { "type": "string", "description": "Device code. Pass `uuid`, or the trio `bankBin` (or `bankName`) + `vaAccountNumber` + `deviceType` so the system finds the devices attached to the account (via the account or the shop that contains it). When `uuid` is passed, `vaAccountNumber`, `bankBin`, `bankName` and `deviceType` are ignored. Currently only TingeeBox 6XS and TingeeBox 3LS devices can show QR codes." }, "vaAccountNumber": { "type": "string", "description": "VA account number or identification account. Required when `uuid` is not passed." }, "amount": { "type": "number", "description": "Amount to pay (VND)." }, "qrCode": { "type": "string", "description": "Static QR Code string (VietQR)." }, "bankBin": { "type": "string", "description": "Bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks). When `uuid` is not passed, you must pass `bankBin` or `bankName`." }, "bankName": { "type": "string", "description": "Bank name (per `BankNameEnum`): `OCB`, `BIDV`, `MBB`, `ACB`, `VPB`, `PGB`, `VIB`, `STB`, `CTG`, `VCB`, `AGRIBANK`, `SHINHAN`, `COB`, `MSB`, `NEXTPAY`, `PAYOO`, `BAOKIM`, `TPB`. When `uuid` is not passed, you must pass `bankBin` or `bankName`; if `bankBin` is passed, `bankName` is derived from `bankBin`." }, "deviceType": { "type": "string", "description": "Type of device to show the QR on: `tingee-box-6xs` or `tingee-box-3ls`. Required when `uuid` is not passed." }, "firstText": { "type": "string", "description": "Text shown with the QR (line 1)." }, "secondText": { "type": "string", "description": "Text shown with the QR (line 2)." }, "thirdText": { "type": "string", "description": "Text shown with the QR (line 3)." }, "showTime": { "type": "number", "description": "Has no effect for static QR (TingeeBox 6XS saves the static QR as its idle screen)." }, "playSound": { "type": "boolean", "description": "Has no effect for static QR." } }, "required": [ "amount", "qrCode" ] }, "example": { "vaAccountNumber": "V1T123456789", "amount": 150000, "qrCode": "00020101021138580010A00000072701240006970422011001234567890208QRIBFTTA5204541153037045802VN62180814Thanh toan don6304CA68", "bankBin": "970422", "deviceType": "tingee-box-3ls" } } } } } }, "/v1/device/generate-and-show-dynamic-qr-code": { "post": { "tags": [ "Devices & Hardware" ], "summary": "Create and show QR", "description": "Create a dynamic QR Code and show it on the TINGEEBOX device right away for customers to scan and pay.\n\nDocumentation: https://developers.tingee.vn/en/docs/tingee-box/generate-and-show-dynamic-qr-code", "operationId": "post_device_generate_and_show_dynamic_qr_code", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "qrCode": "00020101021238570010A...", "qrAccount": "V1T123456789", "billId": "BILL_20251110_001" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "uuid": { "type": "string", "description": "Device code (the device must be linked to the Merchant)." }, "qrCodeType": { "type": "string", "description": "Dynamic QR type: - `dynamic-one-time-payment`: QR that can be paid only once. - `dynamic-recurring-payment`: QR that can be paid multiple times." }, "vaAccountNumber": { "type": "string", "description": "Virtual account number (max 50 characters)." }, "amount": { "type": "number", "description": "Bill amount (VND), minimum `1`." }, "purpose": { "type": "string", "description": "Payment description." }, "bankBin": { "type": "string", "description": "Bank BIN. See [Supported banks](https://developers.tingee.vn/en/docs/banking/get-banks)." }, "bankName": { "type": "string", "description": "Bank name: `OCB`, `BIDV`, `MBB`, `ACB`, `VPB`, `PGB`, `VIB`, `STB`, `CTG`, `VCB`, `AGRIBANK`, `SHINHAN`, `COB`, `MSB`, `NEXTPAY`, `PAYOO`, `BAOKIM`, `TPB`. When `bankBin` is passed, the system derives `bankName` from `bankBin`. QR creation is based on `bankBin`, so always pass `bankBin`." }, "name": { "type": "string", "description": "QR display name. Only applies to the BAOKIM e-wallet; if omitted, the account holder name is used." }, "expireInMinute": { "type": "number", "description": "QR validity period (minutes), from `1` to `43200` (30 days). Default `43200`. Required for OCB (`970448`)." }, "extraInfo": { "type": "string", "description": "Extra information when creating the QR, max 200 characters (e.g. the partner's bill code)." }, "deviceType": { "type": "string", "description": "Device type. No need to pass it — the system determines it from `uuid`." }, "firstText": { "type": "string", "description": "Text shown with the QR (line 1)." }, "secondText": { "type": "string", "description": "Text shown with the QR (line 2). Defaults to the `qrAccount` of the newly created QR." }, "thirdText": { "type": "string", "description": "Text shown with the QR (line 3)." }, "showTime": { "type": "number", "description": "How long the QR is shown on the speaker (seconds). Default `90` seconds." }, "playSound": { "type": "boolean", "description": "Play a beep when showing the QR. - `true`: With a beep. - `false`/omitted: No beep." }, "readAmountAfterPay": { "type": "boolean", "description": "Read the amount aloud after a successful payment. - `true`: The speaker reads the amount automatically. - `false`/omitted: The partner calls the read amount API to play it on the speaker." } }, "required": [ "uuid", "qrCodeType", "vaAccountNumber", "amount", "bankBin" ] }, "example": { "uuid": "DEVICE_UUID", "qrCodeType": "dynamic-one-time-payment", "vaAccountNumber": "V1T123456789", "amount": 150000, "purpose": "Thanh toan don hang #001", "bankBin": "970422", "expireInMinute": 5, "firstText": "Quan ABC", "showTime": 30, "playSound": true, "readAmountAfterPay": true } } } } } }, "/v1/device/add-device-to-shop": { "post": { "tags": [ "Devices & Hardware" ], "summary": "Add a device to a shop (Add Device To Shop)", "description": "Link a new TINGEEBOX device to the Merchant's management system.\n\nDocumentation: https://developers.tingee.vn/en/docs/tingee-box/add-device-to-shop", "operationId": "post_device_add_device_to_shop", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": [ { "type": "tingee-box-3ls", "uuid": "DEVICE-001" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "uuid": { "type": "string", "description": "Unique device identifier (max 50 characters)." }, "securityCode": { "type": "string", "description": "Device security code (max 100 characters). Call [Read out security code](https://developers.tingee.vn/en/docs/tingee-box/read-security-code) so the device reads the code aloud, then pass the code the user heard." }, "vaAccountNumbers": { "type": "array", "items": {}, "description": "List of VA account numbers; the device is linked to the shops that contain these accounts. Required if `shopIds` is not passed; ignored when `shopIds` is passed." }, "shopIds": { "type": "array", "items": {}, "description": "List of shop IDs to link (Required if `vaAccountNumbers` is not passed)." }, "appType": { "type": "string", "description": "Integration platform (per `AppTypeEnum`): `baas`, `ocb-web`, `ocb-app`, `bidv-web`, `bidv-app`, `stb-web`, `stb-app`, `vcb-web`, `vcb-app`, `tingee-web`, `tingee-app`, `tingee-merchant-app`, `TingeeMerchant`, `loa-hub`, `mini-app-mbb`, `mini-app-zalo`. The device type must be allowed on this platform in TINGEE's configuration. Open API partners usually pass `baas` (or the value TINGEE provides when issuing the account)." } }, "required": [ "uuid", "securityCode", "appType" ] }, "example": { "uuid": "DEVICE-001", "securityCode": "ABC123XYZ", "shopIds": [ 12 ], "appType": "ocb-web", "vaAccountNumbers": [ "123456789" ] } } } } } }, "/v1/device/update-shop-device-link-status": { "post": { "tags": [ "Devices & Hardware" ], "summary": "Update the device-to-shop link status", "description": "Update the list of shops whose transactions the TINGEEBOX device is allowed to show.\n\nDocumentation: https://developers.tingee.vn/en/docs/tingee-box/update-shop-device-link-status", "operationId": "post_device_update_shop_device_link_status", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "uuid": { "type": "string", "description": "Unique device identifier (the device must be linked to the Merchant)." }, "type": { "type": "string", "description": "Device type (per `DeviceTypeEnum`, e.g. `tingee-box-3ls`). No need to pass it — the system determines it from `uuid`." }, "appType": { "type": "string", "description": "Integration platform (per `AppTypeEnum`): `baas`, `ocb-web`, `ocb-app`, `bidv-web`, `bidv-app`, `stb-web`, `stb-app`, `vcb-web`, `vcb-app`, `tingee-web`, `tingee-app`, `tingee-merchant-app`, `TingeeMerchant`, `loa-hub`, `mini-app-mbb`, `mini-app-zalo`. The device type must be allowed on this platform in TINGEE's configuration. Open API partners usually pass `baas` (or the value TINGEE provides when issuing the account)." }, "shopsLinkToDeviceDtos": { "type": "array", "items": {}, "description": "List of shops whose link status to update. [See details](#chi-tiết-shopslinktodevicedtos)." } }, "required": [ "uuid", "appType", "shopsLinkToDeviceDtos" ] }, "example": { "uuid": "DEVICE-001", "type": "app-tingee", "appType": "ocb-web", "shopsLinkToDeviceDtos": [ { "shopName": "Shop Demo", "shopId": 101, "isLinkToDevice": true, "fullAddress": "123 Main St", "vaAccountNumber": "123456789" } ] } } } } } }, "/v1/device/get-paging": { "post": { "tags": [ "Devices & Hardware" ], "summary": "List devices", "description": "Query a Merchant's devices with full details.\n\nDocumentation: https://developers.tingee.vn/en/docs/tingee-box/get-paging", "operationId": "post_device_get_paging", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "totalCount": 1, "items": [ { "id": 1001, "type": "tingee-box-3pro", "uuid": "3PRO123456", "name": "TINGEEBOX PRO 01", "system": null, "systemVersion": null, "merchantId": 123456, "masterMerchantId": 1000, "merchantPhoneNumber": "0901234567", "employeeName": null, "status": "approved", "useDate": "2025-01-01T10:00:00.000Z", "expirationDate": "2026-01-01T10:00:00.000Z", "warrantyDate": "2026-01-01T10:00:00.000Z", "selectedBankNames": [ "MBB" ], "securityCode": "123456", "creationTime": "2024-12-20T08:00:00.000Z", "assignedAgentId": null, "simSerialNumber": null, "simPhoneNumber": null, "simProvider": null, "simPlan": null, "simExpirationDate": null, "simActivationDate": null, "shopDtos": [ { "id": 101, "name": "Cửa hàng ABC" } ], "merchantName": "Merchant ABC" } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "type": "string", "description": "Keyword for partial matching on device name, device code (`uuid`), Merchant phone number or employee name." }, "skipCount": { "type": "number", "description": "Number of records to skip (pagination), minimum `0`." }, "maxResultCount": { "type": "number", "description": "Maximum number of records per page, from `1` to `2000` (larger values are capped at `2000`). If omitted, all records are returned." }, "sorting": { "type": "string", "description": "Not supported yet. The list is always sorted newest device first (`id` descending)." }, "merchantId": { "type": "number", "description": "ID of the sub-Merchant whose devices you want to list. This API is only for Master Merchant accounts." }, "type": { "type": "string", "description": "Device type to filter by (per `DeviceTypeEnum`): `app-tingee`, `tingee-box-f1`, `tingee-box-2a`, `tingee-box-2as`, `tingee-box-s1` (TingeeBox 3S), `tingee-box-3ls`, `tingee-box-3pro`, `tingee-box-3vn`, `tingee-box-3vna`, `tingee-box-4ls`, `tingee-box-5s`, `tingee-box-5sa`, `tingee-box-6ls`, `tingee-box-6pro`, `tingee-box-6xs`, `vn-50`, `loa-pay`, `trusted-pay`, `pay-alert`, `tingee-box-3vn-mbb`, `tingee-box-3pro-mbb`, `tingee-box-3pro-x`, `tingee-box-max`, `tingee-box-8pro`." } }, "required": [ "merchantId" ] }, "example": { "skipCount": 0, "maxResultCount": 10, "merchantId": 123456 } } } } } }, "/v1/device/get-devices-link-to-shop-or-va": { "post": { "tags": [ "Devices & Hardware" ], "summary": "List devices linked to a shop or VA", "description": "Query the list of devices by shopId or vaAccountNumber.\n\nDocumentation: https://developers.tingee.vn/en/docs/tingee-box/get-devices-link-to-shop-or-va", "operationId": "post_device_get_devices_link_to_shop_or_va", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": [ { "type": "tingee-box-3ls", "uuid": "DEVICE-001" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "vaAccountNumber": { "type": "string", "description": "VA account number to check; the system returns the devices of the shop that contains this account. Required if `shopId` is not passed. If both are passed, `vaAccountNumber` takes precedence." }, "shopId": { "type": "number", "description": "ID of the shop to query. Required if `vaAccountNumber` is not passed." } } }, "example": { "vaAccountNumber": "V1THENO84343344" } } } } } }, "/v1/merchant/create": { "post": { "tags": [ "Operations & Extensions" ], "summary": "Create a Merchant account", "description": "Create a new Merchant entity to start integrating Tingee's payment services.\n\nDocumentation: https://developers.tingee.vn/en/docs/master-merchant/merchant/create", "operationId": "post_merchant_create", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "merchantId": 12345 } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Merchant display name (up to 500 characters)." }, "phoneNumber": { "type": "string", "description": "Primary contact phone number: 10 characters, starting with `0`. If the phone number already exists on TINGEE, the system links the existing Merchant to the Master Merchant instead of creating a new one." }, "password": { "type": "string", "description": "Merchant account password: at least 6 characters, including at least 1 lowercase letter, 1 uppercase letter, 1 digit and 1 special character. If you pass it, the user must change the password on first login. If you omit it, Tingee sets a default password for the Merchant." }, "email": { "type": "string", "description": "Contact email address, in a valid email format and not already used by another Merchant." }, "website": { "type": "string", "description": "Merchant website (up to 256 characters)." }, "code": { "type": "string", "description": "Your own identifier (Partner's Internal ID), up to 20 characters and not already used by another Merchant." }, "businessSectorIds": { "type": "array", "items": {}, "description": "List of the Merchant's business sector IDs." }, "provinceId": { "type": "string", "description": "Province/city code (up to 20 characters)." }, "districtId": { "type": "string", "description": "District code (up to 20 characters)." }, "communeId": { "type": "string", "description": "Ward/commune code (up to 20 characters)." }, "address": { "type": "string", "description": "Address (house number, street), up to 125 characters." }, "fullAddress": { "type": "string", "description": "Full address, up to 250 characters." }, "referralCode": { "type": "string", "description": "Referral code (if any), up to 50 characters. Whitespace is removed." } }, "required": [ "name", "phoneNumber" ] }, "example": { "name": "Doanh nghiệp Vận tải Miền trung", "phoneNumber": "0946881502", "email": "vantaimientrung@gmail.com", "website": "https://vtmt.com" } } } } } }, "/v1/merchant/get-paging": { "post": { "tags": [ "Operations & Extensions" ], "summary": "Get the Merchant list", "description": "Get the list of sub-Merchants, filtered by keyword or status.\n\nDocumentation: https://developers.tingee.vn/en/docs/master-merchant/merchant/get-paging", "operationId": "post_merchant_get_paging", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "totalCount": 1, "items": [ { "id": 10001, "name": "Doanh nghiệp Vận tải", "phoneNumber": "0946881502", "fullAddress": "123 Lê Lợi, Phường Bến Thành, Quận 1, TP. Hồ Chí Minh", "referralCode": null, "userReferralLevel": 1, "creationTime": "2026-01-15T05:20:49.000Z", "userReferralAncestorIds": null, "isMasterMerchant": false, "baasType": null, "isLockEvent": false, "assignedUserId": null, "isLockoutEnabled": false } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "type": "string", "description": "Search keyword, partially matched against the Merchant code (`code`), name, email and phone number; or exactly matched against `clientId`." }, "skipCount": { "type": "number", "description": "Number of records to skip (pagination). Default: 0." }, "maxResultCount": { "type": "number", "description": "Maximum number of records per page (up to 2000). Leave empty to get all." } } }, "example": { "filter": "", "skipCount": 0, "maxResultCount": 10 } } } } } }, "/v1/merchant/delete": { "delete": { "tags": [ "Operations & Extensions" ], "summary": "Delete a Merchant account", "description": "Permanently delete a sub-Merchant from the Master Merchant's system.\n\nDocumentation: https://developers.tingee.vn/en/docs/master-merchant/merchant/delete", "operationId": "delete_merchant_delete", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": null } } } } }, "parameters": [ { "name": "merchantId", "in": "query", "required": true, "description": "ID of the Merchant to delete.", "schema": { "type": "number" }, "example": "12345" } ] } }, "/v1/shop/create-or-update": { "post": { "tags": [ "Operations & Extensions" ], "summary": "Create/update a shop", "description": "Add a new shop or update shop details, depending on the 'id' parameter.\n\nDocumentation: https://developers.tingee.vn/en/docs/master-merchant/shop/create-or-update", "operationId": "post_shop_create_or_update", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "shopId": 5566 } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "ID of the sub-Merchant that owns the shop. Required when calling with a Master Merchant account." }, "id": { "type": "number", "description": "Shop ID (pass it to perform an update)." }, "name": { "type": "string", "description": "Shop display name (up to 500 characters)." }, "address": { "type": "string", "description": "Detailed address of the point of sale (house number, street), up to 125 characters." }, "fullAddress": { "type": "string", "description": "Full address of the point of sale, up to 250 characters. This value is returned in the `address` field of the [Get shop list](https://developers.tingee.vn/en/docs/master-merchant/shop/get-paging) API." }, "provinceId": { "type": "string", "description": "Province/city code (up to 20 characters)." }, "districtId": { "type": "string", "description": "District code (up to 20 characters)." }, "communeId": { "type": "string", "description": "Ward/commune code (up to 20 characters)." }, "email": { "type": "string", "description": "Shop email, in a valid email format (up to 256 characters)." }, "phoneNumber": { "type": "string", "description": "Shop phone number: 10 characters, starting with `0`." }, "isActive": { "type": "boolean", "description": "Active status (`true`/`false`). A newly created shop is always active; this value only takes effect on update." } }, "required": [ "name", "isActive" ] }, "example": { "merchantId": 10001, "name": "Cửa hàng Chi nhánh 1", "isActive": true, "address": "Số 123 Đường ABC, Hà Nội" } } } } } }, "/v1/shop/get-paging": { "post": { "tags": [ "Operations & Extensions" ], "summary": "Get the shop list", "description": "Query the shop list with pagination and advanced filtering.\n\nDocumentation: https://developers.tingee.vn/en/docs/master-merchant/shop/get-paging", "operationId": "post_shop_get_paging", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "totalCount": 1, "items": [ { "id": 10001, "name": "Cửa hàng Chi nhánh 1", "address": "Số 123 Đường ABC, Hà Nội", "isActive": true } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Filter by a specific sub-Merchant ID." }, "filter": { "type": "string", "description": "Search keyword, partially matched against the shop name or full address (`fullAddress`)." }, "sorting": { "type": "string", "description": "Sort results in the format ` `, with multiple conditions separated by commas. Example: `s.id desc`." }, "skipCount": { "type": "number", "description": "Number of records to skip (start position). Default: 0." }, "maxResultCount": { "type": "number", "description": "Maximum number of records per page (up to 2000). Leave empty to get all." } } }, "example": { "filter": "", "skipCount": 0, "maxResultCount": 10, "merchantId": 1001 } } } } } }, "/v1/device/reset": { "delete": { "tags": [ "Operations & Extensions" ], "summary": "Reset a device", "description": "Send a command that resets a TingeeBox device to its initial state and removes its link to the merchant.\n\nDocumentation: https://developers.tingee.vn/en/docs/master-merchant/device/reset-device", "operationId": "delete_device_reset", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": "DEVICE_UUID" } } } } }, "parameters": [ { "name": "uuid", "in": "query", "required": true, "description": "UUID of the device to reset. The device must be assigned to the Master Merchant calling the API.", "schema": { "type": "string" }, "example": "DEVICE_UUID" } ] } }, "/api/webhook/payment": { "post": { "tags": [ "Operations & Extensions" ], "summary": "Payment webhook (QR Code & dynamic QR)", "description": "Push notification of transaction data from Tingee to your system as soon as money arrives in the account.\n\nDocumentation: https://developers.tingee.vn/en/docs/webhook/webhook-payment-callback", "operationId": "post__api_webhook_payment", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } } } } } } } }, "/api/webhook/va-status": { "post": { "tags": [ "Operations & Extensions" ], "summary": "Account linking status webhook", "description": "Webhook that notifies the partner system of the virtual account linking or unlinking status from VCB and TPBank.\n\nDocumentation: https://developers.tingee.vn/en/docs/webhook/webhook-va-status", "operationId": "post__api_webhook_va_status", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Original request identifier (applies to TPBank only; not used for Vietcombank)." }, "merchantId": { "type": "number", "description": "Merchant ID on the Tingee system." }, "merchantAccountNumberId": { "type": "number", "description": "ID of the bank account record on the Tingee system (present for TPBank)." }, "shopId": { "type": "number", "description": "ID of the shop this virtual account is assigned to." }, "bankName": { "type": "string", "description": "Bank name (`\"VCB\"` or `\"TPB\"`)." }, "bankBin": { "type": "string", "description": "Bank BIN: `\"970436\"` (Vietcombank) or `\"970423\"` (TPBank)." }, "accountNumber": { "type": "string", "description": "The customer's original bank account number." }, "accountName": { "type": "string", "description": "Account holder name (uppercase, without diacritics)." }, "vaAccountNumber": { "type": "string", "description": "The virtual account (VA) number that was issued/linked successfully." }, "isNotifyAccountNumber": { "type": "boolean", "description": "`false`: virtual account (VA); `true`: original account receiving balance notifications." }, "status": { "type": "string", "description": "Processing status from the bank (see the table below)." } }, "required": [ "merchantId", "bankName", "bankBin", "accountNumber", "vaAccountNumber", "isNotifyAccountNumber", "status" ] } } } } } }, "/api/webhook/bank-link": { "post": { "tags": [ "Operations & Extensions" ], "summary": "Bank link webhook (Bank Link)", "description": "Notification that syncs the successfully linked bank account information from Tingee to the partner system.\n\nDocumentation: https://developers.tingee.vn/en/docs/webhook/webhook-bank-link", "operationId": "post__api_webhook_bank_link", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } } } } } } } }, "/v1/merchant/get-paging-config": { "post": { "tags": [ "Operations & Extensions" ], "summary": "Get the bank configuration list", "description": "Query a Merchant's bank connection configurations by filter conditions.\n\nDocumentation: https://developers.tingee.vn/en/docs/cau-hinh-tai-khoan-dn/get-paging-config", "operationId": "post_merchant_get_paging_config", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "totalCount": 1, "items": [ { "id": 1, "bankName": "ACB", "bankBin": "970416", "accountType": "business-account", "configDto": { "accountNumber": "698988999", "accountName": "CONG TY TNHH ABC", "vaPrefix": "TINGEE", "mobile": "0843226139", "acbUserId": "ACB_USER_001" } } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Filter by Merchant ID (for Master Merchant accounts). A Master Merchant leaves it empty to get the configurations of all Merchants it manages. A Merchant account always gets only its own configurations." }, "bankBin": { "type": "string", "description": "Bank BIN to filter results by. Takes precedence over `bankName` if you pass both." }, "bankName": { "type": "string", "description": "Bank code to filter results by (e.g. `ACB`, `BIDV`, `CTG`)." }, "accountType": { "type": "string", "description": "Filter by account type: `business-account` (business), `business-household-account` (household business), `personal-account` (personal)." }, "filter": { "type": "string", "description": "Find configurations that have a value in `configDto` exactly matching this string (e.g. an account number). You can use the `%` wildcard." }, "skipCount": { "type": "number", "description": "Number of records to skip (pagination). Default: 0." }, "maxResultCount": { "type": "number", "description": "Maximum number of records per page (up to 2000). Leave empty to get all." } } }, "example": { "bankBin": "970416", "skipCount": 0, "maxResultCount": 10 } } } } } }, "/v1/merchant/create-or-update-config": { "post": { "tags": [ "Operations & Extensions" ], "summary": "Create / update a bank configuration", "description": "Create or update the bank integration configuration for a Merchant.\n\nDocumentation: https://developers.tingee.vn/en/docs/cau-hinh-tai-khoan-dn/create-or-update-config", "operationId": "post_merchant_create_or_update_config", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": 125 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "bankBin": { "type": "string", "description": "Bank BIN. Takes precedence over `bankName` if you pass both." }, "bankName": { "type": "string", "description": "Bank name (e.g. `ACB`, `BIDV`, `CTG`). Required if you do not pass `bankBin`." }, "accountType": { "type": "string", "description": "Account type: `business-account` (business) or `business-household-account` (household business)." }, "id": { "type": "number", "description": "ID of the existing configuration (pass it to update, leave it empty to create)." }, "otpNumber": { "type": "string", "description": "Confirmation OTP (required by some banks)." }, "confirmId": { "type": "string", "description": "Confirmation code received after the ACB configuration registration step." }, "bidvConfigDto": { "type": "object", "description": "Configuration for BIDV. Pass it when `bankBin` is BIDV." }, "ctgConfigDto": { "type": "object", "description": "Configuration for VietinBank (CTG). Pass it when `bankBin` is VietinBank." }, "acbConfigDto": { "type": "object", "description": "Configuration for ACB. Pass it when `bankBin` is ACB." }, "msbConfigDto": { "type": "object", "description": "Configuration for MSB. Pass it when `bankBin` is MSB." }, "baokimConfigDto": { "type": "object", "description": "Configuration for the BaoKim e-wallet. Pass it when `bankBin` is `BAOKIM`." } }, "required": [ "accountType" ] }, "example": { "bankBin": "970418", "accountType": "business-account", "bidvConfigDto": { "accountNumber": "1234567890", "accountName": "CONG TY TNHH ABC", "vaPrefix": "TINGEE", "bankPartnerId": "PARTNER_001" } } } } } } }, "/v1/merchant/delete-config": { "post": { "tags": [ "Operations & Extensions" ], "summary": "Delete a bank configuration", "description": "Delete a Merchant's bank integration configuration for the specified bank.\n\nDocumentation: https://developers.tingee.vn/en/docs/cau-hinh-tai-khoan-dn/delete-config", "operationId": "post_merchant_delete_config", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "ID of the configuration record to delete (positive integer), from the [Get configuration list](https://developers.tingee.vn/en/docs/cau-hinh-tai-khoan-dn/get-paging-config) API." }, "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "otpNumber": { "type": "string", "description": "Confirmation OTP sent by the bank. For ACB: pass it together with `confirmId` to confirm the configuration cancellation at the bank." }, "confirmId": { "type": "string", "description": "Confirmation code received from the [[ACB] Delete business account configuration](/docs/cau-hinh-tai-khoan-dn/delete-config-account-business) API. For ACB: pass it together with `otpNumber`." } }, "required": [ "id" ] }, "example": { "id": 1 } } } } } }, "/v1/merchant/config-account-business": { "post": { "tags": [ "Operations & Extensions" ], "summary": "[ACB] Configure a business account", "description": "Link a business bank account and generate a confirmation code (confirmId) to complete the configuration.\n\nDocumentation: https://developers.tingee.vn/en/docs/cau-hinh-tai-khoan-dn/config-account-business", "operationId": "post_merchant_config_account_business", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "confirmId": "CONFIRM_ABC123" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "bankBin": { "type": "string", "description": "Bank BIN; pass `970416` (ACB)." }, "vaPrefix": { "type": "string", "description": "Virtual Account prefix." }, "accountName": { "type": "string", "description": "Bank account holder name." }, "accountNumber": { "type": "string", "description": "Business bank account number." }, "mobile": { "type": "string", "description": "Phone number registered with the bank account." }, "acbUserId": { "type": "string", "description": "User ID in the bank's system (issued by the bank)." } }, "required": [ "bankBin", "accountName", "accountNumber", "mobile", "acbUserId" ] }, "example": { "bankBin": "970416", "vaPrefix": "TINGEE", "accountName": "CONG TY TNHH ABC", "accountNumber": "1234567890", "mobile": "0901234567", "acbUserId": "ACB_USER_001" } } } } } }, "/v1/merchant/delete-config-account-business": { "post": { "tags": [ "Operations & Extensions" ], "summary": "[ACB] Delete a business account configuration", "description": "Delete an ACB business account configuration for a Merchant.\n\nDocumentation: https://developers.tingee.vn/en/docs/cau-hinh-tai-khoan-dn/delete-config-account-business", "operationId": "post_merchant_delete_config_account_business", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "confirmId": "CONFIRM_ABC123" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "bankBin": { "type": "string", "description": "Bank BIN; pass `970416` (ACB). Required if you do not pass `bankName`." }, "bankName": { "type": "string", "description": "Bank code; pass `ACB`. Required if you do not pass `bankBin`." }, "accountType": { "type": "string", "description": "Account type of the configuration to delete: `business-account` or `business-household-account`." }, "configRemove": { "type": "object", "description": "Details of the ACB account to remove from the configuration (`accountNumber`, `accountName`, `vaPrefix`, `mobile`, `acbUserId`). The system identifies the configuration to delete by `accountType` and `configRemove.vaPrefix`, so `configRemove.vaPrefix` is required." } }, "required": [ "accountType", "configRemove" ] }, "example": { "bankBin": "970416", "accountType": "business-account", "configRemove": { "accountNumber": "1234567890", "accountName": "CONG TY TNHH ABC", "vaPrefix": "TINGEE", "mobile": "0901234567", "acbUserId": "ACB_USER_001" } } } } } } }, "/v1/e-invoice/get-provider": { "post": { "tags": [ "E-invoices" ], "summary": "List providers", "description": "Get the list of supported e-invoice providers.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/get-provider", "operationId": "post_e_invoice_get_provider", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": [ { "code": "x-cyber", "name": "XCyber", "description": "Cyber Lotus", "urlLogo": "https://.../xCyber.svg", "lookupUrlPattern": "http://tracuuhoadon.cyberbill.vn/#/tracuuhoadon/tracuu?maso={trackingCode}" }, { "code": "hilo", "name": "HiLo", "description": "HILO GROUP", "urlLogo": "https://.../hilo.svg", "lookupUrlPattern": "https://tracuuhddt78.hilo.com.vn/" }, { "code": "s-invoice", "name": "SInvoice", "description": "Viettel Solutions", "urlLogo": "https://.../sInvoice.svg", "lookupUrlPattern": "https://vinvoice.viettel.vn/tracuu?masothue={taxCode}&mabimat={reservationCode}" }, { "code": "misa", "name": "Misa", "description": "MISA JSC", "urlLogo": "https://.../misa.svg" }, { "code": "bkav", "name": "BKAV", "description": "BKAV CORP", "urlLogo": "https://.../bkav.svg", "lookupUrlPattern": "https://tchd.ehoadon.vn/TCHD" } ] } } } } } } }, "/v1/e-invoice/get-paging-account": { "post": { "tags": [ "E-invoices" ], "summary": "List provider accounts", "description": "Query the list of e-invoice provider accounts by filter conditions.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/get-paging-account", "operationId": "post_e_invoice_get_paging_account", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "totalCount": 1, "items": [ { "id": 1, "merchantId": 10001, "masterMerchantId": null, "provider": "x-cyber", "taxCode": "0101234567", "username": "admin@company.vn", "isDefault": true, "isActive": true, "services": [ "output-invoice" ], "creationTime": "2026-01-15T08:30:00.000Z" } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Filter by sub-Merchant. (Only applies when you connect with a Master Merchant account; leave empty to get the accounts of all sub-Merchants)." }, "filter": { "type": "string", "description": "Fuzzy search keyword on the tax code (`taxCode`) or username (`username`)." }, "skipCount": { "type": "number", "description": "Number of records to skip (Default: `0`)." }, "maxResultCount": { "type": "number", "description": "Maximum number of records per page (maximum `2000`; larger values are reduced to `2000`). If not passed, the system returns all records." }, "provider": { "type": "string", "description": "Filter by provider: `x-cyber`, `hilo`, `s-invoice`, `misa`, `bkav`." }, "isDefault": { "type": "boolean", "description": "Filter default accounts." }, "isActive": { "type": "boolean", "description": "Filter active accounts." } } }, "example": { "skipCount": 0, "maxResultCount": 10, "provider": "x-cyber", "isActive": true } } } } } }, "/v1/e-invoice/create-or-update-account": { "post": { "tags": [ "E-invoices" ], "summary": "Create / Update a provider account", "description": "Create or update an e-invoice provider account.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/create-or-update-account", "operationId": "post_e_invoice_create_or_update_account", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": 1 } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Account ID (pass it to update, leave it empty to create)." }, "merchantId": { "type": "number", "description": "Merchant ID. (Required if you connect with a Master Merchant account)." }, "provider": { "type": "string", "description": "Provider: `x-cyber`, `hilo`, `s-invoice`, `misa`, `bkav`." }, "taxCode": { "type": "string", "description": "Business tax code." }, "username": { "type": "string", "description": "Username of the provider account." }, "password": { "type": "string", "description": "Account password (stored encrypted)." }, "isDefault": { "type": "boolean", "description": "Set as the default account (Default: `false`). The Merchant's first account is always set as the default; when set to `true`, the other accounts are no longer the default." }, "isActive": { "type": "boolean", "description": "Activate the account (Default: `true`)." }, "services": { "type": "array", "items": {}, "description": "Services used with the account: `output-invoice` (sales invoices), `input-invoice` ([purchase invoices](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/hoa-don-dau-vao)). Default `[\"output-invoice\"]`. On update, the services you pass are added to the existing list. The `input-invoice` service currently only supports the `x-cyber` provider." } }, "required": [ "provider", "taxCode", "username", "password" ] }, "example": { "provider": "x-cyber", "taxCode": "0101234567", "username": "admin@company.vn", "password": "your_password", "isDefault": true, "isActive": true } } } } } }, "/v1/e-invoice/delete-account": { "post": { "tags": [ "E-invoices" ], "summary": "Delete a provider account", "description": "Delete an e-invoice provider account by ID.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/delete-account", "operationId": "post_e_invoice_delete_account", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "ID of the provider account to delete." }, "merchantId": { "type": "number", "description": "Merchant ID. (Required if you connect with a Master Merchant account)." } }, "required": [ "id" ] }, "example": { "id": 1 } } } } } }, "/v1/e-invoice/create": { "post": { "tags": [ "E-invoices" ], "summary": "Create a draft invoice", "description": "Create a draft invoice (draft/preview) and return the Base64 PDF file.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/create", "operationId": "post_e_invoice_create", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "invoiceCode": "INV-20251209-001", "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PA..." } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID. (Required if you connect with a Master Merchant account)." }, "accountId": { "type": "number", "description": "Account configuration ID (if empty, the default account is used)." }, "invoicePattern": { "type": "string", "description": "Invoice template number (mẫu số). See [Get invoice templates](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/invoice-templates)." }, "invoiceSeries": { "type": "string", "description": "Invoice symbol (ký hiệu). See [Get invoice templates](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/invoice-templates)." }, "invoiceCode": { "type": "string", "description": "Invoice code generated by the partner (unique key), used later to download the invoice / send email." }, "invoiceDate": { "type": "string", "description": "Invoice date (format: `YYYY-MM-DD`, e.g. `2025-12-09`)." }, "invoiceType": { "type": "string", "description": "Invoice type (provider-specific)." }, "buyerTaxCode": { "type": "string", "description": "Buyer's tax code." }, "buyerIdentity": { "type": "string", "description": "Buyer's identity document number (citizen ID card (CCCD) / passport / business registration certificate (GPKD) number). The BKAV provider does not use this field yet." }, "buyerIdType": { "type": "string", "description": "Document type of `buyerIdentity`: `1`=citizen ID card (CCCD), `2`=passport, `3`=business registration certificate (GPKD). Other values are rejected. Currently only sent to SInvoice; if you pass `buyerIdentity` without `buyerIdType`, it defaults to `1`." }, "buyerName": { "type": "string", "description": "Buyer name. TINGEE does not require this field, but the provider (e.g. SInvoice) may reject the invoice if both `buyerName` and `buyerLegalName` are missing." }, "buyerLegalName": { "type": "string", "description": "Buyer's company name." }, "buyerAddress": { "type": "string", "description": "Buyer address." }, "buyerPhone": { "type": "string", "description": "Buyer phone number." }, "buyerEmail": { "type": "string", "description": "Buyer email." }, "buyerBankAccount": { "type": "string", "description": "Buyer's bank account number." }, "buyerBankName": { "type": "string", "description": "Buyer's bank name." }, "paymentMethod": { "type": "number", "description": "Payment method: `1`=cash (TM), `2`=bank transfer (CK), `3`=cash/bank transfer (TM/CK) (Default: `3`)." }, "paymentMethodName": { "type": "string", "description": "Payment method name (generated by the system from `paymentMethod` if not passed)." }, "currency": { "type": "string", "description": "Currency code (Default: `VND`)." }, "exchangeRate": { "type": "string", "description": "Foreign currency exchange rate (Default: `1`)." }, "amountInWords": { "type": "string", "description": "Amount in words (generated automatically if not passed)." }, "note": { "type": "string", "description": "Invoice note." }, "items": { "type": "array", "items": {}, "description": "List of goods/services (see the `items[]` table below)." }, "totalDiscount": { "type": "string", "description": "Total discount amount (calculated by the system if not passed)." }, "totalBeforeTax": { "type": "string", "description": "Total amount before tax (calculated by the system if not passed)." }, "totalTax": { "type": "string", "description": "Total tax amount (calculated by the system if not passed)." }, "totalAfterTax": { "type": "string", "description": "Total amount after tax (calculated by the system if not passed)." }, "taxRateSummaries": { "type": "array", "items": {}, "description": "Tax rate summary (calculated by the system if not passed, see the table below)." } }, "required": [ "invoicePattern", "invoiceSeries", "invoiceCode", "invoiceDate", "items" ] }, "example": { "invoicePattern": "1", "invoiceSeries": "C25TAB", "invoiceCode": "INV-20251209-001", "invoiceDate": "2025-12-09", "buyerName": "Nguyen Van A", "buyerLegalName": "CONG TY TNHH ABC", "buyerTaxCode": "0109876543", "buyerAddress": "123 Nguyen Hue, Quan 1, TP.HCM", "paymentMethod": 2, "paymentMethodName": "Chuyển khoản", "items": [ { "itemName": "Dịch vụ thanh toán", "unitName": "Gói", "quantity": "1", "unitPrice": "1000000", "taxRateCode": "10" } ] } } } } } }, "/v1/e-invoice/create-and-issue": { "post": { "tags": [ "E-invoices" ], "summary": "Create and issue an invoice", "description": "Create, sign and issue an invoice in a single step (HSM signing).\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/create-and-issue", "operationId": "post_e_invoice_create_and_issue", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "invoiceCode": "INV-20251209-002", "trackingCode": "INV-20251209-002", "invoiceNumber": "C25TAB123", "reservationCode": "ABC123XYZ", "codeOfTax": "00A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6", "url": "https://vinvoice.viettel.vn/tracuu?masothue=0101234567&mabimat=ABC123XYZ" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "invoicePattern": "1", "invoiceSeries": "C25TAB", "invoiceCode": "INV-20251209-002", "invoiceDate": "2025-12-09", "buyerName": "Nguyen Van A", "buyerLegalName": "CONG TY TNHH ABC", "buyerTaxCode": "0109876543", "buyerAddress": "123 Nguyen Hue, Quan 1, TP.HCM", "paymentMethod": 2, "paymentMethodName": "Chuyển khoản", "items": [ { "itemName": "Dịch vụ thanh toán", "unitName": "Gói", "quantity": "1", "unitPrice": "1000000", "taxRateCode": "10" } ] } } } } } }, "/v1/e-invoice/download": { "post": { "tags": [ "E-invoices" ], "summary": "Download an invoice", "description": "Download an issued invoice as a Base64 PDF by invoice code.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/download", "operationId": "post_e_invoice_download", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "invoiceCode": "INV-20251209-001", "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PA..." } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID. (Required if you connect with a Master Merchant account)." }, "accountId": { "type": "number", "description": "Account configuration ID. The system prefers the account that issued this invoice; only if that cannot be determined does it use `accountId` (or the default account if empty)." }, "invoiceCode": { "type": "string", "description": "Invoice code (`invoiceCode`) you passed when calling [Create and issue an invoice](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/create-and-issue). The invoice template number (mẫu số) and invoice symbol (ký hiệu) are determined by the system." } }, "required": [ "invoiceCode" ] }, "example": { "invoiceCode": "INV-20251209-001" } } } } } }, "/v1/e-invoice/invoice-templates": { "post": { "tags": [ "E-invoices" ], "summary": "Get invoice templates", "description": "Get the list of invoice templates registered with the provider.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/invoice-templates", "operationId": "post_e_invoice_invoice_templates", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": [ { "invoicePattern": "1", "invoiceSeries": "C25TAB", "quota": 950 } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID. (Required if you connect with a Master Merchant account)." }, "accountId": { "type": "number", "description": "Account configuration ID (if empty, the default account is used)." }, "provider": { "type": "string", "description": "Provider: `x-cyber`, `hilo`, `s-invoice`, `misa`, `bkav`." }, "taxCode": { "type": "string", "description": "Tax code." }, "username": { "type": "string", "description": "Username of the provider account." }, "password": { "type": "string", "description": "Account password." }, "invoiceNoToCheck": { "type": "number", "description": "Invoice number to check (greater than `0`). Required when the provider is HiLo (`provider = hilo`, or the account selected by `accountId` / the default account belongs to HiLo)." } } }, "example": { "invoiceNoToCheck": 100 } } } } } }, "/v1/e-invoice/send-email": { "post": { "tags": [ "E-invoices" ], "summary": "Send an invoice by email", "description": "Send an invoice to the buyer by email.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/send-email", "operationId": "post_e_invoice_send_email", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": null } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID. (Required if you connect with a Master Merchant account)." }, "accountId": { "type": "number", "description": "Account configuration ID. The system prefers the account that issued this invoice; only if that cannot be determined does it use `accountId` (or the default account if empty)." }, "invoiceCode": { "type": "string", "description": "Invoice code (`invoiceCode`) you passed when calling [Create and issue an invoice](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/create-and-issue)." }, "recipientEmail": { "type": "string", "description": "Recipient email." }, "buyerName": { "type": "string", "description": "Recipient name displayed in the email. Only applies to MISA (Default: `Khách hàng`)." } }, "required": [ "invoiceCode", "recipientEmail" ] }, "example": { "invoiceCode": "INV-20251209-001", "recipientEmail": "buyer@example.com" } } } } } }, "/v1/e-invoice/input/connect": { "post": { "tags": [ "E-invoices" ], "summary": "Connect a tax account", "description": "Connect a General Department of Taxation (TCT) account to an e-invoice account.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/hoa-don-dau-vao/connect", "operationId": "post_e_invoice_input_connect", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": "Kết nối thành công" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "accountId": { "type": "number", "description": "E-invoice account ID (from [List accounts](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/get-paging-account)). Leave empty to use the default account." }, "tctUsername": { "type": "string", "description": "Username for the General Department of Taxation e-invoice portal. Leave empty to use the information saved in the business profile at the provider." }, "tctPassword": { "type": "string", "description": "Password for the General Department of Taxation e-invoice portal. Leave empty to use the saved information." } } }, "example": { "tctUsername": "0101234567", "tctPassword": "YOUR_TCT_PASSWORD" } } } } } }, "/v1/e-invoice/input/disconnect": { "post": { "tags": [ "E-invoices" ], "summary": "Disconnect a tax account", "description": "Disconnect a General Department of Taxation (TCT) account.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/hoa-don-dau-vao/disconnect", "operationId": "post_e_invoice_input_disconnect", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": "Ngắt kết nối thành công" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "accountId": { "type": "number", "description": "E-invoice account ID (from [List accounts](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/get-paging-account)). Leave empty to use the default account." } } }, "example": { "accountId": 1 } } } } } }, "/v1/e-invoice/input/sync": { "post": { "tags": [ "E-invoices" ], "summary": "Sync purchase invoices", "description": "Sync purchase invoices from the General Department of Taxation for a time range.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/hoa-don-dau-vao/sync", "operationId": "post_e_invoice_input_sync", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": "Đồng bộ thành công" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "accountId": { "type": "number", "description": "E-invoice account ID (from [List accounts](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/get-paging-account)). Leave empty to use the default account." }, "fromDate": { "type": "string", "description": "Start date, format `dd/MM/yyyy`." }, "toDate": { "type": "string", "description": "End date, format `dd/MM/yyyy`." } } }, "example": { "fromDate": "01/10/2026", "toDate": "10/10/2026" } } } } } }, "/v1/e-invoice/input/list": { "post": { "tags": [ "E-invoices" ], "summary": "List purchase invoices", "description": "Get the list of purchase invoices with pagination and filters.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/hoa-don-dau-vao/list", "operationId": "post_e_invoice_input_list", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "totalCount": 1, "items": [ { "id": 123456, "invoiceCode": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "fileHistoryId": "f9e8d7c6-b5a4-4321-9876-543210fedcba", "invoiceNo": "0000125", "invoicePattern": "1", "invoiceSeries": "C26TAA", "sellerName": "CÔNG TY TNHH ABC", "sellerTaxCode": "0101234567", "totalBeforeTax": 1000000, "taxAmount": 80000, "totalAfterTax": 1080000, "invoiceDate": "2026-10-05", "receivedDate": "2026-10-06", "invoiceStatus": 1, "approvalStatus": 1, "tctStatus": 1, "invoiceType": 1, "invoiceProperty": 1, "importMethod": 1, "orderNo": null, "note": null } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "accountId": { "type": "number", "description": "E-invoice account ID (from [List accounts](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/get-paging-account)). Leave empty to use the default account." }, "page": { "type": "number", "description": "Page to retrieve, starting from `0`. Default `0`." }, "size": { "type": "number", "description": "Number of records per page (minimum `1`). Default `50`." }, "sellerTaxCode": { "type": "string", "description": "Filter by seller tax code." }, "buyerTaxCode": { "type": "string", "description": "Filter by buyer tax code. Defaults to the business's tax code." }, "invoiceNo": { "type": "string", "description": "Filter by invoice number." }, "invoiceProperty": { "type": "number", "description": "Invoice nature: `1` Original, `2` Replacement, `3` Adjustment, `4` Replaced, `5` Adjusted, `6` Deleted/cancelled." }, "approvalStatus": { "type": "number", "description": "Approval status: `1` Pending approval, `2` Approved, `3` Rejected, `4` Cancelled, `5` Processed." }, "label": { "type": "string", "description": "Filter by label." } } }, "example": { "page": 0, "size": 50, "invoiceFromDate": "2026-10-01 00:00:00.000", "invoiceToDate": "2026-10-10 23:59:59.999" } } } } } }, "/v1/e-invoice/input/detail": { "post": { "tags": [ "E-invoices" ], "summary": "Purchase invoice details", "description": "Get the details of a purchase invoice by invoiceCode.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/hoa-don-dau-vao/detail", "operationId": "post_e_invoice_input_detail", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "invoiceCode": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "fileHistoryId": "f9e8d7c6-b5a4-4321-9876-543210fedcba", "invoiceName": "Hóa đơn giá trị gia tăng", "invoicePattern": "1", "invoiceSeries": "C26TAA", "invoiceNo": "0000125", "invoiceDate": "2026-10-05", "signedDate": "2026-10-05", "receivedDate": "2026-10-06", "approvedDate": null, "paymentDate": null, "currency": "VND", "exchangeRate": 1, "paymentMethod": "TM/CK", "sellerName": "CÔNG TY TNHH ABC", "sellerTaxCode": "0101234567", "sellerAddress": "Hà Nội", "buyerName": "CÔNG TY CP XYZ", "buyerTaxCode": "0109876543", "buyerAddress": "TP. Hồ Chí Minh", "totalBeforeTax": 1000000, "taxAmount": 80000, "discountAmount": 0, "totalAfterTax": 1080000, "amountInWords": "Một triệu không trăm tám mươi nghìn đồng", "invoiceStatus": 1, "approvalStatus": 1, "invoiceType": 1, "note": null, "items": [ { "id": 987654, "lineNumber": 1, "itemName": "Dịch vụ phần mềm", "unitName": "Gói", "quantity": 1, "unitPrice": 1000000, "totalBeforeTax": 1000000, "taxRate": "8%", "taxAmount": 80000, "itemType": 1, "isPromotion": false } ], "taxRateSummaries": [ { "id": 55501, "taxRate": "8%", "taxAmount": 80000 } ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "accountId": { "type": "number", "description": "E-invoice account ID (from [List accounts](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/get-paging-account)). Leave empty to use the default account." }, "invoiceCode": { "type": "string", "description": "Invoice identifier, from the [List purchase invoices](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/hoa-don-dau-vao/list) API." } }, "required": [ "invoiceCode" ] }, "example": { "invoiceCode": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" } } } } } }, "/v1/e-invoice/input/preview-base64": { "post": { "tags": [ "E-invoices" ], "summary": "Purchase invoice rendition", "description": "Download the PDF rendition of a purchase invoice as Base64.\n\nDocumentation: https://developers.tingee.vn/en/docs/hoa-don-dien-tu/hoa-don-dau-vao/preview-base64", "operationId": "post_e_invoice_input_preview_base64", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } }, "example": { "code": "00", "message": "Success", "data": { "fileBase64": "JVBERi0xLjQKMSAwIG9iago8PA..." } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "type": "number", "description": "Merchant ID (Required if you connect with a Master Merchant account)." }, "accountId": { "type": "number", "description": "E-invoice account ID (from [List accounts](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/get-paging-account)). Leave empty to use the default account." }, "invoiceCode": { "type": "string", "description": "Invoice identifier, from the [List purchase invoices](https://developers.tingee.vn/en/docs/hoa-don-dien-tu/hoa-don-dau-vao/list) API." } }, "required": [ "invoiceCode" ] }, "example": { "invoiceCode": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" } } } } } }, "/v1/direct-link/financial-utility/wallet-info": { "get": { "tags": [ "Other" ], "summary": "Query e-wallet information (BaoKim)", "description": "Query the balance and details of a BaoKim e-wallet.\n\nDocumentation: https://developers.tingee.vn/en/docs/direct-link/wallet-info", "operationId": "get_direct_link_financial_utility_wallet_info", "security": [ { "clientId": [], "timestamp": [], "signature": [] } ], "responses": { "200": { "description": "Result (check the `code` field)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {} } } } } } }, "parameters": [ { "name": "bankBin", "in": "query", "required": true, "description": "Bank / e-wallet BIN. Currently only BAOKIM (BaoKim e-wallet) is supported.", "schema": { "type": "string" }, "example": "BAOKIM" }, { "name": "walletId", "in": "query", "required": true, "description": "The merchant's BaoKim e-wallet username (the wallet linked to TINGEE).", "schema": { "type": "string" }, "example": "0987654321" } ] } } } }