Overview

Return Receipts are the documents issued by the taxpayer documenting a return of the goods or services purchased by the customer registered with the Tax Authority.

Data Structure

Core

The data structure of the return receipt v1.2 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
contractor	contractor	Optional, Structure representing the contractor information.	See structure.
beneficiary	beneficiary	Optional, Structure representing the beneficiary information.	See structure.

Header

Element	Type	Description	Value example
dateTimeIssued	Mandatory, DateTime in UTC,	Mandatory, Date and time of issuance of return 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 return receipt case in case of validation failure and requirement to change something in the return receipt and resend it with a different UUID. In this case it would be required to send the old UUID for the corrected return 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
documentUseReason	String(1)	Optional,Accept only two values ref Return with no reference Types.	I
salesIssuedDateTime	DateTime in UTC	Optional, accept the issuance date and time in UTC of the sales receipt.	2021-12-20T00:00:00Z

DocumentType

Element	Type	Description	Value example
receiptType	String (20)	Mandatory, the Value must be ‘r’ for Return Receipt	r
typeVersion	String (100)	Mandatory, the Value must be ‘1.2’	1.2

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 (150000 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 (100)	Optional in all cases except when 1.type is B 2.type is P and totalAmount equals to or greater than a configured value (150000 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
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.
additionalCommercialDiscount	discount	Optional, Additional commercial discount after net sale on the item level	10.0
additionalItemDiscount	discount	Optional, Additional item discount after net sale on the item level	10.0
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
rate	Decimal	Optional, Tax rate applied for the invoice line. Value from 0 to 100. If 0 value is provided then the amount will take precedence	1.12

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 (200)	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