Sepay eInvoice API Overview

Introduction

• eInvoice API lets you create, issue, and query e-invoices over HTTP.
• Supports two environments: Sandbox for testing and Production for live use.

Environment & Base URL

Production: https://einvoice-api.sepay.vn
Sandbox: https://einvoice-api-sandbox.sepay.vn

Authentication

Header: Authorization: Bearer <ACCESS_TOKEN>
Get token: POST /v1/token

Overview Flow

• eInvoice Processing Flow Description:

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

1. Obtain access token
   The merchant application calls POST v1/token to obtain an access_token that is reused for all eInvoice APIs.

2. List provider accounts
   Call GET v1/provider-accounts to retrieve configured eInvoice provider accounts and their statuses.

3. Get provider account detail
   Use GET v1/provider-accounts/{id} to inspect a specific account configuration (allowed templates/series, status, etc.).

4. Create invoice
   Submit invoice data via POST v1/invoices/create. The API returns a tracking_code for the creation job.

5. Check invoice creation status
   Poll GET v1/invoices/create/check/{tracking_code} to confirm whether creation succeeded or failed.

6. Issue invoice
   Once creation succeeds, trigger issuance via POST v1/invoices/issue. Another tracking_code is returned for this stage.

7. Check invoice issuance status
   Poll GET v1/invoices/issue/check/{tracking_code} to see the issuance result.

8. Get invoice details
   After issuance completes, call GET v1/invoices/{reference_code} to fetch full invoice information plus file URLs (PDF, XML, etc.).

9. Check usage quota
   Call GET v1/usage to monitor remaining issuance quota and plan future operations.

10. List invoices
    Use GET v1/invoices to retrieve paginated invoice lists for monitoring and reconciliation.

Core Endpoints

Common Response Structure

{
  "success": true,
  "data": "object"
}

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error message"
  }
}