🧾 Purchase invoices​

Automatically retrieve a business's purchase invoices from the General Department of Taxation (provider XCyber supported). See the Purchase invoices overview.

• POST /v1/e-invoice/input/connect – Connect a tax account
• POST /v1/e-invoice/input/disconnect – Disconnect a tax account
• POST /v1/e-invoice/input/sync – Sync purchase invoices
• POST /v1/e-invoice/input/list – List purchase invoices
• POST /v1/e-invoice/input/detail – Purchase invoice details
• POST /v1/e-invoice/input/preview-base64 – Download the PDF rendition

🏪 POS payments​

Create an order and push it directly to a Payoo POS terminal so the customer can pay by card or QR. See POS payments.

• POST /v1/create-pos-bill – Create a POS order
• GET /v1/get-detail-pos-bill – POS order details
• PUT /v1/update-pos-bill – Cancel a POS order

🏦 Debit notifications (ACB)​

Register for notifications of outgoing transactions on an ACB source account.

• POST /v1/create-debit – Register for debit notifications
• DELETE /v1/delete-debit – Cancel debit notifications

🛠️ Documentation improvements​

• Consistent code samples in 5 languages (cURL, NestJS, C#, Java, PHP) for every API, with tested signatures. The samples pin the UTC+7 time zone and do not escape non-ASCII characters when signing, which avoids errors 90, 91 and 97.
• Your chosen programming language is remembered across all pages.
• The error code list adds a System error codes group and API rate limits; every API has its own error code table.
• Parameters standardized to match the live system, including these changes to note when integrating:
  • VietinBank disbursement: use debitAccountNumber, records[].creditAccountNumber, records[].creditBankBin (instead of sender* / receiver*).
  • BIDV disbursement: use creditBankBin, creditIssueDate, creditIssueAddress; paginate lookups with skipCount / maxResultCount.
  • Direct Debit: look up transactions by transactionId.
  • Business account configuration: accountType accepts business-account / business-household-account.

✨ Documentation site experience​

• 🌐 Multi-language (Tiếng Việt / English): the API and SDK documentation is now available in English at developers.tingee.vn/en. Switch languages with the VI | EN button in the navigation bar; you stay on the same page. The English version covers the latest documentation version; the Sandbox is currently available in Vietnamese only.
• 🤖 Ask AI on every page: a toolbar under each page title offers Ask AI (opens ChatGPT, Claude, Perplexity, Grok or Cursor with the page content), Copy Markdown to paste into AI tools, and .md to view the page as Markdown.
• 🧰 Developer resources per language: OpenAPI, the Postman Collection and llms.txt / llms-full.txt come in Vietnamese (at the root) and English (under /en/), e.g. https://developers.tingee.vn/en/openapi.json. See Developer toolkit.
• 🌙 Improved dark mode: code blocks, sample responses, Sandbox banners, flow diagrams and the version badge now use dark backgrounds that are easier to read in dark mode.
• 📱 Navigation menu in sync with the sidebar: the mobile "Main features" menu and the desktop navigation bar show every documentation section (now including Important notes, Changelog...) and follow the version you are viewing.
• 🎨 New look: the header, sidebar and table of contents are rounded cards aligned in a single frame. The right-hand table of contents highlights the section you are reading; on medium screens (1000–1200px) it sticks below the header and always shows the current section. A Sandbox shortcut card now sits under the table of contents.
• 🧪 Tidier Sandbox: the "Back" bar and page content of every Sandbox now line up with the header.

⚠️ Note: this is a simulation that uses mock data for API testing; it is not connected to the real tax system.

🌟 E-invoice Sandbox highlights​

An interactive tool for the E-invoice solution:

• Many providers: try simulated invoice templates from popular providers (Viettel S-Invoice, HiLo, X-Cyber, MISA, BKAV).
• Automatic template number & symbol: automatically loads the invoice-issuing accounts and the matching template numbers (VAT invoice, sales invoice).
• Line items & calculation: issue to individuals or businesses; manage items, discounts and multiple VAT rates, with amounts calculated in real time.
• Simulated draft & issue: try the draft invoice (/create) and issue invoice (/create-and-issue) APIs.
• Live PDF preview: render the invoice PDF right in the browser through the /download API.
• API Playground: generates the x-signature (HMAC-SHA512) automatically, and lets you view and copy the JSON request / response for your integration.

We also added Sandbox Banners (the "Try in Sandbox" block) to all the key documentation pages, so you can start testing the APIs sooner.

🎨 Sandbox Banner UI​

Visual Sandbox banners have been added to the core business documentation:

• Bank Link: try creating a virtual account and verifying the OTP.
• Payment Gateway: test the end-to-end payment flow with several methods (VietQR, ATM, Pay-by-Bank).
• Tingee Box device: simulate transaction notification sound scenarios.
• E-Invoice: issue test VAT invoices from several providers.
• Disbursement & Direct Debit (Direct Link / Direct Debit): try approving disbursement orders, querying them and running recurring automatic debits.

Each banner links straight to the matching Tingee Sandbox page, for maximum convenience.

🚀 BaoKim integration (Disbursement – Direct Link)​

Tingee now officially supports the BaoKim e-wallet. Partners can sync their wallet for both Collection and Disbursement.

• Identifier BIN: BAOKIM
• Supported API flows:
  • Create a disbursement order (single orders only; batch orders have been removed)
  • Beneficiary account inquiry (Account Inquiry)
  • Transaction status inquiry (Transaction Inquiry)
  • Wallet account integration (wallet sync with the BAOKIM identifier)
  • The APIs in the Banking & Identification group

👉 See: Create a disbursement order (VietinBank, BaoKim)

🔄 Standardized disbursement parameter (creditAccountType)​

To unify the payment data structure and support routing to more partners such as BaoKim and BIDV, we standardized the account type parameter of the Create disbursement order API.

Changes to the /v1/direct-link/create-transfer API:

• Field replaced: paymentMethod (to-acc, to-id) has been removed and fully replaced by the creditAccountType field.
• How it works: creditAccountType can be set at both the global level (Global Parameter) and the record level.
• New supported values:
  • ACCOUNT: transfer to an account number
  • CARD: transfer to a card number
  • WALLET: transfer to an e-wallet
  • ID: transfer to an identity document (ID card / citizen ID / passport)

This gives the payload a consistent structure and makes it easier to add new payment channels in the future.

🏦 Banking & VA​

create-va API update (Create / link an account number):

• New transactionType field (Request Body):
  • The transaction type to register for.
  • Supported values:
    • credit: credit transactions (default).
    • debit: debit transactions (ACB only).

🪝 Webhook​

Webhook Payment Callback update (payment notifications):

• New type field (Body Parameter):
  • The type of the received transaction.
  • Returned values:
    • credit: credit transaction.
    • debit: debit transaction.
  • If no value is returned, the system defaults to credit.

🏦 Bank Link SDK​

Embed the bank linking screen into your system seamlessly:

• Create a bank link session: a backend API that creates a session and returns a secure SDK URL.
• Web UI SDK: the tingee-bank-link.js frontend library embeds the UI as a Popup (Modal) or an Inline Container directly in your web page.

🛠️ Documentation upgrades & improvements​

• Navigation fixes: the version dropdown and the secondary navigation bar now work reliably and correctly on every documentation page (including the standalone SDK pages).
• Simpler code samples: simplified the Node.js backend snippets in the docs, removed duplication and pointed to a single page about configuring the HMAC-SHA512 signature.
• SDK configuration cleanup: removed unnecessary internal configuration properties and hid the not-yet-optimized size presets of the Web Modal SDK to improve the partner integration experience.

Together they optimize the whole financial process: from managing incoming cash flow and outgoing cash flow (payroll, commissions, supplier payments...) to automating tax documents.

🧾 E-invoice system​

The integrated E-invoice solution helps businesses issue and manage invoices automatically:

• Providers & accounts: set up providers and configure invoice-issuing accounts.
• Create a draft invoice: prepare invoice data before issuing it.
• Create and issue an invoice: issue a valid e-invoice to the tax authority and the customer.
• Invoice utilities: extra features such as downloading invoices, emailing invoices and listing invoice templates.

💳 Payment Gateway​

Flexible Payment Gateway integration for partner apps and websites:

• Create a Payment Link: create a payment link in seconds.
• Web UI SDK: embed the payment gateway UI seamlessly on the web.
• iOS SDK: a standard payment gateway UI for iOS apps.
• Android SDK: a standard payment gateway UI for Android apps.

🏦 Disbursement flows​

Depending on your business requirements and the connected bank, two processing models are supported:

1. Automatic disbursement flow​

• Supported bank: VietinBank.
• Characteristics: a minimal process; transactions are posted immediately without manual OTP verification in the app. Suited to fully automated 24/7 models.
• Core APIs:
  • Create an automatic disbursement order: create the transfer order and send it straight to the partner bank.
  • Query an automatic disbursement transaction: check the posting status of an automatic disbursement order.

2. Maker/Checker approval flow (two-layer security)​

• Supported bank: BIDV.
• Characteristics: a strict security process that separates the person who creates the order (Maker) from the person who approves it (Checker). Requires two-layer authentication by scanning a QR code to get a SmartOTP in the banking app.
• Process & APIs involved:
  • Get the authorization URL: log in and link the Maker/Checker bank accounts.
  • Create a Maker/Checker disbursement order: the Maker creates an order as a draft (INIT) or requests approval (REQUEST_APPROVAL).
  • Confirm submission for approval: the Maker scans the SmartOTP QR to submit the transaction to the bank for approval.
  • Approve a disbursement order: the Checker starts approving an order submitted by the Maker.
  • Confirm disbursement approval: the Checker scans the SmartOTP QR to approve and post the transaction.
  • Reject an order / Delete an order: the Checker rejects an order, or the Maker cancels orders that are still drafts (INIT).
  • Query a Maker/Checker transaction: track the detailed status of a batch or a single transaction.

🛠️ Advanced disbursement utilities​

The Disbursement solution includes tools for reconciliation, information verification and payment account management. Support for the utility APIs is as follows:

1. Common utilities (all banks)​

• Pre-transaction checks:
  • Beneficiary account inquiry: verify the beneficiary account before transferring money to avoid sending it to the wrong account.
  • Validate the payment account: check the payment account before creating a disbursement order.
• Bank information:
  • Domestic bank list: get the Vietnamese banks that support Disbursement.
  • Bank branch list: look up bank branches for Disbursement.

2. BIDV-only utilities​

The full set of advanced utilities for operating and reconciling business cash flow:

• Payment account management:
  • Payment account balance: get the real-time available balance of the payment account.
• Reports & reconciliation:
  • Transaction action log: get the action history of a disbursement transaction.
  • Payment account transaction history: view the detailed balance history (statement) of the payment account.
  • Download batch report: export batch transaction results to an Excel file for periodic reconciliation.

🏦 Banking & VA​

create-va API update (Create / link an account number):

• New and clarified parameter descriptions (Request Body):
  • shopId: assigns the VA to an existing shop.
  • merchantName: name of the new shop to create.
  • name: cash flow name.
• New webhookUrl field (Request Body):
  • URL that receives account registration / deregistration notifications.
  • Required when creating a VA for TPBank or VCB (personal accounts).
• New authorizeLink field (Response Data):
  • Returns the TPBank BIZ web login link where the customer grants authorization.
  • Only returned when linking a TPBank account.

It is the standard foundation for partners to integrate Tingee's full range of payment and device services.

📦 SDK​

Official SDK libraries for fast integration with the Tingee Open API:

• NodeJS — npm package, with TypeScript support
• .NET — NuGet package, compatible with .NET 6+
• Java — Maven/Gradle, with Spring Boot support
• PHP — Composer package, compatible with PHP 7.4+

🏦 Banking & VA​

The complete set of APIs for account linking and transaction processing:

• List supported banks
• List account numbers
• Create / link an account number
• Confirm an account number
• Register for balance notifications
• Confirm notification registration
• Delete an account number
• Confirm deletion
• Refund a transaction
• Transaction history

📱 QR Code​

Supports both static and dynamic QR codes:

Static QR Code:

• Create a static VietQR code following the NAPAS standard

Dynamic QR Code:

• Create a dynamic QR code for each specific order
• Delete a dynamic QR code
• Check the payment status of a dynamic QR code

📦 TingeeBox​

Integrate the TingeeBox payment device at the point of sale:

• Have the device read out its security code
• Read out the transaction amount
• Show a QR code on the device screen
• Create and show a dynamic QR code directly on the device
• Add a device to a shop
• Update the device link status
• List devices by Merchant
• List devices by shop / VA account

🔗 Pay by Bank (Deep Link)​

Accept payments through banking apps with Deep Link:

• Create a payment Deep Link that opens the banking app directly
• Receive the payment result via the partner's callback URL

🌐 Webhook (IPN)​

Receive real-time transaction notifications:

• Payment webhooks for QR and Deep Link
• Balance notification webhooks for VA accounts
• Webhook signature verification for security

⚙️ Operations & Extensions​

Multi-level management for Master Merchants:

• Manage sub-Merchants (create, look up)
• Manage shops (create, update, look up)
• Manage devices (reset a device)
• Business account configuration (create, update, delete)

🔐 Security​

• API key authentication required for every request
• HMAC signature verification for IPN webhooks
• HTTPS enforced on all endpoints
• Default rate limits and request size limits