You will need:
- client_id and client_secret from your SePay eInvoice account
- Use the Sandbox environment for testing:
https://einvoice-api-sandbox.sepay.vn - All API calls must be made from server-side — do not call directly from a client/browser
Step 1: Get an Access Token
Every eInvoice API request requires a Bearer token for authentication. Call the /v1/token endpoint using Basic Authentication to receive an access_token.
https://einvoice-api.sepay.vn/v1/tokenNEVER call this API from a browser or mobile app. Your client_secret must remain strictly confidential on your server.
curl --request POST \--url https://einvoice-api.sepay.vn/v1/token \--header 'Authorization: Basic REPLACE_BASIC_AUTH'
{
"success": true,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400
}
}Tokens are valid for 86400 seconds (24 hours). Cache and reuse the token rather than fetching a new one on every request. When you receive a 401 error, refresh the token automatically.
Step 2: List Provider Accounts
Before creating an invoice you need a provider_account_id — the ID of the e-invoice provider account configured in your system. Call /v1/provider-accounts to retrieve the list.
https://einvoice-api.sepay.vn/v1/provider-accountscurl --request GET \--url 'https://einvoice-api.sepay.vn/v1/provider-accounts?page=1&per_page=20' \--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{
"data": {
"paging": {
"per_page": 20,
"total": 1,
"has_more": false,
"current_page": 1,
"page_count": 1
},
"items": [
{
"id": "0aea3134-da40-11f0-aef4-52c7e9b4f41b",
"provider": "matbao",
"active": true,
"tax_authority_approved_date": "2026-04-20"
}
]
}
}Only use accounts with active: true. If you have multiple accounts from different providers, call the Provider Account Detail API to inspect the allowed invoice templates and series for each account.
Step 3: Create and Issue the Invoice
Call /v1/invoices/create with is_draft: false to create and issue the invoice directly (without a draft step). The API processes this asynchronously and returns a tracking_code to check the result in the next step.
https://einvoice-api.sepay.vn/v1/invoices/createInvoice template code (from account details API)
Invoice series (from account details API)
Issue date (YYYY-MM-DD HH:mm:ss)
Currency:
- VND: Vietnamese Dong
- USD: United States Dollar
- CAD: Canadian Dollar
VNDProvider account ID (UUID)
Payment method:
- TM: Cash
- CK: Bank transfer
- TM/CK: Cash and bank transfer
- KHAC: Other
true: Create as draft (requires issuing later, does not count towards quota)false: Create and issue immediately
falseList of goods/services
Internal notes
curl --request POST \--url https://einvoice-api.sepay.vn/v1/invoices/create \--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \--header 'content-type: application/json' \--data '{"template_code":"1","invoice_series":"C26TSE","issued_date":"2026-01-26 00:00:00","currency":"VND","provider_account_id":"0aea3134-da40-11f0-aef4-52c7e9b4f41b","payment_method":"TM","is_draft":false,"buyer":{"type":"personal","name":"Công ty TNHH ABC","legal_name":"CÔNG TY CỔ PHẦN ABC","tax_code":"0123456789","address":"123 Đường ABC, Quận 1, TP.HCM","email":"contact@abc.com","phone":"0901234567","buyer_code":"KH-001","national_id":"001234567890"},"items":[{"line_number":1,"line_type":1,"item_code":"SP001","item_name":"Sản phẩm A","unit":"cái","quantity":10,"unit_price":100000,"tax_rate":10,"discount_tax":10,"discount_amount":100000,"before_discount_and_tax_amount":4500000}],"notes":"Ghi chú nội bộ"}'
{
"success": true,
"data": {
"tracking_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
"tracking_url": "https://einvoice-api.sepay.vn/v1/invoices/create/check/084e179d-d95a-11f0-aef4-52c7e9b4f41b",
"message": "Đã tạo yêu cầu xuất bán hóa đơn điện tử"
}
}The API returns a tracking_code immediately, but the invoice has not yet been issued at this point. You must complete Step 4 to confirm the issuance result.
Step 4: Check the Invoice Creation Status
Call /v1/invoices/create/check/{tracking_code} to check the result of the invoice creation. When is_draft: false, the create step includes digital signing and submission to the tax authority — this endpoint confirms the full outcome. Poll every 2–3 seconds, up to 10 times.
https://einvoice-api.sepay.vn/v1/invoices/create/check/{tracking_code}curl --request GET \--url https://einvoice-api.sepay.vn/v1/invoices/create/check/084e179d-d95a-11f0-aef4-52c7e9b4f41b \--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{
"success": true,
"data": {
"reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
"status": "Success",
"message": "Xuất hóa đơn điện tử thành công",
"invoice": {
"reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
"invoice_number": "0",
"issued_date": "2025-12-15",
"pdf_url": "https://beta-portalv2.mifi.vn/DownloadPDFCA.aspx?kk=1434747710&keyinv=...",
"xml_url": null,
"status": "draft",
"buyer": {
"name": "Công ty ABC",
"tax_code": "0101234567",
"address": "123 Đường A, Quận B, Hà Nội",
"email": "buyer@example.com",
"phone": "0900000000"
},
"total_before_tax": 200000,
"tax_amount": 20000,
"total_amount": 220000,
"notes": "Ghi chú hóa đơn",
"source": "api"
}
}
}If status returns "Failed", inspect the message field for the specific reason (invalid buyer details, unrecognised invoice series, quota exhausted, etc.). Correct the data and call the Create Invoice API again to issue a new invoice.
Next Steps
After successfully issuing your first invoice:
- Authenticate with Bearer Token — Details on authentication and token management
- List Provider Accounts — Browse and select e-invoice provider accounts
- Provider Account Detail — Retrieve allowed invoice templates and series
- Create E-Invoice — Full parameter reference for invoice creation
- Invoice Status Tracking — Details on polling the status endpoint
- Issue a Draft Invoice — Draft-then-issue workflow
- Invoice Detail — Retrieve full invoice information after issuance
- Download Invoice — Download the PDF or XML file for an invoice
- Check Usage Quota — Monitor remaining issuance quota