# Tài liệu Pay2S đính kèm Ngày chụp nội dung tài liệu: 2026-09-29 (UTC). Nguồn: https://docs.pay2s.vn/ Đây là bản tài liệu lưu tại ngày trên, không tự cập nhật sau khi tải. Nội dung các trang được chép đầy đủ bên dưới; không cần mở link để đọc. Các liên kết khác là nguồn tham khảo bổ sung. Nếu thiếu thông tin cần thiết, hãy hỏi người dùng thay vì tự đoán. ## Mục lục - API tra cứu mã số thuế - API hóa đơn điện tử - Đối soát và xử lý lỗi - Email và phân quyền - Hóa đơn điện tử trên Pay2S - Kết nối và cấu hình - Lập và phát hành hóa đơn - Quy tắc hàng hóa - Tra cứu mã số thuế và dữ liệu người mua - Tự động hóa hóa đơn --- Nguồn trang: https://docs.pay2s.vn/hoa-don-dien-tu/api-tra-cuu-ma-so-thue.html # API tra cứu mã số thuế Tra cứu tên người nộp thuế, địa chỉ và trạng thái để hỗ trợ điền thông tin người mua hóa đơn. API không tạo hoặc phát hành hóa đơn. ## Request ```http GET https://api.pay2s.vn/userapi/tax-lookup?mst=0317646674 pay2s-token: BASE64_SECRET_KEY Accept: application/json ``` | Thành phần | Bắt buộc | Ý nghĩa | |---|---|---| | Query `mst` | Có | Chuỗi mã số thuế; giữ số 0 đầu, không chuyển thành số | | Header `pay2s-token` | Có | Base64 chuẩn của chuỗi Secret Key UTF-8, mã hóa đúng một lần | API tra cứu dùng **GET**, không gửi JSON body. `POST` tới đường dẫn này không dùng để tra cứu. Mã doanh nghiệp được hỗ trợ: 10 hoặc 13 chữ số, hoặc mã đơn vị phụ thuộc dạng `0123456789-001`. Tra cứu mã định danh cá nhân 12 số chỉ dành cho tài khoản được Pay2S phê duyệt riêng; tài khoản chưa được cấp quyền nhận HTTP 403. Tài khoản cần gói đang hoạt động, hỗ trợ từ Basic trở lên; gói Free35 không được dùng. Secret Key cửa hàng cũng được hỗ trợ khi khóa và cửa hàng đang hoạt động, kiểm tra gói của tài khoản chủ. ## `pay2s-token` là gì? ```text pay2s-token = Base64(UTF8(Secret Key)) ``` Đây **không phải JWT**, không phải Access Key, không phải token đăng nhập Dashboard và không phải `Base64(accessKey:secretKey)`. Không thêm tiền tố `Bearer` hoặc `Basic`. Không dùng HMAC hay bộ header `X-Signature` của API tạo hóa đơn điện tử. Ví dụ minh họa, không phải khóa dùng thật: ```text Secret Key: example-secret pay2s-token: ZXhhbXBsZS1zZWNyZXQ= ``` Nếu đã có token Base64 đúng định dạng thì dùng trực tiếp, không mã hóa lần hai. Base64 có thể giải mã ngược nên token phải được bảo vệ như Secret Key: chỉ dùng trên backend, không đặt trong URL, frontend hoặc log. ### Postman Đặt `pay2sSecretKey` vào biến bí mật của môi trường Postman. Thêm Pre-request Script: ```js const secret = pm.environment.get('pay2sSecretKey'); if (!secret) throw new Error('Thiếu pay2sSecretKey'); pm.variables.set('pay2sToken', CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(secret))); ``` Trong Headers, đặt `pay2s-token` bằng `{{pay2sToken}}`. Phần Authorization chọn **No Auth**; không dùng đồng thời token đăng nhập hay Bearer tự sinh. ## Ví dụ gọi API ### cURL `PAY2S_TOKEN` là token đã tạo từ Secret Key, lưu trong môi trường server: ```bash curl --get 'https://api.pay2s.vn/userapi/tax-lookup' \ --data-urlencode 'mst=0317646674' \ --header "pay2s-token: $PAY2S_TOKEN" \ --header 'Accept: application/json' ``` ### Node.js (backend) ```js async function lookupTaxCode(mst) { const secret = process.env.PAY2S_SECRET_KEY; if (!secret) throw new Error('Thiếu PAY2S_SECRET_KEY'); const url = new URL('https://api.pay2s.vn/userapi/tax-lookup'); url.searchParams.set('mst', mst); // mst là chuỗi, giữ số 0 đầu const response = await fetch(url, { headers: { 'pay2s-token': Buffer.from(secret, 'utf8').toString('base64'), Accept: 'application/json' }, signal: AbortSignal.timeout(30000) }); const result = await response.json(); if (!response.ok || result.status !== true) { throw new Error(`${response.status}: ${result.message || 'Tra cứu thất bại'}`); } return result.data; } const taxpayer = await lookupTaxCode('0317646674'); // Hiển thị thông tin để người dùng kiểm tra; không tự phát hành hóa đơn ở đây. ``` ### PHP ```php $secret = getenv('PAY2S_SECRET_KEY'); if (!$secret) throw new RuntimeException('Thiếu PAY2S_SECRET_KEY'); $url = 'https://api.pay2s.vn/userapi/tax-lookup?' . http_build_query(['mst' => '0317646674']); $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ['pay2s-token: ' . base64_encode($secret), 'Accept: application/json'], ]); $body = curl_exec($ch); $http = curl_getinfo($ch, CURLINFO_HTTP_CODE); $error = curl_error($ch); curl_close($ch); if ($body === false) throw new RuntimeException($error); $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); if ($http !== 200 || ($result['status'] ?? false) !== true) { throw new RuntimeException($result['message'] ?? 'Tra cứu thất bại'); } $taxpayer = $result['data']; ``` ## Response thành công HTTP 200, ví dụ theo cấu trúc hiện tại: ```json { "status": true, "message": "Tra cứu mã số thuế thành công.", "data": { "taxCode": "0317646674", "companyName": "CÔNG TY TNHH CÔNG NGHỆ EZ", "address": "Số 72, Đường số 6, KDC Cityland Park Hills, Phường Gò Vấp, Thành phố Hồ Chí Minh, Việt Nam", "status": {"code": "00", "name": "NNT đã được cấp MST"}, "canIssueInvoice": true }, "meta": {"fresh": true}, "request_id": "TAX-20260918090000-1234ABCD" } ``` Tên/địa chỉ trong ví dụ là dữ liệu minh họa theo ảnh kết quả, không phải kết quả vừa tra cứu trực tiếp. | Trường | Ý nghĩa | |---|---| | `status` ngoài cùng | Request tra cứu có thành công hay không | | `data.taxCode` | Mã số thuế tìm được | | `data.companyName` | Tên người nộp thuế/đơn vị | | `data.address` | Địa chỉ do nguồn tra cứu trả về | | `data.status.code` | Mã trạng thái người nộp thuế, **chuỗi**; giữ nguyên `"00"` | | `data.status.name` | Mô tả trạng thái từ nguồn tra cứu | | `data.canIssueInvoice` | Cờ khả năng xuất hóa đơn từ nguồn tra cứu; không có nghĩa đã phát hành hoặc đã được bật quyền Production trên Pay2S | | `meta.fresh` | Bản hiện tại tra cứu mới, không dùng kết quả cache | | `request_id` | Mã đối soát khi liên hệ hỗ trợ; cũng có ở header `X-Request-ID` khi vào bước tra cứu | Bản phản hồi cũ có thể dùng `meta.cached: false` thay `meta.fresh: true`. Không dùng các trường `meta` để quyết định thanh toán hoặc phát hành hóa đơn. Không nhầm `status: true` ngoài cùng với trạng thái thuế hợp lệ. Luồng tự động HĐĐT trên Pay2S chỉ tiếp tục với mã trạng thái thuế `"00"`; cần kiểm tra thông tin/mẫu và quyền phát hành như bình thường. ## Lỗi và giới hạn | HTTP | Cách xử lý | |---|---| | 401 | Thiếu/sai `pay2s-token`; kiểm tra Secret Key, Base64 đúng một lần, không thêm Bearer | | 403 | Gói hết hạn/không đủ điều kiện hoặc chưa được cấp quyền tra cứu mã cá nhân | | 404 | Không tìm thấy thông tin mã số thuế | | 422 | MST sai định dạng | | 429 | Vượt giới hạn tốc độ/ngày; đợi theo header `Retry-After` hoặc `retry_after` trong JSON | | 502 / 504 | Nguồn tra cứu lỗi/timeout; thử lại có giãn cách, không tự kết luận MST sai | | 503 | Dịch vụ phụ trợ chưa sẵn sàng; thử lại sau hoặc liên hệ hỗ trợ | Giới hạn tốc độ được trả trong `X-RateLimit-Limit`, `X-RateLimit-Remaining`; hạn mức ngày trong `X-Daily-RateLimit-Limit`, `X-Daily-RateLimit-Remaining`. Đọc giá trị server trả về, không gọi lặp liên tục khi nhận 429. ## Dùng với Collection Link V2 hoặc API HĐĐT Sau khi người dùng kiểm tra kết quả: | Kết quả tra cứu | Metadata Collection Link V2 | API tạo nháp HĐĐT | |---|---|---| | `taxCode` | `customerInfo.taxCode` | `buyer_tax_code` | | `companyName` (đơn vị/doanh nghiệp) | `customerInfo.buyerCompanyName` | `buyer_name` | | `address` | `customerInfo.address` | `buyer_address` | Không tự gán tên doanh nghiệp vào họ tên người liên hệ. Với cá nhân/hộ kinh doanh, kiểm tra đúng loại người mua trước khi ánh xạ. Xem [Collection Link V2](/api/collection-link-v2), [API hóa đơn điện tử](/hoa-don-dien-tu/api) và [quy tắc dữ liệu người mua](/hoa-don-dien-tu/tra-cuu-ma-so-thue). Nếu Collection Link đã tự xử lý HĐĐT cho đơn, không đồng thời gọi tạo hóa đơn độc lập cho cùng đơn. --- Nguồn trang: https://docs.pay2s.vn/hoa-don-dien-tu/api.html # API hóa đơn điện tử API dành cho **server của khách hàng** tạo nháp, gửi nháp tới nhà cung cấp, phát hành và tra cứu hóa đơn điện tử qua kết nối đã cấu hình trên Pay2S. API này không tạo link thanh toán, không cộng tiền và không tự xác minh đơn hàng bên ngoài đã thanh toán. ## Chuẩn bị 1. Tài khoản chính có gói Basic trở lên và được bật tính năng HĐĐT. 2. Trong **Xuất hóa đơn tự động**, tạo kết nối, kiểm tra đăng nhập nhà cung cấp, đồng bộ mẫu và chọn mẫu mặc định. Nếu truyền `store_id`, cửa hàng phải được gán mẫu thuộc kết nối đó. 3. Lấy **Partner Code, Access Key, Secret Key của tài khoản chính Pay2S** (cùng bộ khóa dùng tích hợp thanh toán). Không dùng khóa Partner API độc lập, khóa nhân viên/cửa hàng hoặc token đăng nhập Dashboard. 4. Dùng kết nối Sandbox để kiểm tra. Tài khoản demo không được gọi bộ API này. Production cần được Pay2S bật quyền phát hành thật. Không gửi thông tin đăng nhập nhà cung cấp hóa đơn trong request. Chỉ giữ Secret Key ở backend của bạn. ## Endpoint và xác thực Tất cả thao tác dùng: ```http POST https://api.pay2s.vn/api/v1/einvoices Content-Type: application/json X-Partner-Code: YOUR_PARTNER_CODE X-Access-Key: YOUR_ACCESS_KEY X-Timestamp: UNIX_SECONDS X-Signature: LOWERCASE_HMAC_SHA256_HEX ``` `X-Timestamp` là Unix timestamp 10 chữ số, lệch giờ server tối đa 300 giây. JSON tối đa 256 KiB. Giới hạn **60 request/phút/tài khoản**, tính chung các thao tác; HTTP 429 thì đợi phút kế tiếp. Chuỗi ký gồm 4 dòng, ngăn bằng ký tự LF (`\n`), **không thêm xuống dòng cuối**: ```text {timestamp} POST /api/v1/einvoices {sha256_hex_cua_nguyen_body_JSON} ``` `signature = HMAC-SHA256(secret_key, chuỗi_ký)`, xuất hex chữ thường. Ký đúng chuỗi JSON sẽ gửi; không serialize lại body sau khi ký. Timestamp và chữ ký nằm ở header, không nằm trong JSON. Không thêm query string vào endpoint. ### Node.js ```js import { createHash, createHmac } from 'node:crypto'; async function einvoice(payload) { const path = '/api/v1/einvoices'; const body = JSON.stringify(payload); const timestamp = String(Math.floor(Date.now() / 1000)); const digest = createHash('sha256').update(body, 'utf8').digest('hex'); const canonical = `${timestamp}\nPOST\n${path}\n${digest}`; const signature = createHmac('sha256', process.env.PAY2S_SECRET_KEY) .update(canonical, 'utf8').digest('hex'); const response = await fetch(`https://api.pay2s.vn${path}`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Partner-Code': process.env.PAY2S_PARTNER_CODE, 'X-Access-Key': process.env.PAY2S_ACCESS_KEY, 'X-Timestamp': timestamp, 'X-Signature': signature }, body, signal: AbortSignal.timeout(90000) }); return { httpStatus: response.status, result: await response.json() }; } console.log(await einvoice({ action: 'connections' })); ``` ### PHP cURL ```php function einvoice(array $payload): array { $path = '/api/v1/einvoices'; $body = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR); $timestamp = (string)time(); $canonical = $timestamp . "\nPOST\n" . $path . "\n" . hash('sha256', $body); $signature = hash_hmac('sha256', $canonical, getenv('PAY2S_SECRET_KEY')); $ch = curl_init('https://api.pay2s.vn' . $path); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => $body, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 90, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'X-Partner-Code: ' . getenv('PAY2S_PARTNER_CODE'), 'X-Access-Key: ' . getenv('PAY2S_ACCESS_KEY'), 'X-Timestamp: ' . $timestamp, 'X-Signature: ' . $signature, ], ]); $response = curl_exec($ch); $httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE); $error = curl_error($ch); curl_close($ch); if ($response === false) throw new RuntimeException($error); return ['httpStatus' => $httpStatus, 'result' => json_decode($response, true, 512, JSON_THROW_ON_ERROR)]; } ``` ## 1. Lấy danh sách kết nối ```json {"action":"connections"} ``` Trả về kết nối đang hoạt động thuộc tài khoản đã xác thực, không trả mật khẩu/token của nhà cung cấp: ```json {"status":true,"data":{"connections":[{"id":12,"name":"Hóa đơn thử","provider":"matbao_hddt","environment":"sandbox"}]}} ``` Các ID trong ví dụ là minh họa; dùng ID thực tế từ API. ID là số nguyên JSON ở request. ## 2. Tạo nháp tại Pay2S ```json { "action": "create_draft", "connection_id": 12, "environment": "sandbox", "external_ref": "ORDER_20260918_001", "buyer_contact_name": "Bán cho người tiêu dùng", "payment_method": "TM/CK", "note": "Đơn hàng từ website", "items": [ {"code":"SP01","name":"Sản phẩm mẫu","unit":"Cái","quantity":2,"unit_price":100000,"tax_rate":10} ] } ``` Thành công lần đầu: HTTP **201**. Chưa gọi nhà cung cấp và chưa phát hành. ```json {"status":true,"message":"Đã tạo bản nháp Sandbox.","data":{"id":101,"status":"draft","external_ref":"ORDER_20260918_001"}} ``` Lưu `data.id` làm `invoice_id` cho các bước sau. | Trường | Quy định | |---|---| | `connection_id` | Bắt buộc, ID kết nối đang hoạt động của tài khoản | | `environment` | Bắt buộc `sandbox` hoặc `production`, phải khớp kết nối | | `external_ref` | Bắt buộc, mã đơn riêng của bạn; 1–100 ký tự chữ/số/`_`/`-`, phân biệt hoa thường | | `store_id` | Tùy chọn, số nguyên; bỏ trống hoặc 0 để dùng mẫu mặc định của kết nối | | `buyer_name` | Tên đơn vị mua hàng, tối đa 400 ký tự | | `buyer_tax_code` | Mã số thuế, tối đa 14 ký tự | | `buyer_citizen_id` | CCCD, tối đa 12 ký tự | | `buyer_contact_name` | Họ tên người mua, tối đa 100 ký tự | | `buyer_address` | Địa chỉ, tối đa 400 ký tự | | `buyer_phone` | Tối đa 20 ký tự | | `buyer_email` | Email hợp lệ, tối đa 50 ký tự | | `payment_method` | Mặc định `TM/CK`, tối đa 50 ký tự | | `note` | Tối đa 255 ký tự | | `items` | Mảng 1–100 dòng | | `confirm_production` | Boolean `true` bắt buộc khi tạo nháp Production; vẫn chưa phát hành | Phải có `buyer_name` hoặc `buyer_contact_name`. Thông tin người mua dùng cùng quy tắc Dashboard: doanh nghiệp cần đủ tên đơn vị, MST, địa chỉ; cá nhân cần họ tên và địa chỉ. Thiếu bộ thông tin định danh đầy đủ thì tên hiển thị chuyển thành **Bán cho người tiêu dùng**, bỏ thông tin định danh rời rạc. Đọc và kiểm tra dữ liệu nháp bằng `detail` trước khi phát hành. | Trường dòng hàng | Quy định | |---|---| | `name` | Tên hàng bắt buộc; tối đa 500 ký tự | | `code` | Mã hàng tùy chọn, tối đa 50 ký tự | | `unit` | Đơn vị tính tùy chọn, tối đa 50 ký tự | | `quantity` | Số JSON > 0, làm tròn 4 chữ số thập phân | | `unit_price` | Số JSON ≥ 0, làm tròn 2 chữ số thập phân | | `tax_rate` | Bắt buộc, giá trị hệ thống nhận: -2, -1, 0, 3.5, 5, 8, 10; phải phù hợp loại mẫu và nhà cung cấp | | `direct_vat_rate` | Tùy chọn: 1, 2, 3, 5; dùng khi giảm thuế cho mẫu hóa đơn bán hàng trực tiếp | | `vat_reduction_eligible` | Boolean, mặc định false; hệ thống kiểm tra điều kiện/mẫu khi áp dụng | `-1` là không chịu thuế, `-2` là không kê khai tính nộp thuế. Các mã này là quy ước dữ liệu API; chọn đúng theo nghiệp vụ và mẫu đang dùng. Mỗi số và giá trị mỗi dòng tối đa 10^12. Tổng tiền do backend tính, không nhận tổng do client tự khai. Không truyền `owner_user_id`, `user_id`, `source_order_id`, `template_id`, `provider`, `credentials` hoặc `idempotency_key`. ### Chống trùng và timeout - `external_ref` duy nhất theo **tài khoản chính**, xuyên các kết nối/môi trường. Nên đặt tiền tố khác nhau cho đơn Sandbox và Production. - Cùng mã và dữ liệu: trả lại cùng ID, HTTP 200, `duplicate: true`. Không tạo thêm hóa đơn. - Cùng mã nhưng thay đổi dữ liệu/kết nối: HTTP 409. Không tự đổi mã đơn để vượt lỗi này. - Đã xóa nháp trên Dashboard thì mã cũ không được tạo lại. Dùng mã mới chỉ khi bạn thực sự muốn tạo hóa đơn thay thế. - Nếu timeout khi `create_draft`, ký lại request với timestamp mới nhưng giữ nguyên mã và dữ liệu. Các giá trị số nên giữ nguyên cách biểu diễn giữa các lần gọi (ví dụ `2` khác `2.0` trong dấu vân tay dữ liệu). - API có khóa xử lý đồng thời; HTTP 409 “đang được xử lý” thì đợi vài giây rồi gọi lại. ## 3. Gửi nháp sang nhà cung cấp ```json {"action":"submit_draft","connection_id":12,"environment":"sandbox","invoice_id":101} ``` Dùng logic tạo nháp đã có trên Dashboard. Bản nháp đã có mã nhà cung cấp sẽ không được tạo lại. Đây chưa phải thao tác ký/phát hành. Kết quả và khả năng tạo nháp phụ thuộc nhà cung cấp. ## 4. Phát hành Sau khi gửi nháp thành công và đã kiểm tra thông tin: ```json {"action":"publish","connection_id":12,"environment":"sandbox","invoice_id":101} ``` Với Production, cả bước tạo/gửi nháp/phát hành đều cần `"environment":"production"` và **`"confirm_production":true`**, đúng kết nối Production và quyền phát hành của tài khoản. API không tự chuyển môi trường và không tự bật quyền. `publish` thực hiện ký/cấp số hóa đơn thật ở Production. Không dùng để điều chỉnh hoặc thay thế hóa đơn đã phát hành. Gọi lại hóa đơn đã `issued` trả trạng thái đã phát hành, không phát hành lần nữa. ## 5. Tra cứu và đồng bộ trạng thái Đọc dữ liệu đã lưu trên Pay2S, không gọi nhà cung cấp: ```json {"action":"detail","connection_id":12,"environment":"sandbox","invoice_id":101} ``` Kết quả nằm trong `data.invoice`: ID, trạng thái, môi trường, mẫu/ký hiệu, số hóa đơn (`invoice_number`), người mua, `items`, `subtotal`, `tax_total`, `grand_total`, thời gian và `provider_pdf_url`/`provider_xml_url` khi nhà cung cấp có trả link. Có `has_provider_reference` để kiểm tra đã có mã nhà cung cấp chưa. Yêu cầu đồng bộ từ nhà cung cấp: ```json {"action":"sync","connection_id":12,"environment":"sandbox","invoice_id":101} ``` Sau `sync`, gọi `detail` để lấy bản cập nhật. Một số nhà cung cấp cần đủ mã tham chiếu trước khi đồng bộ được. | Trạng thái | Cách xử lý | |---|---| | `draft` | Nháp; xem `has_provider_reference` để biết đã gửi nhà cung cấp chưa | | `processing` | Đang xử lý, đợi và tra cứu | | `issued` | Đã phát hành | | `failed` | Xem lỗi và xử lý trên Dashboard; không tự tạo đơn mới để thử lại | | `unknown` | Kết quả chưa rõ, đồng bộ/đối soát trước khi thử lại | Nếu timeout ở bước gửi nháp/phát hành, **tra cứu trước**. Không tạo hóa đơn mới chỉ vì client không nhận được phản hồi. API chặn gửi/phát hành lại khi `processing` hoặc `unknown`. Phiên bản này dùng polling, chưa có webhook riêng cho trạng thái HĐĐT. ## 6. Lấy PDF/XML ```json {"action":"files","connection_id":12,"environment":"sandbox","invoice_id":101,"file_type":"all"} ``` `file_type`: `all` (mặc định), `pdf`, `xml`. Kết quả JSON có `data.pdf_base64`, `data.xml_base64`; giải mã Base64 thành tệp. Trường có thể rỗng nếu nhà cung cấp không hỗ trợ. Một số nhà cung cấp chỉ cho tải sau khi phát hành. API không luôn trả một URL tải công khai. ## Mã HTTP | Mã | Ý nghĩa | |---|---| | 200 / 201 | Thành công / tạo nháp mới | | 400 / 413 / 415 | JSON sai / quá lớn / sai Content-Type | | 401 | Sai khóa, chữ ký, timestamp hoặc tài khoản bị khóa | | 403 | Sai loại tài khoản, không đủ gói/quyền hoặc demo | | 404 | Không có hóa đơn/kết nối thuộc tài khoản này | | 405 | Không phải POST | | 409 | Mã đơn trùng dữ liệu khác, đang xử lý hoặc cần đối soát | | 422 | Dữ liệu không hợp lệ, chưa cấu hình mẫu hoặc nhà cung cấp từ chối | | 429 | Quá 60 request/phút | | 500 / 502 / 503 | Lỗi hệ thống/nhà cung cấp hoặc chưa sẵn sàng; giữ mã đơn, kiểm tra trạng thái trước khi thử lại | Luôn kiểm tra cả HTTP và `status` trong JSON. Khi có `error_reference`, gửi mã này cho hỗ trợ; không gửi Secret Key. --- Nguồn trang: https://docs.pay2s.vn/hoa-don-dien-tu/doi-soat-va-xu-ly-loi.html # Đối soát và xử lý lỗi ## Màn hình Đối soát Mỗi kết nối hóa đơn có tab **Đối soát** để so sánh ba nguồn dữ liệu: - Giao dịch ngân hàng: mã giao dịch, tài khoản nhận và số tiền thực nhận. - Đơn hàng Pay2S: mã đơn, cửa hàng và số tiền đã thanh toán. - Hóa đơn điện tử: số hóa đơn, nhà cung cấp, trạng thái và tổng thanh toán. Các trạng thái gồm **Đã khớp**, **Chưa kiểm tra**, **Không tìm thấy giao dịch**, **Sai tài khoản nhận**, **Lệch số tiền**, **Đơn hàng không hợp lệ** và **Trùng hóa đơn**. Có thể lọc theo từ khóa, trạng thái và khoảng ngày. Nút **Kiểm tra lại** chỉ đọc và đối chiếu dữ liệu hiện có, sau đó ghi thêm một lần kiểm tra vào lịch sử. Thao tác này không tạo nháp, không phát hành và không gọi API phát hành của nhà cung cấp. Nút **Lịch sử** hiển thị tối đa 100 lần kiểm tra gần nhất của đơn. Nút **Kiểm tra tất cả** đối chiếu toàn bộ danh sách theo bộ lọc hiện tại, tối đa 500 đơn mỗi lượt. Nếu còn nhiều hơn, hệ thống sẽ báo số đơn còn lại để người dùng tiếp tục lượt kế tiếp. Nút **Xử lý** đưa người dùng đến đúng nghiệp vụ: lập hóa đơn khi thanh toán đã khớp, mở bản nháp để kiểm tra hoặc xóa và lập lại, mở giao dịch khi dữ liệu ngân hàng sai lệch, hoặc mở danh sách khi phát hiện trùng hóa đơn. Hóa đơn đã phát hành chỉ được xem; không có thao tác sửa trực tiếp. Khi cần thay đổi phải thực hiện nghiệp vụ điều chỉnh hoặc thay thế theo quy định và khả năng của nhà cung cấp. Khi bật **Kiểm tra thanh toán trước khi phát hành**, cron tự động kiểm tra tối đa 100 đơn chưa kiểm tra hoặc đang có sai lệch trong mỗi lượt chạy. Một kết quả lỗi chỉ được kiểm tra lại sau tối thiểu 15 phút để tránh tạo lịch sử trùng lặp. Việc tự đối soát không tự phát hành lại hóa đơn và không gọi API nhà cung cấp. ## Hóa đơn Pay2S và hóa đơn nhà cung cấp - **Hóa đơn Pay2S:** chỉ gồm hóa đơn được tạo thủ công, từ đơn hàng hoặc tự động hóa qua Pay2S trong kết nối hiện tại. - **Hóa đơn nhà cung cấp:** tra cứu trực tiếp dữ liệu tại nhà cung cấp theo mẫu, ngày, số hóa đơn, khách hàng, loại và trạng thái. ## Xuất Excel hoặc CSV Tại **Hóa đơn Pay2S**, có thể xuất dữ liệu cho kế toán gồm: - Mã đơn hàng và mã hóa đơn. - Mã tra cứu. - Người mua và tổng tiền. - Trạng thái hóa đơn và gửi email. - Cửa hàng và nhà cung cấp. ## Kiểm tra sức khỏe Mục **Kiểm tra sức khỏe** cho biết: - Cấu hình dữ liệu đã đầy đủ chưa. - Kết nối nhà cung cấp và SMTP có hoạt động không. - Cron tự động hóa và đồng bộ trạng thái chạy lần cuối khi nào. - Có bao nhiêu đơn tồn trong hàng chờ. - Có bao nhiêu hóa đơn lỗi hoặc cần đối soát. ## Sự cố thường gặp | Hiện tượng | Nguyên nhân thường gặp | Cách xử lý | |---|---|---| | Kết nối chưa sẵn sàng | Sai môi trường hoặc thông tin đăng nhập | Sửa kết nối rồi bấm **Kiểm tra** | | Không thấy mẫu | Chưa đồng bộ hoặc mẫu không hoạt động | Đồng bộ mẫu và kiểm tra tài khoản nhà cung cấp | | Không gắn cửa hàng nhưng không lập được | Chưa chọn mẫu mặc định | Chọn một mẫu đang hoạt động làm mặc định | | Đơn nằm mãi trong hàng chờ | Cron chưa chạy hoặc đơn thiếu điều kiện | Xem Kiểm tra sức khỏe, Tự động hóa và Nhật ký | | Thanh toán chưa được đối chiếu | Không tìm thấy mã giao dịch, sai tài khoản nhận hoặc lệch số tiền | Kiểm tra giao dịch ngân hàng gắn với đơn; Pay2S sẽ không gọi nhà cung cấp cho tới khi dữ liệu khớp | | Tổng hàng hóa không khớp | Thiếu dòng hàng, sai giá hoặc thuế | Kiểm tra đơn và quy tắc hàng hóa | | Hiện “Bán cho người tiêu dùng” | Thiếu bộ thông tin người mua hợp lệ | Bổ sung họ tên + địa chỉ, hoặc tên đơn vị + MST + địa chỉ | | MST có trạng thái khác `00` | Người nộp thuế không ở trạng thái đang hoạt động | Dừng phát hành và kiểm tra lại tại cổng tra cứu của Tổng cục Thuế | | Đơn có MST nhưng tự động hóa không chạy | Tự động kiểm tra MST đang bật và trạng thái không phải `00` | Xem Hàng chờ, Nhật ký và kiểm tra lại thông tin người mua | | Không có nút Phát hành | Không phải bản nháp hoặc thiếu quyền | Kiểm tra trạng thái và vai trò | | Không mở được PDF | Trình duyệt chặn popup hoặc chưa có PDF | Cho phép popup, đồng bộ rồi thử lại | | Không gửi được email | Email tắt, SMTP lỗi hoặc thiếu email người mua | Kiểm tra cấu hình và gửi thử | | Trạng thái cần đối soát | Chưa xác định nhà cung cấp đã nhận yêu cầu | Không tạo lại; xem Nhật ký và đồng bộ trạng thái | ## Khi cần hỗ trợ Cung cấp cho Pay2S: - Mã lỗi dạng `EIC-...`. - Mã tra cứu hoặc mã hóa đơn Pay2S. - Thời điểm xảy ra lỗi và môi trường Sandbox/Production. Không gửi mật khẩu, Access Key, Secret Key hoặc file chứa thông tin đăng nhập. --- Nguồn trang: https://docs.pay2s.vn/hoa-don-dien-tu/email-va-phan-quyen.html # Email và phân quyền ## Gửi hóa đơn qua email Trong cấu hình email, có thể chọn: - **Hệ thống Pay2S:** gửi bằng máy chủ email của Pay2S. - **SMTP riêng:** gửi bằng tên miền và tài khoản email của doanh nghiệp. Với SMTP riêng, nhập máy chủ, cổng, kiểu mã hóa, tài khoản, mật khẩu, email người gửi và tên người gửi. Sau khi lưu, bấm **Gửi thử**. Chỉ bật gửi tự động khi kiểm tra email thành công. Đơn cần có địa chỉ email người mua để gửi. ## Phân quyền nhân viên cửa hàng | Vai trò | Quyền HĐĐT | |---|---| | Chủ tài khoản | Quản lý kết nối, cấu hình, lập nháp, phát hành và tải PDF | | Quản lý | Xem, lập nháp, phát hành và tải PDF trong cửa hàng được phân công | | Thu ngân | Xem, lập nháp và tải PDF; không được phát hành | | Người xem | Chỉ xem và tải PDF | Nhân viên chỉ thấy dữ liệu của cửa hàng được phân công. Nếu một nhân viên thuộc nhiều cửa hàng, họ cần chọn cửa hàng đang thao tác trước khi xem hoặc lập hóa đơn. ::: info Bảo vệ quyền truy cập Việc biết đường dẫn trực tiếp không làm tăng quyền. Backend vẫn kiểm tra vai trò và cửa hàng trên từng yêu cầu. ::: --- Nguồn trang: https://docs.pay2s.vn/hoa-don-dien-tu/index.html # Hóa đơn điện tử trên Pay2S Pay2S giúp doanh nghiệp kết nối tài khoản hóa đơn điện tử, lập hóa đơn từ đơn hàng đã thanh toán, quản lý theo cửa hàng và tự động hóa quá trình tạo hóa đơn. Pay2S hỗ trợ kết nối **Mắt Bão eInvoice, Viettel VInvoice, Bkav eHoadon, MISA meInvoice, FPT.eInvoice và M-Invoice 2.0**. Chọn nhà cung cấp đang sử dụng tại mục **Xuất hóa đơn tự động** để thiết lập kết nối và mẫu hóa đơn. ## Bạn có thể làm gì? - Kết nối nhiều tài khoản HĐĐT cho các pháp nhân khác nhau. - Đồng bộ và chọn mẫu hóa đơn. - Lập hóa đơn thủ công hoặc từ đơn hàng Pay2S. - Tạo bản nháp để kiểm tra trước khi phát hành. - Tự động tạo nháp hoặc tự động phát hành khi đơn đủ điều kiện. - Tra cứu và tự động kiểm tra trạng thái mã số thuế trước khi phát hành. - Quản lý theo toàn tài khoản hoặc từng cửa hàng. - Xem, tải PDF, gửi email và xuất dữ liệu đối soát. Nếu website tự gọi API tạo đơn, hãy dùng [Collection Link V2](/api/collection-link-v2) để gửi kèm thông tin người mua và hàng hóa. Nếu hệ thống của bạn cần trực tiếp tạo nháp, phát hành và tra cứu hóa đơn điện tử qua kết nối Pay2S, dùng [API hóa đơn điện tử](/hoa-don-dien-tu/api). API này hoạt động độc lập với việc tạo link thanh toán. ## Các khái niệm cần biết ### Kết nối nhà cung cấp Là tài khoản HĐĐT của doanh nghiệp tại nhà cung cấp. Một tài khoản Pay2S có thể tạo nhiều kết nối. ### Sandbox và Production | Môi trường | Mục đích | |---|---| | Sandbox | Thử cấu hình, mẫu, người mua và hàng hóa; không tạo hóa đơn thật | | Production | Phát hành hóa đơn thật, ký và cấp số tại nhà cung cấp | ::: danger Lưu ý về Production Sandbox và Production là hai kết nối riêng. Hóa đơn Production sau khi phát hành không thể xóa bằng chức năng xóa bản nháp. ::: ### Mẫu mặc định Mẫu dùng cho hóa đơn không gắn cửa hàng. Mỗi kết nối cần có một mẫu mặc định đang hoạt động. ### Gán cửa hàng Cho phép một cửa hàng sử dụng kết nối và mẫu riêng. Nếu không dùng tính năng Cửa hàng, bạn vẫn có thể lập hóa đơn bằng mẫu mặc định. ### Bản nháp và hóa đơn đã phát hành - **Bản nháp:** đã tạo tại nhà cung cấp nhưng chưa ký, chưa cấp số; có thể kiểm tra hoặc xóa. - **Đã phát hành:** đã được ký và cấp số; không thể xóa như bản nháp. ## Quy trình khuyến nghị 1. [Tạo và kiểm tra kết nối Sandbox](./ket-noi-va-cau-hinh.md). 2. Đồng bộ mẫu và chọn mẫu mặc định. 3. [Tạo một hóa đơn nháp thủ công](./lap-va-phat-hanh.md). 4. Kiểm tra nội dung và PDF rồi phát hành thử. 5. [Cấu hình quy tắc hàng hóa](./quy-tac-hang-hoa.md) nếu dùng website hoặc phần mềm bán hàng. 6. [Kiểm tra cách tra cứu mã số thuế](./tra-cuu-ma-so-thue.md) và quy tắc dữ liệu người mua. 7. [Bật tự động tạo nháp](./tu-dong-hoa.md) và theo dõi trong vài ngày. 8. Tạo kết nối Production riêng khi dữ liệu đã ổn định. ## Checklist trước khi dùng Production - [ ] Kết nối Sandbox đã kiểm tra thành công. - [ ] Đã đồng bộ và chọn đúng mẫu hóa đơn. - [ ] Đã thử người mua lấy và không lấy hóa đơn. - [ ] Đã kiểm tra MST hoạt động và đối chiếu dữ liệu với nguồn chính thức. - [ ] Tổng hóa đơn khớp số tiền đã thanh toán. - [ ] Tên hàng, đơn vị và thuế suất hiển thị đúng. - [ ] Đã xem và tải được PDF. - [ ] Đã thử tạo nháp, phát hành và gửi email nếu sử dụng. - [ ] Đã kiểm tra quyền nhân viên cửa hàng. - [ ] Cron tự động hóa hoạt động ổn định nếu sử dụng. > Tài liệu cập nhật ngày 14/08/2026. --- Nguồn trang: https://docs.pay2s.vn/hoa-don-dien-tu/ket-noi-va-cau-hinh.html # Kết nối và cấu hình Nên thiết lập đầy đủ trên **Sandbox** trước, sau đó tạo một kết nối **Production** riêng. ## 1. Thêm kết nối 1. Vào **Tích hợp nhà cung cấp HĐĐT**. 2. Chọn nhà cung cấp rồi bấm **Thêm kết nối**. 3. Nhập tên gợi nhớ, môi trường, mã số thuế và tài khoản do nhà cung cấp cấp. 4. Nếu chọn Production, đọc cảnh báo và xác nhận đây là môi trường hóa đơn thật. 5. Lưu kết nối. Thông tin đăng nhập được Pay2S mã hóa. Không gửi mật khẩu nhà cung cấp qua email, tin nhắn hoặc ảnh chụp màn hình. ## 2. Kiểm tra kết nối Bấm **Kiểm tra** tại kết nối vừa tạo. - **Kết nối tốt:** có thể đồng bộ mẫu và sử dụng. - **Kiểm tra thất bại:** kiểm tra môi trường, mã số thuế, tài khoản và mật khẩu. Kết nối phải đang bật và kiểm tra thành công trước khi dùng tự động hóa. ## 3. Đồng bộ mẫu hóa đơn 1. Mở chi tiết kết nối. 2. Chọn **Mẫu hóa đơn**. 3. Bấm **Đồng bộ mẫu**. 4. Kiểm tra mẫu số, ký hiệu và số hóa đơn còn lại. 5. Chọn một mẫu đang hoạt động làm **Mẫu mặc định**. Mẫu cũ hoặc hết số vẫn có thể xuất hiện trong lịch sử nhưng không nên dùng để phát hành mới. ## 4. Gán cho cửa hàng Nếu doanh nghiệp dùng tính năng Cửa hàng: 1. Chọn **Gán cửa hàng**. 2. Chọn mẫu cho từng cửa hàng. 3. Bấm **Gán mẫu** hoặc **Cập nhật**. Mỗi cửa hàng chỉ có một cấu hình đang hoạt động trong cùng môi trường. Khi gán sang kết nối khác, quyền sử dụng sẽ chuyển sang kết nối mới. ::: tip Không sử dụng Cửa hàng Bỏ qua bước gán cửa hàng. Hóa đơn sẽ sử dụng mẫu mặc định của kết nối. ::: ## Các mục trong một kết nối | Mục | Công dụng | |---|---| | Tổng quan | Trạng thái kết nối, mẫu mặc định và sức khỏe hệ thống | | Mẫu hóa đơn | Đồng bộ, tìm kiếm và chọn mẫu mặc định | | Gán cửa hàng | Gán kết nối và mẫu cho từng cửa hàng | | Hàng hóa | Thiết lập quy tắc đổi mã sản phẩm thành nội dung hóa đơn | | Hóa đơn Pay2S | Các hóa đơn được tạo qua Pay2S trong kết nối hiện tại | | Hàng chờ | Đơn đã thanh toán và yêu cầu hóa đơn nhưng chưa được lập | | Tự động hóa | Tự tạo nháp, tự phát hành và cấu hình dữ liệu mặc định | | Hóa đơn nhà cung cấp | Tra cứu trực tiếp dữ liệu tại nhà cung cấp | | Tạo hóa đơn | Lập hóa đơn thủ công hoặc từ đơn trong hàng chờ | | Nhật ký | Theo dõi thao tác và lỗi do nhà cung cấp trả về | --- Nguồn trang: https://docs.pay2s.vn/hoa-don-dien-tu/lap-va-phat-hanh.html # Lập và phát hành hóa đơn ## Tạo hóa đơn thủ công 1. Mở kết nối cần sử dụng. 2. Chọn **Tạo hóa đơn**. 3. Chọn phạm vi phát hành. 4. Nhập người mua và hàng hóa. 5. Bấm **Xem trước hóa đơn**. 6. Chọn **Tạo hóa đơn nháp** hoặc **Tạo và phát hành**. ## Phạm vi phát hành - **Không gắn cửa hàng:** dùng mẫu mặc định của kết nối. - **Cửa hàng cụ thể:** dùng mẫu đã gán cho cửa hàng đó. ## Thông tin người mua Hai trường có ý nghĩa khác nhau: - **Tên đơn vị mua hàng:** tên công ty, doanh nghiệp hoặc tổ chức. - **Họ tên người mua hàng:** người trực tiếp mua hoặc người liên hệ. Nếu người mua không lấy hóa đơn, tích **Người mua không lấy hóa đơn**. Pay2S sẽ dùng nội dung **Bán cho người tiêu dùng**. - Xuất cho cá nhân: tối thiểu nên có **họ tên và địa chỉ**. - Xuất cho doanh nghiệp: kiểm tra **tên đơn vị, mã số thuế và địa chỉ**. Bạn có thể bấm **Tra cứu** cạnh ô mã số thuế để Pay2S hỗ trợ điền tên đơn vị, địa chỉ và kiểm tra trạng thái người nộp thuế. Kết quả chỉ mang tính tham khảo và cần được đối chiếu trước khi phát hành. Xem [Tra cứu mã số thuế và dữ liệu người mua](./tra-cuu-ma-so-thue.md). ## Hàng hóa, dịch vụ Mỗi dòng gồm tên hàng, mã hàng, đơn vị tính, số lượng, đơn giá trước thuế và thuế suất. | Giá trị | Ý nghĩa | |---|---| | `-2` | Không kê khai, tính nộp thuế | | `-1` | Không chịu thuế | | `0` | Thuế suất 0% | | `3.5` | Thuế suất khác 3,5% | | `5` | Thuế suất 5% | | `8` | Thuế suất 8% | | `10` | Thuế suất 10% | Pay2S tính lại tiền hàng, tiền thuế và tổng thanh toán. Với hóa đơn lập từ đơn hàng, tổng hóa đơn phải khớp số tiền đã thanh toán. ## Khi nào nên tạo nháp? - Dùng **Tạo hóa đơn nháp** khi cần kế toán kiểm tra trước. - Dùng **Tạo và phát hành** khi dữ liệu đã chắc chắn chính xác. ::: warning Với hóa đơn thật Trước khi phát hành Production, kiểm tra kỹ người mua, mã số thuế, địa chỉ, hàng hóa, thuế suất và tổng tiền. ::: ## Xem, tải, phát hành và xóa Trong danh sách hoặc cửa sổ chi tiết: - **Chi tiết:** xem dữ liệu người mua, hàng hóa và đối chiếu. - **Xem PDF:** mở hóa đơn trong tab mới. - **Tải PDF:** tải hóa đơn về thiết bị. - **Phát hành:** chỉ có với bản nháp và tài khoản đủ quyền. - **Xóa nháp:** xóa bản nháp trên Pay2S và nhà cung cấp; không áp dụng cho hóa đơn đã phát hành. Nếu trình duyệt chặn PDF, hãy cho phép cửa sổ bật lên đối với tên miền Pay2S. --- Nguồn trang: https://docs.pay2s.vn/hoa-don-dien-tu/quy-tac-hang-hoa.html # Quy tắc hàng hóa Quy tắc hàng hóa dùng để đổi mã hoặc tên sản phẩm từ website/phần mềm thành tên, mã hàng, đơn vị và thuế suất chuẩn trên hóa đơn. Ví dụ, website gửi `WOO_SKU_VPS-PRO`, Pay2S có thể xuất thành: ```text Tên: Cước dịch vụ máy chủ ảo Mã hàng: VPS Đơn vị: Tháng Thuế suất: 10% ``` ## Mã nguồn thường gặp | Nguồn | Mã sản phẩm | Mã nhóm | |---|---|---| | WHMCS | `WHMCS_PRODUCT_12` | `WHMCS_GROUP_3` | | WooCommerce | `WOO_SKU_VPS-PRO`, `WOO_PRODUCT_80` | `WOO_CATEGORY_12` | | HostBill | `HOSTBILL_PRODUCT_35` | `HOSTBILL_CATEGORY_4` | | API riêng | `API_PRODUCT_CLOUD_SERVER` | `API_GROUP_INFRASTRUCTURE` | - Chọn **Mã sản phẩm** để cấu hình chính xác một sản phẩm. - Chọn **Mã nhóm sản phẩm** để nhiều sản phẩm dùng chung một cách xuất. - Chọn **Tên sản phẩm** khi hệ thống nguồn không có mã ổn định. Tên phải khớp toàn bộ; Pay2S bỏ khoảng trắng thừa và không phân biệt chữ hoa/thường, nhưng vẫn phân biệt dấu tiếng Việt. - Trong cùng phạm vi và nguồn, thứ tự ưu tiên là **Mã sản phẩm → Mã nhóm sản phẩm → Tên sản phẩm**. ## Cách ghép tên - **Chỉ dùng tên cấu hình:** thay hoàn toàn tên nguồn gửi lên. - **Tên cấu hình + tên sản phẩm:** ví dụ `Cước máy chủ ảo PL1`. - **Tên sản phẩm + tên cấu hình:** đặt tên nguồn ở phía trước. Nguồn tích hợp mặc định là `any`. Chỉ chọn một nguồn cụ thể khi cùng mã nhưng cần xử lý khác nhau giữa WHMCS, WooCommerce hoặc hệ thống khác. ## Dữ liệu nên gửi lên Mỗi dòng hàng nên có: ```json { "itemCode": "WOO_SKU_VPS-PRO", "itemGroupCode": "WOO_CATEGORY_12", "sourceProductName": "VPS PL1", "itemName": "VPS PL1", "unit": "Tháng", "quantity": 1, "unitPrice": 100000, "taxRate": 10 } ``` Tên khóa có thể khác theo module, nhưng mã sản phẩm, mã nhóm, tên gốc, số lượng, đơn giá và thuế suất cần được gửi nhất quán. Nếu không có `itemCode`, quy tắc theo tên sẽ dùng `sourceProductName`; khi trường này trống, Pay2S dùng `itemName` để đối chiếu. Với hóa đơn bán hàng áp dụng giảm thuế theo Nghị quyết 204/2025/QH15, mỗi dòng đủ điều kiện có thể gửi thêm: ```json { "vatReductionEligible": true, "directVatRate": 5 } ``` `directVatRate` chỉ nhận `1`, `2`, `3` hoặc `5` và là tỷ lệ tính thuế GTGT trực tiếp trên doanh thu. Nếu không gửi hai trường này, quy tắc hàng hóa trên Pay2S vẫn có thể bổ sung tự động theo mã sản phẩm hoặc mã nhóm đã cấu hình. ## Khi quy tắc thay đổi thuế Số tiền đã thanh toán được xem là tổng cuối cùng. Khi quy tắc đổi thuế suất, Pay2S tự tính lại đơn giá trước thuế để tổng hóa đơn vẫn khớp số tiền khách đã trả. ::: tip Kiểm tra trước khi dùng tự động Hãy thử ít nhất một sản phẩm thường, một sản phẩm giảm giá và một sản phẩm có chu kỳ nhiều tháng trên Sandbox. ::: --- Nguồn trang: https://docs.pay2s.vn/hoa-don-dien-tu/tra-cuu-ma-so-thue.html # Tra cứu mã số thuế và dữ liệu người mua Pay2S hỗ trợ tra cứu thông tin người nộp thuế để giảm sai sót khi nhập tên đơn vị, địa chỉ và trạng thái hoạt động trước khi lập hóa đơn. Để tích hợp từ website/backend, xem [API tra cứu mã số thuế](/hoa-don-dien-tu/api-tra-cuu-ma-so-thue): endpoint GET, header `pay2s-token = Base64(Secret Key)`, ví dụ Node.js/PHP và cấu trúc kết quả. ## Tra cứu thủ công Tại biểu mẫu tạo hóa đơn: 1. Nhập mã số thuế hoặc mã đăng ký kinh doanh vào ô tương ứng. 2. Bấm nút **Tra cứu**. 3. Kiểm tra tên đơn vị, địa chỉ và trạng thái được trả về. 4. Đối chiếu lại thông tin trước khi tạo nháp hoặc phát hành. Kết quả tra cứu chỉ hỗ trợ nhập liệu. Người lập hóa đơn vẫn chịu trách nhiệm kiểm tra thông tin người mua. ## Tự động kiểm tra mã số thuế Khi bật **Tự động kiểm tra mã số thuế**, Pay2S sẽ kiểm tra mã số thuế trong đơn trước khi tự động tạo nháp hoặc phát hành. - Chỉ trạng thái `00` – **NNT đang hoạt động, đã được cấp MST** – được phép tiếp tục luồng tự động. - Nếu trạng thái khác `00`, Pay2S cảnh báo và không tự động tạo hoặc phát hành hóa đơn. - Đơn bị dừng vẫn được giữ trong **Hàng chờ** để người dùng kiểm tra và xử lý. - Nếu đơn không có mã số thuế, Pay2S xử lý theo bộ thông tin người mua đã được gửi lên. ::: warning Không bỏ qua cảnh báo trạng thái Không nên tự phát hành hóa đơn khi người nộp thuế đang có trạng thái khác `00`. Hãy đối chiếu lại với người mua và cơ quan thuế trước khi tiếp tục. ::: ## Pay2S bổ sung dữ liệu như thế nào? Tra cứu thuế chỉ bổ sung thông tin còn thiếu, không tùy tiện ghi đè dữ liệu hợp lệ mà khách hàng đã cung cấp. | Thứ tự | Nguồn dữ liệu | Cách sử dụng | |---:|---|---| | 1 | Thông tin gửi cùng đơn hàng | Ưu tiên tên đơn vị, mã số thuế, địa chỉ và thông tin liên hệ đã gửi | | 2 | Kết quả tra cứu thuế | Bổ sung tên đơn vị, địa chỉ và trạng thái còn thiếu | | 3 | Tên người chuyển khoản | Chỉ dùng làm **Họ tên người mua hàng** khi đã bật tùy chọn tương ứng | | 4 | Dữ liệu mặc định | Chỉ dùng khi đơn không cung cấp dữ liệu phù hợp | Nếu đơn có tên đơn vị, mã số thuế và địa chỉ, việc bật **Dùng tên người thanh toán làm người mua** không làm mất thông tin doanh nghiệp. Tên người thanh toán chỉ được điền vào trường **Họ tên người mua hàng**. ## Cá nhân và hộ kinh doanh Với mã định danh của cá nhân hoặc hộ kinh doanh, Pay2S dựa trên tên do dịch vụ tra cứu trả về để hỗ trợ phân loại: - Nếu tên thể hiện hộ kinh doanh, tên đó được dùng cho **Tên đơn vị mua hàng**; mã định danh được đưa vào trường phù hợp của hóa đơn. - Nếu kết quả là tên cá nhân, tên được dùng cho **Họ tên người mua hàng** và mã định danh được dùng cho người mua. Việc phân loại tự động chỉ mang tính hỗ trợ. Người lập hóa đơn cần kiểm tra lại loại người mua, tên và địa chỉ trước khi phát hành. ## Khi nào dùng “Bán cho người tiêu dùng”? Pay2S chỉ sử dụng thông tin định danh người mua khi có bộ dữ liệu phù hợp: - **Cá nhân:** họ tên và địa chỉ. - **Doanh nghiệp hoặc tổ chức:** tên đơn vị, mã số thuế và địa chỉ. Nếu không đủ thông tin, hoặc người mua chọn không lấy hóa đơn, Pay2S sử dụng **Bán cho người tiêu dùng** để tránh phát hành thông tin không đầy đủ. ## Dữ liệu tra cứu không được lưu cache Pay2S thực hiện tra cứu mới khi người dùng hoặc luồng tự động yêu cầu. Kết quả tra cứu mã số thuế không được lưu cache để dùng lại cho lần phát hành sau. ::: danger Lưu ý về độ chính xác dữ liệu Dữ liệu tra cứu trên Pay2S chỉ mang tính tham khảo. Trước khi phát hành hóa đơn, hãy kiểm tra thông tin chính thức tại [Cổng tra cứu thông tin người nộp thuế của Tổng cục Thuế](https://tracuunnt.gdt.gov.vn/tcnnt/mstdn.jsp). Pay2S không chịu trách nhiệm đối với sai sót hoặc thiệt hại phát sinh nếu người dùng không kiểm tra lại dữ liệu với nguồn chính thức trước khi phát hành. ::: --- Nguồn trang: https://docs.pay2s.vn/hoa-don-dien-tu/tu-dong-hoa.html # Tự động hóa hóa đơn ## Tự động tạo hóa đơn nháp Khi bật, Pay2S tự tạo bản nháp cho đơn đáp ứng đủ điều kiện. Đây là chế độ nên dùng đầu tiên để kế toán kiểm tra dữ liệu trước khi phát hành. ## Tự động phát hành sau khi tạo nháp Khi bật, Pay2S phát hành ngay sau khi tạo nháp thành công. ::: danger Cẩn trọng với Production Hóa đơn thật có thể được ký và cấp số mà không cần xác nhận thủ công. Chỉ bật sau khi đã theo dõi chế độ tự tạo nháp ổn định. ::: ## Dùng tên người thanh toán làm người mua Khi bật, Pay2S ưu tiên tên người chuyển khoản làm họ tên người mua. Tên đơn vị, mã số thuế và địa chỉ vẫn lấy từ dữ liệu yêu cầu hóa đơn. Pay2S có thể chuẩn hóa một số tiền tố kỹ thuật trong nội dung ngân hàng hoặc tra cứu tên chủ tài khoản khi ngân hàng không gửi tên người chuyển khoản đầy đủ. Kết quả này chỉ được dùng cho trường **Họ tên người mua hàng**. ## Tự động kiểm tra mã số thuế Khi đơn có mã số thuế và tùy chọn này đang bật, Pay2S kiểm tra trạng thái người nộp thuế trước khi tự tạo nháp hoặc phát hành. - Chỉ trạng thái `00` – **NNT đang hoạt động, đã được cấp MST** – được tiếp tục tự động. - Trạng thái khác `00` sẽ dừng xử lý và giữ đơn trong **Hàng chờ**. - Kết quả tra cứu chỉ bổ sung dữ liệu còn thiếu; không ghi đè tên đơn vị, mã số thuế hoặc địa chỉ hợp lệ đã gửi cùng đơn. - Kết quả không được lưu cache để sử dụng lại cho lần sau. Xem đầy đủ tại [Tra cứu mã số thuế và dữ liệu người mua](./tra-cuu-ma-so-thue.md). ## Đối chiếu thanh toán trước khi phát hành Khi bật, Pay2S kiểm tra lại giao dịch ngân hàng ngay trước mỗi lần phát hành hóa đơn từ đơn hàng. Hệ thống dùng đúng mã giao dịch đã liên kết với đơn, đồng thời kiểm tra tài khoản nhận tiền và số tiền; không dò giao dịch chỉ bằng số tiền. - Khớp đầy đủ: tiếp tục phát hành. Số tiền phải khớp tuyệt đối; lệch 1 đồng cũng được giữ lại để kiểm tra. - Không tìm thấy giao dịch, sai tài khoản hoặc lệch tiền: giữ hóa đơn lại và không gửi sang nhà cung cấp. - Dữ liệu ngân hàng tạm thời chưa có: giữ trong hàng chờ để lần chạy sau kiểm tra lại, không tự kết luận khách chưa thanh toán. - Hóa đơn tạo thủ công, không gắn với đơn hàng Pay2S, không áp dụng bước kiểm tra này. Kết quả và thời điểm kiểm tra gần nhất được hiển thị trong **Hàng chờ** để người dùng biết lý do hóa đơn chưa được phát hành. ## Thứ tự ưu tiên dữ liệu người mua 1. Thông tin người mua được gửi cùng đơn hàng. 2. Kết quả tra cứu mã số thuế để bổ sung phần còn thiếu. 3. Tên người chuyển khoản làm **Họ tên người mua hàng** nếu đã bật tùy chọn. 4. **Bán cho người tiêu dùng** nếu không có bộ thông tin người mua hợp lệ. Việc dùng tên người chuyển khoản không xóa tên đơn vị, mã số thuế hoặc địa chỉ của doanh nghiệp. ## Hàng hóa mặc định Chỉ áp dụng khi đơn không gửi danh sách hàng hóa. Có thể đặt tên hàng, đơn vị tính và thuế suất mặc định. Dữ liệu hàng hóa chi tiết do website gửi lên luôn được ưu tiên hơn hàng hóa mặc định. ## Điều kiện để đơn được tự xử lý - Đơn đã thanh toán thành công. - Đơn có yêu cầu xuất hóa đơn. - Đơn phát sinh sau thời điểm bật tự động hóa. - Kết nối đang bật và đã kiểm tra thành công. - Có mẫu mặc định hoặc cửa hàng đã được gán mẫu. Nếu tài khoản chỉ có một kết nối đang hoạt động và đã kiểm tra hợp lệ, Pay2S tự dùng kết nối đó cho đơn không gắn cửa hàng; khi có nhiều kết nối, bạn cần chọn một kết nối mặc định. - Có hàng hóa hợp lệ hoặc đã bật hàng hóa mặc định. - Tổng hàng hóa và thuế khớp số tiền đã thanh toán. - Nếu bật đối chiếu thanh toán trước phát hành, mã giao dịch, tài khoản nhận và số tiền ngân hàng phải khớp đơn hàng. - Nếu đơn có mã số thuế và bật kiểm tra tự động, trạng thái người nộp thuế phải là `00`. Đơn không đủ điều kiện vẫn nằm trong **Hàng chờ** để kiểm tra hoặc lập thủ công. ## Trình tự vận hành an toàn 1. Kiểm tra trên Sandbox. 2. Bật tự động tạo nháp, chưa bật tự phát hành. 3. Theo dõi **Hàng chờ**, **Nhật ký** và PDF trong vài ngày. 4. Sửa quy tắc hàng hóa nếu cần. 5. Chỉ bật tự phát hành sau khi người phụ trách kế toán xác nhận.