Create Electronic Invoice API

Create and sign an electronic invoice via SePay eInvoice API. Submits invoice data to the Vietnamese tax authority and returns a tracking code to monitor.

||
View demo invoice

API Endpoint

POST
https://einvoice-api.sepay.vn/v1/invoices/create

API Request

template_codestringrequired

Invoice template code (from account details API)

invoice_seriesstringrequired

Invoice series, taken from the account details API (do not hardcode it; the C{YY} part must match the current year, e.g. C26 in 2026, and a wrong year is rejected).

issued_datestringrequired

Invoice issue date (YYYY-MM-DD HH:mm:ss). Only the current date is supported as the issue date.

currencyenumrequired

Currency:

  • VND: Vietnamese Dong
  • USD: United States Dollar
  • CAD: Canadian Dollar
Default: VND
provider_account_idstringrequired

Provider account ID (UUID)

seller_store_xidstring

Pass the xid of a seller business location (from the business locations list API) to attach the location to the invoice - its code and name are passed to the invoice. Leave it out if the invoice does not need a location.

If the location does not exist or does not belong to your account, the API returns 400 SELLER_STORE_NOT_FOUND. If the location is deactivated (is_active=false), the API returns 400 SELLER_STORE_INACTIVE. In these cases the invoice is not sent to the tax authority.

reference_codestring

Invoice reference code, must be unique within your account. Auto-generated as UUID if omitted.

payment_methodenum

Payment method:

  • TM: Cash
  • CK: Bank transfer
  • TM/CK: Cash and bank transfer
  • KHAC: Other
is_draftboolean
  • true: Create as draft (requires issuing later, does not count towards quota)
  • false: Create and issue immediately
Default: false
buyerobjectrequired
itemsarray<object>required

List of goods/services

notesstring

Internal notes

total_amountinteger

Final total payable amount of the invoice (tax included). Optional. If provided, it must be an integer (no decimals).

  • Omitted: the system computes it from the line items (post-discount subtotal + tax) and rounds to a whole number.
  • Provided: compute and round it to a whole number yourself; the system uses your value exactly as-is and performs NO validation against the line items. Sending a value with decimals (e.g. 100000.5) is rejected with a 400 error.

Warning (when provided): You are solely responsible for this value. If it does not match the goods subtotal + tax, the invoice will display an incorrect total and the tax authority may reject it.

Attaching a seller business location (seller_store_xid)

Pass seller_store_xid with the location's xid (from the Seller Business Locations API) to attach a business location to the invoice - its code and name are passed to the invoice. The location must belong to your account and must be active - otherwise the API returns 400 SELLER_STORE_NOT_FOUND or 400 SELLER_STORE_INACTIVE.

API Response

Success Response (200)
{
  "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ử"
  }
}
successboolean
dataobject

Error Handling

When the API returns any of the errors below, the invoice is not created and is not sent to the tax authority.

400Bad Request

Missing or invalid required fields.

401Unauthorized

Missing or invalid Bearer token.

400ISSUED_DATE_INVALID

issued_date is in the future (later than today).

400VALIDATION_ERROR

invoice_series has the wrong year: it must be C{YY} of the current year (e.g. C26 for 2026).

400SELLER_STORE_NOT_FOUND

seller_store_xid does not exist or does not belong to your account.

400SELLER_STORE_INACTIVE

The business location is deactivated (is_active=false) and cannot be used for new invoices.

422INVOICE_DATE_BEFORE_TAX_APPROVAL

Invoice date is before the tax authority approval date (production only).

422REGISTRATION_NOT_TAX_APPROVED

Business has not registered eInvoicing or the tax authority has not approved the filing.

500QUOTA_HAS_BEEN_USERD_UP

The plan's invoice quota is used up. Top up the quota before calling again - do not auto-retry, this error does not clear by itself.

409EINVOICE_DOCUMENT_EXISTED

An invoice already exists for this reference_code. reference_code must be unique.

500REGISTRATION_NOT_COMPLETE

The company has not completed eInvoice package registration.

500Internal Server Error

System error while signing/submitting.

Tax Rate Information

  • tax_rate is only required when issuing VAT invoices for companies (not required for sales invoices).
  • The tax_rate field inside items accepts the following values:
    • -2 (Non-taxable)
    • -1 (Not declared / not subject to VAT calculation)
    • 0 (0% VAT rate)
    • 5 (5% VAT rate)
    • 8 (8% VAT rate)
    • 10 (10% VAT rate)
  • Sales invoices (template_code = 2): the system automatically ignores any tax_rate and tax_amount you send.

