SePay eInvoice API overview

Introduction

SePay eInvoice API is the integration layer between your system and Vietnam's tax authority (CQT), allowing you to create and issue e-invoices compliant with Decree 123/2020/ND-CP and Circular 78/2021/TT-BTC. Instead of integrating separately with each e-invoice provider, you integrate once with SePay and issue invoices through any configured provider.

The API covers the complete invoice lifecycle: from draft creation, issuance to CQT, real-time status tracking, file download (PDF/XML), and usage quota management — all via a standard RESTful HTTP interface.

View demo invoice

Who is this for?

eInvoice API is designed for organizations and developers who need to automate the e-invoice issuance process:

SaaS & ERP Platforms

Embed e-invoice issuance directly into your sales, accounting, or order management workflows.

High-volume Invoice Issuers

Fully automate batch invoice creation and issuance, reducing manual work and errors at scale.

Accounting Software

Connect directly to CQT to issue and sync invoice status, supporting reconciliation and compliant storage.

E-commerce Platforms

Automatically issue an invoice for each completed order to meet per-transaction invoice requirements.

Developers Building Solutions

Add e-invoice functionality for enterprise clients without negotiating directly with each provider.

Key Features

Create E-Invoices

Create draft or live invoices via POST v1/invoices/create, supporting multiple invoice templates and series.

Issue to Tax Authority

Submit invoices to CQT through your configured e-invoice provider using POST v1/invoices/issue.

Async Status Tracking

Poll create/issue results in real time via /check/{tracking_code} before proceeding to the next step.

Retrieve & Download Invoices

Fetch issued invoice details including CQT-compliant PDF and XML file URLs.

Usage Quota Monitoring

Track remaining issuance quota via GET v1/usage to plan your service usage.

Provider Account Management

List and inspect configured e-invoice provider accounts including templates, series, and status.

Processing Flow

eInvoice Processing Flow

Rendering diagram...

The eInvoice flow covers every step from authentication and account checks to invoice creation, issuance, and retrieval:

Obtain access token — Call POST v1/token to receive an access_token used for all subsequent API calls.
List provider accounts — Call GET v1/provider-accounts to view available e-invoice provider accounts and their statuses.
Get provider account detail — Call GET v1/provider-accounts/{id} for the specific configuration: allowed templates, series, and activity status.
Create invoice — Submit invoice data via POST v1/invoices/create. The API returns a tracking_code to track the creation job.
Check creation status — Poll GET v1/invoices/create/check/{tracking_code} to confirm whether creation succeeded or failed.
Issue invoice — Trigger issuance via POST v1/invoices/issue. A new tracking_code is returned for this stage.
Check issuance status — Poll GET v1/invoices/issue/check/{tracking_code} to confirm the result of submission to CQT.
Retrieve invoice details — Once issuance completes, call GET v1/invoices/{reference_code} to fetch full invoice data plus PDF and XML file URLs.
Check usage quota — Call GET v1/usage to monitor remaining issuance quota.
List invoices — Call GET v1/invoices to retrieve a paginated invoice list for monitoring and reconciliation.

Asynchronous Processing

The Create and Issue steps are processed asynchronously. After calling each step, you must poll the corresponding /check API to confirm the status before proceeding to the next step.

Environments

Environment	Base URL
Production	`https://einvoice-api.sepay.vn`
Sandbox	`https://einvoice-api-sandbox.sepay.vn`

Authenticate using a Bearer token in the request header: Authorization: Bearer <ACCESS_TOKEN>

Tip

If you are just getting started, use the Sandbox environment for testing before switching to Production.

Next Steps

To start using the eInvoice API, follow these steps in order:

Authenticate with Bearer Token — Get a Bearer token to authenticate subsequent API calls
List E-Invoice Providers — View available e-invoice provider accounts
Issue an E-Invoice — Start creating your first invoice