Create a Receipt - BeaconX e-Invoice API

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Header Params

string

optional

Example:

application/json

Body Params application/json

buyer

object

required

Buyer Object

tin

string

required

Tax Identification Number (TIN)

name

string

required

Full Name as per IC

string

required

Email Address

address1

string

required

Address Line 1

address2

string

required

Address Line 2

address3

string

required

Address Line 3

city

string

required

City

postcode

string

required

Postcode

state

string

required

State

country

string

required

Country

contact

string

required

Phone Number

id_number

string

required

NRIC, Passport or BRN value

id_type

string

required

Accepts only "NRIC", "PASSPORT", "ARMY" or "BRN"

sst_number

string

required

SST Number if applicable

membership_id

string

required

Membership No for record purposes

reference_number

string

required

System Unique ID. Used for iServe searching. It is advisable to make this field unique and obscured from being easily guessed.

invoice_number

string

required

For POS, use running receipt number

original_einvoice_ref_number

string

optional

Used for Refunds. If this field is provided, system will search for original receipt's reference_number and set the original receipt status to "reversed". The current receipt's status will be set as "refund"

outlet_code

string

required

Outlet / Branch code to link receipt to outlet.

dept_code

string

optional

[Optional] Additional field to link receipt to department

pos_id

string

required

POS Terminal No / ID

source

string

required

Source system label for internal reference. Leave as empty string if not applicable.

issued_at

string

required

Date/Time of transaction

status

string

required

"valid" to allow Buyer to claim the e-Invoice. "pending" or "voided" values will prevent Buyer from claiming the e-Invoice

subtotal

number

required

Sum of all amount before discount

discount_rate

number

required

Discount rate % where applicable

discount_amount

number

required

Discount amount where applicable

service_fee_rate

number

required

Additional Fees rate % where applicable

service_fee_amount

number

required

Additional Fees where applicable

total_excl_tax

number

required

= subtotal - discount_amount + fee_amount + charge+amount

sales_tax_amount

number

required

Sum of line items Sales Tax type

service_tax_amount

number

required

Sum of line items Service Tax type

gst_amount

number

required

Sum of line items GST type

ttx_amount

number

required

Sum of line items Tourism Tax type

hvgt_amount

number

required

Sum of line items High Value Goods Tax type

lvst_amount

number

required

Sum of line items Low Value Sales Tax type

total_tax_amount

number

required

Sum of all tax types amounts

total_incl_tax

number

required

total_excl_tax + total_tax_amount

rounding

number

required

Rounding Adjustment of total_incl_tax

e.g. to nearest RM0.05

total_payable_amount

number

required

= total_incl_tax + rounding

currency_code

string

required

Defaults to "MYR"

currency_rate

number

required

Defaults to "1.0"

footer_notes

string

optional

Footer notes to be included into PDF printout of invoices

suppliers_bank_account_number

string

optional

[Optional]
Supplier's Bank Account Number that facilitates payment, where applicable.

payment_mode

string

optional

[Optional]
Applicable for retail purchases.

01 Cash
02 Cheque
03 Bank Transfer
04 Credit Card
05 Debit Card
06 e-Wallet / Digital Wallet
07 Digital Bank
08 Others

payment_terms

string

optional

[Optional]
An agreed-upon payment terms and conditions. e.g. "Cash Upfront"

prepayment_amount

number

optional

[Optional]
Amount paid upfront. Used for Cash Vouchers, Deposits, other amounts paid upfront.

prepayment_datetime

string

optional

[Optional]
Date/Time of amount paid upfront. Use YYYY-MM-DD HH:ii::ss or YYYY-MM-DD format.

prepayment_reference_number

string

optional

[Optional]
Transaction reference number of prepayment. e.g. Voucher Serial Number, etc

items

array [object {27}]

required

Minimum of 1 item

string

required

Line item ID, may be a sequence of running number if not available

code

string

required

Material / SKU code to be used for mapping of certain data.

If not used, please leave it as "" (blank string)

classification

string

required

Classification code of item

unit_price

number

required

Unit Price

quantity

number

required

Quantity, minimum is 1

description

string

required

