Overview
Receipts are the documents issued by the taxpayer for the goods or services purchased by the customer registered with the Tax Authority.
Data Structure
Core
The data structure of the receipt v1.0 documents consists of a single document element that contains these additional elements. Note that this description defines the data structure while actual attribute naming could be different for JSON structure.
| Element |
Type |
Description |
Value example |
| header |
header |
Mandatory, Structure representing the header information. |
See structure. |
| documentType |
documentType |
Mandatory, Structure representing the documentType information. |
See structure. |
| seller |
seller |
Mandatory, Structure representing the seller information. |
See structure. |
| buyer |
buyer |
Mandatory, Structure representing the buyer information. |
See structure. |
| itemData |
itemData |
Mandatory, This would be collection of objects .Structure representing the itemData information. |
See structure. |
| totalSales |
Decimal |
Mandatory, sum of all sales total elements of receipt lines |
1921.12345 |
| totalCommercialDiscount |
Decimal |
Optional, sum of all discount amount elements of receipts lines |
12.12345 |
| totalItemsDiscount |
Decimal |
Optional, sum of all itemsDiscountAmount elements of receipt lines |
12.12345 |
| extraReceiptDiscount |
Array of Decimal |
Optional, Amount of extra receipt level discount |
[12.12345,13.12345] |
| netAmount |
Decimal |
Mandatory, Sum of all receipt lines netTotal |
19271.12345 |
| feesAmount |
Decimal |
Mandatory, Is the additional fees amount of receipt level |
10.12345 |
| totalAmount |
Decimal |
Mandatory, totalAmount = sum of all receipt line total – total extraDiscountAmount |
19281.12345 |
| taxTotals |
taxTotals |
Optional, Structure representing the total tax information. |
See structure. |
| paymentMethod |
String (50) |
Mandatory, Payment Method Codes |
C |
| adjustment |
Decimal |
Optional, monetary amount that will be added to the total of the receipt to perform final adjustments to the total amount of the receipt. This accepts positive or negative amounts |
0.12345 |
| contractor |
contractor |
Optional, Structure representing the contractor information. |
See structure. |
| beneficiary |
beneficiary |
Optional, Structure representing the beneficiary information. |
See structure. |
| Element |
Type |
Description |
Value example |
| dateTimeIssued |
Mandatory, DateTime in UTC, |
Mandatory,Date and time of issuance of receipt |
2022-02-03T00:00:00Z |
| receiptNumber |
String (50) |
Mandatory, receiptNumber is unique per branch within the same submission |
‘ZHFGG221’ |
| uuid |
UUID |
Mandatory, SHA256 format. UUID is a unique key on system level added by taxpayer, it is generated based on receipt content as per receipt base schema, Steps to generate UUID |
68e656b251e67e835… |
| previousUUID |
UUID |
Mandatory, SHA256 format, Reference to previous receipt, empty string value is accepted only if this is the first receipt issued from this POS. |
68e656b251e67e835… |
| referenceOldUUID |
UUID |
Optional, This is not validated and is used for the resent receipt case in case of validation failure and requirement to change something in the receipt and resend it with a different UUID. In this case it would be required to send the old UUID for the corrected receipt in this field to allow searching. |
68e656b251e67e835… |
| currency |
String (3) |
Mandatory, Currency code used from ISO 4217, Currency Codes |
EGP |
| exchangeRate |
Decimal, |
Mandatory when currency not EGP |
0.12345 |
| sOrderNameCode |
String (200) |
Text(30), Optional, Reference to the previous sales order for informational purposes. The field would contain the name of the sales order and/or a reference number to that sales order. |
ABC12345 |
| orderdeliveryMode |
String (30) |
Text(30), Optional, Order Delivery Mode Codes |
FC |
| grossWeight |
Decimal, |
Optional, Total weight of the goods delivered. Value in kilograms |
12.12345 |
| netWeight |
Decimal |
Optional, Net weight of the goods delivered. Value in kilograms |
12.12345 |
DocumentType
| Element |
Type |
Description |
Value example |
| receiptType |
String (20) |
Mandatory, the Value must be ‘s’ for Sale Receipt |
s |
| typeVersion |
String (100) |
Mandatory, the Value must be ‘1.0’ |
1.0 |
Seller
| Element |
Type |
Description |
Value example |
| rin |
String (30) |
Mandatory, Registration number. For business in Egypt must be registration number. |
200173707 |
| companyTradeName |
String (200) |
Mandatory, Registration name of the company. |
ABC Corp |
| branchCode |
String (50) |
Mandatory, The code of the branch as registered with tax authority for the company submitting the document. |
ABC |
| branchAddress |
branchAddress |
Mandatory, Structure representing the branchAddress information. |
See structure. |
| deviceSerialNumber |
String (100) |
Mandatory,This is the POS serial number |
123 |
| syndicateLicenseNumber |
String (30) |
Optional. In case it is a person, then it is a number of minimum 10 characters, if the number is less than 10 characters, leading zeros should be added, example: “0001234567”. In case it is a company, the value should be “C” |
0001234567 |
| activityCode |
String (10) |
Mandatory , Activity Codes |
0111 |
BranchAddress
| Element |
Type |
Description |
Value example |
| country |
String (2) |
Mandatory, Country represented by ISO-3166-2 2 symbol code of the countries. Must be EG for internal business issuers. |
EG |
| governate |
String (100) |
Mandatory, Governorate information as textual value |
Giza Governorate |
| regionCity |
String (100) |
Mandatory, Region and city information as textual value |
Dokki |
| street |
String (200) |
Mandatory, Street information |
17 Nabil Al Wakad |
| buildingNumber |
String (100) |
Mandatory, Building information (number, name or both) |
17 |
| postalCode |
String (30) |
Optional, Postal code |
11311 |
| floor |
String (100) |
Optional, The floor number |
1 |
| room |
String (100) |
Optional, The room/flat number in the floor |
3 |
| landmark |
String (500) |
Optional, Nearest landmark to the address |
Egyptian Museum |
| additionalInformation |
String (500) |
Optional, Any additional information to the address |
Egyptian Museum |
Buyer
| Element |
Type |
Description |
Value example |
| type |
String (1) |
Mandatory, Type of the issuer - supported values - B for business in Egypt, P for natural person, F for foreigner. |
B or P or F |
| id |
String (30) |
Optional in all cases except when
1.type is B
2.type is P and totalAmount equals to or greater than a configured value (50000 EGP) |
Based on type values can be as follows:
1.type is B: Company Registration No. (RIN)
2.type is P: National ID
3.type is F: Any type of Foreigner Identification Number |
| name |
String (200) |
Optional in all cases except when
1.type is B
2.type is P and totalAmount equals to or greater than a configured value (50000 EGP) |
Registration name of the company or name and surname of the person |
| mobileNumber |
String (30) |
Optional, Mobile number of receiver |
+201020567362 |
| paymentNumber |
String (30) |
Optional, a reference to a payment number for which the receipt was issued, this is used for specialized industries that have such reference numbers such as utilities bill for example. It can alternatively contain a reference to the payment method reference such as authorization code in case of credit card payment. |
123 |
ItemData
| Element |
Type |
Description |
Value example |
| internalCode |
String (50) |
Mandatory, Internal code is used for the product being sold – can be used to simplify references back to existing solution. |
8806092129306 |
| description |
String (500) |
Mandatory, Description of the item being sold |
Samsung A02 32GB*LTE_BLACK_DS_SM-A022FZKDMEB_A022 * A022_SM-A022FZKDMEB |
| itemType |
String (30) |
Mandatory, Coding schema used to encode the item type. Must be GS1 or EGS for this version |
EGS or GS1 |
| itemCode |
String (100) |
Mandatory, Code of the goods or services item being sold. GS1 codes targeted for managing goods, EGS codes targeted for managing goods – goods or services |
GS1: 6221218058490, EGS: EG-113317713-1234 |
| unitType |
String (30) |
Mandatory, Code of the unit type used from the code table of the measures |
kg |
| quantity |
Decimal |
Mandatory, Number of units of the defined unit type being sold. Number should be larger than 0. |
17.12345 |
| unitPrice |
Decimal |
Mandatory, cost per quantity of the product |
17.12345 |
| netSale |
Decimal |
Mandatory, Total amount for the receipt line after applying discount. |
36.12345 |
| totalSale |
Decimal |
Mandatory, Total amount for the receipt line considering quantity and unit price |
425.12345 |
| total |
Decimal |
Mandatory, Total amount for the receipt line after adding all pricing items, taxes, removing discounts |
460.12345 |
| commercialDiscount |
Array of Decimal |
Optional, Array of amounts of commercial discounts appiled to this item |
[100.12345,200.12345] |
| itemDiscount |
Array of Decimal |
Optional, Non-taxable items discount |
[100.12345,200.12345] |
| valueDifference |
Decimal |
Optional, Value difference when selling goods already taxed (accepts +/- numbers), e.g., factory value based |
0.12345 |
| taxableItems |
Array of taxableItem |
Optional, Structure representing the taxableItems information. |
See structure. |
TaxableItem
| Element |
Type |
Description |
Value example |
| taxType |
String (30) |
Mandatory, Type of tax applied - from the list of approved tax type codes. The TaxType needs to be unique across the invoice line (no VAT twice in one invoice line), TaxType is from the list of supported tax types. |
T1-T20 |
| amount |
Decimal |
Mandatory, Amount of the tax applied – tax type defined type of tax applies to support different taxes that are possible depending on the type of sales, customer etc. Value with the precision of 2 |
2.12345 |
| subType |
String (50) |
Mandatory, Subtype of the tax types that might mean exemption rate is applied or specific rate linked to product type being sold is applied. |
V001 |
| rate |
Decimal |
Optional, Tax rate applied for the invoice line. Value from 0 to 100. |
2.12 |
TaxTotals
| Element |
Type |
Description |
Value example |
| taxType |
String (30) |
Mandatory, Type of tax applied - from the list of approved tax type codes. The TaxType needs to be unique across the line item (no VAT twice in one invoice line), TaxType is from the list of supported tax types. |
T1-T20 |
| amount |
Decimal |
Mandatory, Sum of all amounts of given tax in all line items. 5 decimal digits allowed. |
838.12345 |
Contractor
| Element |
Type |
Description |
Value example |
| name |
String (100) |
Optional, Name of the Contractor |
ABC CORP |
| amount |
Decimal |
Optional, this is the amount that the contractor is paying from the receipt total amount. This is in case of receipts that has a contractor paying part of the receipt amount such as medical receipts with insurance companies paying part of the amount. |
1536.12345 |
| rate |
Decimal |
Optional, this is the rate that the contractor is paying from the receipt total amount. This is in case of receipts that has a contractor paying part of the receipt amount such as medical receipts with insurance companies paying part of the amount. |
1.12 |
Beneficiary
| Element |
Type |
Description |
Value example |
| amount |
Decimal |
Optional, this is the amount that the beneficiary or buyer is paying from the receipt total amount. This is in case of receipts that has a contractor paying part of the receipt amount such as medical receipts with insurance companies paying part of the amount. |
1536.12345 |
| rate |
Decimal |
Optional, this is the rate that the beneficiary or buyer is paying from the receipt total amount. This is in case of receipts that has a contractor paying part of the receipt amount such as medical receipts with insurance companies paying part of the amount. |
1.12 |
Additional Considerations
For helper information on how to issue a valid receipt, please refer Receipt Issuance FAQ