Digital receipt API guide for approved POS companies

1. Commercial approval

Start by describing the POS product, intended businesses, transaction flow and support model. TerraGridTech reviews current fit before issuing production connection access. Public self-signup and online checkout remain unavailable.

2. Business and plan activation

The business must be linked to the appropriate merchant context and have an active receipt plan. The current POS API Demo is manually activated, includes 50 receipt creations for 30 days, does not renew automatically and is limited to one demo per business. [1]

3. POS connection key

An authorised administrator creates the POS connection key. Handle the reveal carefully and move it into a suitable secret store. Up to two active keys are allowed for the business. Do not design a workflow that depends on repeatedly displaying the original key. [1]

4. Connection test

Run the supported test before receipt traffic. The test consumes zero receipt credits and helps distinguish access configuration from receipt-payload behaviour. [1]

5. Stable receipt operation identity

Assign one stable identity to one intended receipt operation. If the request times out, retry with the same identity. Generating a fresh identity can make the service interpret the retry as a different operation.

6. Receipt creation and QR readiness

Send only the supported sale and receipt fields. On success, present the supported QR or code to the customer without embedding the POS connection key. Treat error categories deliberately; do not turn every failure into a blind retry.

7. Wallet claim and usage

A customer can claim an already-created receipt in TGT User Wallet without consuming an additional receipt credit. Monitor plan usage and inactive or exhausted states. Never tell the customer a claim succeeded solely because the POS displayed a QR. [1]

8. Support and detailed documentation

Approved partners receive the current detailed contract through the controlled support path. This public guide intentionally excludes secrets, private endpoints and unstable implementation detail.

Practical checklist

• Confirm business approval and commercial scope.
• Activate the correct receipt plan.
• Store the connection key securely.
• Pass the zero-credit connection test.
• Implement stable idempotent retry behaviour.
• Handle plan and authorisation errors.
• Test the complete QR and Wallet journey.

Next steps

Report a correction