Decimal Quantity

  • quantity accepts decimal values (up to 2 decimal places).
  • Suitable for hourly services (Giờ/Hour), weight/measurement units (Kg, m, Lít), or fractional portions (Phần).
  • Examples: 1.5, 2.75, 0.25.

Usage Notes

  • To officially issue the invoice, send is_draft=false. To save as a draft for preview only, send is_draft=true (draft invoices will not count toward your eInvoice quota).
  • provider_account_id is provided from the eInvoice account list API
  • After successfully submitting the invoice request, use the endpoint provided in tracking_url to call the invoice status tracking API
  • invoice_series must match the current year, format C{YY} (use C26 in 2026, C27 in 2027). Don't hardcode it, fetch the valid symbol from the account detail API; a wrong year is rejected (400).
  • issued_date must fall between the tax authority approval date and today: it cannot be in the future (ISSUED_DATE_INVALID), and in production it cannot be before the approval date (INVOICE_DATE_BEFORE_TAX_APPROVAL). Test mode skips the approval check.
  • Always poll the status tracking API until a terminal result (success or failure) before ending your job, don't fire-and-forget so failed invoices aren't dropped.

Adding Notes to the Invoice Template

  • If you want to display a note on the invoice, add an item with line_type:4 to the items (array) using the format below:
{
  "line_number": 3,
  "line_type": 4,
  "item_name": "Free promotional goods (This is your note)"
}

How Promotions Affect the Invoice Total

  • When sending a promotion line with line_type = 2, the default value is 0 and it is not included in the invoice total.
  • If you want promotional items to be included in the total amount, you must provide a unit_price or other price-related fields (similar to line_type = 1) greater than 0.

Invoice Total (total_amount)

total_amount is optional. If provided, it must be an integer (no decimals). It is the final payable total of the invoice, tax included.

Case 1: Omitted (default)

The system computes total_amount from the line items (post-discount subtotal + tax) and rounds to a whole number.

Case 2: Provided

You compute and round it to a whole number yourself before sending. The system uses your value exactly as-is and performs NO validation against the computed line-item total. Sending a value with decimals (e.g. 100000.5) is rejected with a 400 error.

Warning for Case 2 (providing total_amount yourself)

You are fully responsible for the value you provide. If it is wrong (does not match goods subtotal + tax), the issued invoice will show an incorrect total and the tax authority may reject it. Compute and round it carefully before sending.

Line Tax Amount (items[].tax_amount)

tax_amount on each line is optional. If provided, it must be an integer (no decimals). It is the line's tax amount.

Case 1: Omitted (default)

The system computes the line tax from the pre-tax line amount and the tax rate (tax_rate) and rounds to a whole number.

Case 2: Provided

You compute and round it yourself to a whole number before sending. The system uses exactly the value you send, never recomputing or reconciling it against tax_rate. Sending a value with decimals (e.g. 90000.5) is rejected with a 400 error.

Warning for Case 2 (providing tax_amount yourself)

You are fully responsible for the value you send. If it is wrong (far off from the line amount times the tax rate), the issued invoice will show a wrong tax amount and the tax authority may reject it. Compute it carefully before sending.

Sample Code

>
>
>
>
>
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","seller_store_xid":"8f14e45f-ceea-4b6d-9c1a-2b3c4d5e6f70","reference_code":"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,"tax_amount":900000,"discount_tax":10,"discount_amount":100000,"before_discount_and_tax_amount":4500000}],"notes":"Ghi chú nội bộ","total_amount":4950000}'

Sample Parameters for Different Invoice Types

Sales Invoice Sample

json
{
  "template_code": "2",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "name": "ABC Company",
      "tax_code": "0101234567",
      "address": "123 Street A, District B, Hanoi",
      "email": "buyer@example.com",
      "phone": "0900000000",
      "buyer_code": "KH-001",
      "national_id": "001234567890"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Product A",
          "unit": "pcs",
          "quantity": 1,
          "unit_price": 4500000
      }
  ],
  "notes": "Invoice note",
  "is_draft": true
}

Sales Invoice with Order-Level Discount

json
{
  "template_code": "2",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "tax_code": "0317887567",
      "address": "88 Anh Sao Street, Binh An Ward, District 9, Ho Chi Minh City, Vietnam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Product A",
          "unit": "pcs",
          "quantity": 1,
          "unit_price": 4500000
      },
      {
          "line_number": 2,
          "line_type": 3,
          "item_name": "Trade discount",
          "before_discount_and_tax_amount": 4500000
      }
  ],
  "notes": "Invoice note",
  "is_draft": false
}