Product / Service description text (limited to 300 characters)

long_description

string

required

Product / Service description text (no limit on characters, to be used for full detailed invoice print out). Optional.

measurement

string

required

Unit of measure. e.g. "KGM" or "H87" or "C62"

Refer https://sdk.myinvois.hasil.gov.my/codes/unit-types/

subtotal

number

required

= unit_price x quantity

discount_rate

number

required

Discount % where applicable

discount_amount

number

required

Discount amount where applicable

service_fee_rate

number

required

Additional Fees % where applicable

service_fee_amount

number

required

Additional Fee amount where applicable

total_excl_tax

number

required

= subtotal - discount_amount + fee_amount + charge_amount

sales_tax_rate

number

required

Sales tax %

sales_tax_amount

number

required

Sales tax amount

service_tax_rate

number

required

Service tax %

service_tax_amount

number

required

Service tax amount

gst_rate

number

required

GST %

gst_amount

number

required

GST amount

ttx_rate

number

required

Tourism tax %

ttx_amount

number

required

Tourism tax amount

hvgt_rate

number

required

High Value Goods Tax %

hvgt_amount

number

required

High Value Goods Tax amount

lvst_rate

number

required

Low Value Sales Tax %

lvst_amount

number

required

Low Value Sales Tax amount

total_incl_tax

number

required

= total_excl_tax + total_tax_amount

Example

{
  "reference_number": "OUTLET-POSID-1131",
  "invoice_number": "OUTLET-POSID-1131",
  "original_einvoice_ref_number": "",
  "pos_id": "",
  "source": "",
  "issued_at": "2024-10-16",
  "outlet_code": "SMG",
  "status": "valid",
  "quantity": 0,
  "subtotal": 117.3,
  "discount_rate": 0,
  "discount_amount": 14.49,
  "service_fee_rate": 0,
  "service_fee_amount": 0,
  "total_excl_tax": 0,
  "sales_tax_amount": 0,
  "service_tax_amount": 0,
  "gst_amount": 0,
  "ttx_amount": 0,
  "hvgt_amount": 0,
  "lvst_amount": 0,
  "total_tax_amount": 0,
  "total_incl_tax": 102.81,
  "rounding": -0.01,
  "currency_code": "MYR",
  "currency_rate": 1,
  "total_payable_amount": 102.8,
  "suppliers_bank_account_number": "",
  "payment_method": "",
  "payment_terms": "",
  "prepayment_amount": "",
  "prepayment_datetime": "",
  "prepayment_reference_number": "",
  "footer_notes": "",
  "items": [
    {
      "id": "50000",
      "code": "SKU001",
      "classification": "",
      "unit_price": 6.9,
      "quantity": 6,
      "description": "MATEMATIK - S - MMP",
      "long_description": "",
      "measurement": "",
      "subtotal": 41.4,
      "discount_rate": 0,
      "discount_amount": 6.21,
      "total_excl_tax": 0,
      "service_fee_rate": 0,
      "service_fee_amount": 0,
      "sales_tax_rate": 0,
      "sales_tax_amount": 0,
      "service_tax_rate": 0,
      "service_tax_amount": 0,
      "gst_rate": 0,
      "gst_amount": 0,
      "ttx_rate": 0,
      "ttx_amount": 0,
      "hvgt_rate": 0,
      "hvgt_amount": 0,
      "lvst_rate": 0,
      "lvst_amount": 0,
      "tax_exempt_amount": 0,
      "total_incl_tax": 35.19
    }
  ]
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://einvoice-api.beaconx.com.my/receipts' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "reference_number": "OUTLET-POSID-1131",
    "invoice_number": "OUTLET-POSID-1131",
    "original_einvoice_ref_number": "",
    "pos_id": "",
    "source": "",
    "issued_at": "2024-10-16",
    "outlet_code": "SMG",
    "status": "valid",
    "quantity": 0,
    "subtotal": 117.3,
    "discount_rate": 0,
    "discount_amount": 14.49,
    "service_fee_rate": 0,
    "service_fee_amount": 0,
    "total_excl_tax": 0,
    "sales_tax_amount": 0,
    "service_tax_amount": 0,
    "gst_amount": 0,
    "ttx_amount": 0,
    "hvgt_amount": 0,
    "lvst_amount": 0,
    "total_tax_amount": 0,
    "total_incl_tax": 102.81,
    "rounding": -0.01,
    "currency_code": "MYR",
    "currency_rate": 1,
    "total_payable_amount": 102.80,
    "suppliers_bank_account_number": "",
    "payment_method": "",
    "payment_terms": "",
    "prepayment_amount": "",
    "prepayment_datetime": "",
    "prepayment_reference_number": "",
    "footer_notes": "",
    "items": [
        {
            "id": "50000",
            "code": "SKU001",
            "classification": "",
            "unit_price": 6.9,
            "quantity": 6,
            "description": "MATEMATIK - S - MMP",
            "long_description": "",
            "measurement": "",
            "subtotal": 41.4,
            "discount_rate": 0,
            "discount_amount": 6.21,
            "total_excl_tax": 0,
            "service_fee_rate": 0,
            "service_fee_amount": 0,
            "sales_tax_rate": 0,
            "sales_tax_amount": 0,
            "service_tax_rate": 0,
            "service_tax_amount": 0,
            "gst_rate": 0,
            "gst_amount": 0,
            "ttx_rate": 0,
            "ttx_amount": 0,
            "hvgt_rate": 0,
            "hvgt_amount": 0,
            "lvst_rate": 0,
            "lvst_amount": 0,
            "tax_exempt_amount": 0,
            "total_incl_tax": 35.19
        }
    ]
}'

