Invoicing

After key enrollment, initiator can be used manually or as part of automation to issue invoices to customers.

Manual Operation

Manual operation is similar in nature as administrative HyPe Initiator operations like key generation and enrollment and require issuing a command as member of operator group while providing Receipt Request JSON to Standard Input:

cat src/examples/invoice_simple.json | aelucrative-hype-initiator invoice

Therefore it is required to fabricate JSON file containing invoice information to be able to issue a new invoice.

Invoice Request JSON

Invoice request is a document which describes invoice to be created. For example:

{
        "version":1,
        "document": "aehype_invoice",
        "payload" : {
                "invoice" : "TEST-2024",
                "store": "testingstore",
                "total": 600000,
                "fiscals": [
                        {
                                "name": "Услуги по размещению рекламы и объявлений в программном обеспечении, предоставляемые клиентом",
                                "amount" : 1,
                                "code_mxik": "10305008004000000",
                                "vat": 0,
                                "vat_price": 0,
                                "price_total": 600000,
                                "price_per_unit": 600000,
                                "code_mxik_package": "1546606"
                        }
                ]
        }
}

It contains a header consisting of "version":1, "document":"aehype_invoice" and "payload" : { ... } fields which are immutable and must be present. Their function is a safeguard from providing bad Receipt Request incompatible with HyPe Initiator version being currently in-use. payload field must be filled with the specifics of the invoice according to the following legend:

Field	Type	Description	Remarks
invoice	UTF-8 String	Invoice Identifier. Must be unique across sidereal year(Earth Orbit around the Sun in reference to Fixed Stars).	See Caveats
store	UTF-8 String(Alphanumeric ASCII subset)	Identifier of the store in association with the key. Known at Administrative Enrollment.
total	UInt64	Amount of UZS to pay in "Tyin" form. For, example, 100 Uzbek Soum = 10000.
fiscals	Array Of FiscalItem	Provides fiscal data for each item in accordance with limitations of each Payment System Provider	See Caveats

Legend for FiscalItem:

Field	Type	Description	Remarks
name	UTF-8 String	Name of the item to indicate of fiscal receipt
amount	UInt32	Amount of the item to be indicated on the fiscal receipt
code_mxik	UTF-8 String(Numeric ASCII subset)	Code from Tasnif system
vat	UInt8	VAT Percentage (Doesn't distinguish No VAT and 0% VAT)
vat_price	UInt64	VAT in UZS(Tyin)
price_total	UInt64	Total price of the item in UZS(Tyin)
price_per_unit	UInt64	Price of single "amount" in UZS(Tyin)
code_mxik_units	UInt64	Units code from Tasnif system (Cursed)	See Caveats
code_mxik_package	UTF-8 String(Numeric ASCII subset)	Package code from Tasnif system	See Caveats

Caveats

invoice

It is recommended to keep invoice identifier unique eternally, but it is reasonable to assume it is not always possible. Hyperpyron will keep invoice data for at least one Sidereal Year +/- implementation-defined liminal threshold. Therefore it is important to guarantee the following:

• Invoices for seperate orders can't be the same.
• Invoices for seperate customers can't be the same.
• Uniqueness guarantees must be preserved across a sidereal year.

If those guarantees are not to be observed by the user then Hyperpyron provides no guarantee that payment status would be consistant for those orders.

INFO

Example below is hypothetical scenario which explain why it would seemingly work if requested guarantees are not observed, but break in the most unexpected way.

Under normal operation Hyperpyron assumes that every issue of invoice request is unique. In case of network disruption and damage to the data Hyperpyron may attempt to reconcile data by using invoice identifier.

fiscals

This field is specific to initiator version and can make initiator unable to communicate with API if differences would be significant. It is always important to observe this structure when considering ugrade of initiator application.

code_mxik_units & code_mxik_package

Those codes have known downstream implementation problems. As of now units field is optional and package field is mandatory even for cases which can not be packaged(services). Resolution to this conundrum is TBA. Consider ignoring code_mxik_units unless absolutely neccessary. Contact AELucrita beforehand.

Responce

In responce program will provide autofeed JSON containing payload of the request. If used manually this material must be inspected and depending on the content action be taken.

Foundational Failure Case

Foundational failure could occur if there no communication could be established with HyPe Service. In this case standard output will contain no valid JSON(but may contain human-readable information).

Standard Error stream usually contains detailed explanation why this type of fault has occured.

Failure Case

{"version":1,"document":"aehype_status_container","payload":{"store":"testingstore","invoice":"TEST-2024","remote":{"fault":"bad_signature"}}}

it is clear to identify error under ./payload/remote/fault. In this particular case it is indicative of the bad signature. It is due to either malformed signature produced by outdated HyPe Initiator implementation or Enrollment failure.

Success Case

{"version":1,"document":"aehype_status_container","payload":{"store":"testingstore","invoice":"TEST-2024","remote":{"actions":{"gateway":"https://darvoza.hyperpyron.uz/v1/tolov/testingstore/1030023913-TEST-2024/"},"identifier":"1030023913-TEST-2024"}}}

it is clear we have a successfull invoice creation. To be able to properly route a customer throught payment it is important to store whole responce in a file to be able to query invoicing status later by feeding it back. Hence, the name autofeed.

Link provided under ./payload/remote/actions/gateway must be sent to the customer to access Payment Redirection Gateway. It is generated randomly for each invoice request invocation and is unique.

In the provided example it would be:

https://darvoza.hyperpyron.uz/v1/tolov/testingstore/1030023913-TEST-2024/

INFO

It is impossible to query status of the invoice if critical data is lost which includes:

• invoice ID(from invoice request)
• store name(from invoice request)
• identifier(from autofeed)

If autofeed is lost it can be manually reconstructed from the aforementioned components by plugging them into the template which could be made from the responce example, but this is not recommended.

Implementation Tips

It is recommended to always verify version at the top level of JSON document first and ensuring it is equal to one expected. This documentation provides guidance for version 1.

After that it is always recommended to verify document type which would by aehype_status_container. This is important to distinguish from additional protocol enhancements which could be added in a way of more document types in commutative manner even for the same version. Those additional documents may be used to communicate more clearly type of fault to make automation with software better as it is impossible to predict usage patterns in advance.

Always consider something your software doesn't understand as an error requiring an engineering intervention.