Sales Invoice with Item Discount (Percentage - discount_tax)

json
{
  "template_code": "2",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "tax_code": "0317887567",
      "address": "88 Anh Sao Street, Binh An Ward, District 9, Ho Chi Minh City, Vietnam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Product A",
          "unit": "pcs",
          "quantity": 1,
          "unit_price": 4500000,
          "discount_tax": 2
      }
  ],
  "notes": "Invoice note",
  "is_draft": false
}

Sales Invoice with Item Discount (Fixed Amount - discount_amount)

json
{
  "template_code": "2",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "tax_code": "0317887567",
      "address": "88 Anh Sao Street, Binh An Ward, District 9, Ho Chi Minh City, Vietnam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Product A",
          "unit": "pcs",
          "quantity": 1,
          "unit_price": 4500000,
          "discount_amount": 100000
      }
  ],
  "notes": "Invoice note",
  "is_draft": false
}

Sales Invoice with Promotion

json
{
  "template_code": "2",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "name": "ABC Company",
      "tax_code": "0101234567",
      "address": "123 Street A, District B, Hanoi",
      "email": "buyer@example.com",
      "phone": "0900000000"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Product A",
          "unit": "pcs",
          "quantity": 1,
          "unit_price": 4500000
      },
      {
          "line_number": 2,
          "line_type": 2,
          "item_code": "KM001",
          "item_name": "Promotional Item",
          "unit": "pcs",
          "quantity": 1,
          "unit_price": 0
      }
  ],
  "notes": "Invoice note",
  "is_draft": true
}

VAT Invoice Sample

json
{
  "template_code": "1",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "tax_code": "0317887567",
      "address": "88 Anh Sao Street, Binh An Ward, District 9, Ho Chi Minh City, Vietnam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Product A",
          "unit": "pcs",
          "quantity": 1,
          "unit_price": 4500000,
          "tax_rate": 10
      }
  ],
  "notes": "Invoice note",
  "payment_method": "CK",
  "is_draft": false
}

VAT Invoice with Order-Level Discount

json
{
  "template_code": "1",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "tax_code": "0317887567",
      "address": "88 Anh Sao Street, Binh An Ward, District 9, Ho Chi Minh City, Vietnam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Product A",
          "unit": "pcs",
          "quantity": 1,
          "unit_price": 4500000,
          "tax_rate": 10
      },
      {
          "line_number": 2,
          "line_type": 3,
          "item_name": "Trade discount",
          "tax_rate": 10,
          "before_discount_and_tax_amount": 100000
      }
  ],
  "notes": "Invoice note",
  "payment_method": "TM/CK",
  "is_draft": false
}

VAT Invoice with Item Discount (Percentage - discount_tax)

json
{
  "template_code": "1",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "tax_code": "0317887567",
      "address": "88 Anh Sao Street, Binh An Ward, District 9, Ho Chi Minh City, Vietnam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Product A",
          "unit": "pcs",
          "quantity": 1,
          "unit_price": 4500000,
          "tax_rate": 10,
          "discount_tax": 10
      }
  ],
  "notes": "Invoice note",
  "payment_method": "CK",
  "is_draft": false
}

VAT Invoice with Item Discount (Fixed Amount - discount_amount)

json
{
  "template_code": "1",
  "invoice_series": "C26TSE",
  "issued_date": "2026-01-26 00:00:00",
  "currency": "VND",
  "provider_account_id": "{{your-provider-account-id}}",
  "buyer": {
      "type": "personal",
      "name": "Buyer Name Demo",
      "tax_code": "0317887567",
      "address": "88 Anh Sao Street, Binh An Ward, District 9, Ho Chi Minh City, Vietnam",
      "email": "buyeremaildemo@gmail.com"
  },
  "items": [
      {
          "line_number": 1,
          "line_type": 1,
          "item_code": "SP001",
          "item_name": "Product A",
          "unit": "pcs",
          "quantity": 1,
          "unit_price": 4500000,
          "tax_rate": 10,
          "discount_amount": 100000
      }
  ],
  "notes": "Invoice note",
  "payment_method": "KHAC",
  "is_draft": false
}

Next Steps

After successfully submitting the invoice creation request and receiving a tracking_code:

  1. Track Invoice Creation Status - Use the tracking_code to check the processing result (required)
After confirming successful status
Previous page
—
Next page
—