Responses

🟢200OK

application/json

Body

status

string

optional

message

string

optional

data

object

optional

success

array[string]

optional

failed

array [object {2}]

optional

Example

{
  "status": "OK",
  "message": "",
  "data": {
    "success": [
      {
        "invoice_number": "RCPT005",
        "reference_number": "RCPT005",
        "outlet_code": "001",
        "source": "",
        "pos_id": "P0302",
        "issued_at": "2024-04-30",
        "status": "valid",
        "quantity": 0,
        "subtotal": 117.3,
        "discount_rate": 0,
        "discount_amount": 14.49,
        "total_excl_tax": 0,
        "sales_tax_amount": 0,
        "service_tax_amount": 0,
        "gst_amount": 0,
        "ttx_amount": 0,
        "hvgt_amount": 0,
        "lvst_amount": 0,
        "total_incl_tax": 102.81,
        "total_tax_amount": 0,
        "rounding": 0,
        "total_payable_amount": 102.81,
        "currency_code": "MYR",
        "currency_rate": 1,
        "items": [
          {
            "id": "50000",
            "classification": "",
            "unit_price": 6.9,
            "quantity": 6,
            "description": "MATEMATIK - S - MMP 新北市22069板桥区三民路二段",
            "long_description": "",
            "measurement": "",
            "subtotal": 41.4,
            "discount_rate": 0,
            "discount_amount": 6.21,
            "total_excl_tax": 0,
            "sales_tax_rate": 0,
            "sales_tax_amount": 0,
            "service_tax_rate": 0,
            "service_tax_amount": 0,
            "gst_rate": 0,
            "gst_amount": 0,
            "ttx_rate": 0,
            "ttx_amount": 0,
            "hvgt_rate": 0,
            "hvgt_amount": 0,
            "lvst_rate": 0,
            "lvst_amount": 0,
            "total_incl_tax": 35.19
          }
        ],
        "service_fee_rate": 0,
        "service_fee_amount": 0,
        "sst_rate": 0,
        "sst_amount": 0,
        "buyer": {
          "membership_id": "",
          "name": "",
          "tin": "",
          "id_number": "",
          "sst_number": "",
          "email": "",
          "address": "",
          "contact": ""
        },
        "id": "9d5235b0-3195-454e-a05e-fa61b8fab680",
        "url": "https://iserve.beaconx.com.my/beacon/001/9d5235b0-3195-454e-a05e-fa61b8fab680",
        "document": []
      }
    ],
    "failed": []
  }
}

🟢200Rejected Error

🟠429Rate Limit Error

🔴500Server Error