Overview
A General Services Return Receipt is a document that states the total amount paid by a client to a business as a refund for a specific service purchased by the customer in the past.
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 |
| extraReceiptDiscountData | Array of discount | Optional, This would be collection of objects of extra receipt level discount. | See structure. |
| netAmount | Decimal | Mandatory, Sum of all receipt lines netTotal | 19271.12345 |
| feesAmount | Decimal | Optional, Is the additional fees amount that will be added to the total of the receipt. This field accepts only zero values. | 0.0 |
| 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 field accepts only zero values. | 0.0 |
Note! feesAmount and adjustment fields are reserved for future use, both accept only zero values.
Header
| 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… |
| referenceUUID | UUID | Mandatory, Reference to The Sale Receipt | 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 |
DocumentType
| Element | Type | Description | Value example |
|---|---|---|---|
| receiptType | String (20) | Mandatory, the Value must be ‘RS’ for General Services Return Receipt | RS |
| 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 |
| 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 | 10007020 |
| 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 |
| commercialDiscountData | Array of discount | Optional, This would be collection of objects of commercial discounts applied to this item. | See structure. |
| itemDiscountData | Array of discount | Optional, This would be collection of objects of non-taxable items discounts. | See structure. |
| 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. |
Discount
| Element | Type | Description | Value example |
|---|---|---|---|
| amount | Decimal | Mandatory, amount of the discount applied | 100.12345 |
| description | String (50) | Mandatory, description of the discount applied | ABCD12345 |
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 |
Additional Considerations
For helper information on how to issue a valid receipt, please refer Receipt Issuance FAQ