Cash Registers API / Kassen API

Hinweis: Dieses Dokument ist ausschließlich in englischer Sprache verfügbar, um ein breiteres Verständnis bei allen beteiligten Entwicklern sicherzustellen.

Note: This document is available in English only to ensure broader understanding among all involved developers.

API Overview

This API allows cash register systems to interact with Awiti vouchers – to check, redeem (debit), and cancel voucher transactions.

Important: All requests must include a valid Authorization header or will result in HTTP 401 Unauthorized.

Production Endpoint

https://api.awiti.com/

Authorization

• Header: Authorization
• Value: ApiKey [Insert your POA API key here]

1. Check Voucher Balance

GET /api/poa/cash-registers/voucher

Query Parameters:

• code: the voucher UUID or short_code

Possible Responses:

• HTTP 200: data: { totalAvailableAmount, baseBalance, totalCampaignBalance, availablePoints } - Balance successfully retrieved
• HTTP 400: message: voucher_type_not_supported - Unsupported voucher type
• HTTP 401: message: access_denied - Invalid or missing API key
• HTTP 404: message: voucher_not_found - Voucher not found
• HTTP 500: message: ... - Server error
• Multiple Errors: type: errors, data: [ { message: "..." } ] - Multiple error messages

Example Success Response:

2. Redeem Voucher (Debit)

POST /api/poa/cash-registers/voucher/debit

Request Parameters:

• code: the voucher UUID or short_code
• amount: the amount to be debited

Possible Responses:

• HTTP 200: data: { message: debit_successful, transfers: ["UUID"] } - Successful debit, transfer ID(s) provided
• HTTP 400: message: voucher_type_not_supported or insufficient_funds - Unsupported type or not enough balance
• HTTP 401: message: access_denied - Invalid or missing API key
• HTTP 404: message: voucher_not_found - Voucher not found
• HTTP 500: message: ... - Server error
• Multiple Errors: type: errors, data: [ { message: "..." } ] - Multiple error messages

Example Success Response:

2.1. Cancel a Voucher Debit

⚠️ Important: Cancellations of transfers can only be made on the same day.

POST /api/poa/cash-registers/voucher/debit/cancel

Request Parameters:

• code: the voucher UUID or short_code
• transfers: list of transfer IDs received from the debit response

Possible Responses:

Possible Responses:

• HTTP 200: data: { message: cancel_successful } - Cancellation successful
• HTTP 400: message: transfer_cancellation_expired - Time window for cancellation expired
• HTTP 401: message: access_denied - Invalid or missing API key
• HTTP 404: message: voucher_not_found or transfer_not_found - Voucher or transfer ID not found
• HTTP 500: message: ... - Server error
• Multiple Errors: type: errors, data: [ { message: "..." } ] - Multiple error messages

Example Success Response:

Notes

• Voucher Types: Only compatible vouchers can be used at the register. Always validate response types.
• Transfer IDs: Returned in the debit response. Required for cancellation.
• Timeout Handling: Cancellations can only be made on the same day.

3. Recharge Voucher (Top UP)

POST /api/poa/cash-registers/voucher/top-up

Request Parameters:

• code: the voucher UUID or short_code
• amount: the amount to be topped up

Possible Responses:

• HTTP 200: data: { message: top_up_successful, transfers: ["UUID"] } - Successful top up, transfer ID(s) provided
• HTTP 400: message: voucher_type_not_supported - Unsupported type
• HTTP 400: message: error.higherThanBalanceLimit - Requested Amount is higher than the Balance limit
• HTTP 400: message: error.higherThanTopUpLimit - Requested Amount is higher than the Top up limit
• HTTP 400: message: balance_will_exceed_region_limit - Total card funds exceed Balance limit
• HTTP 400: message: restrictions_error - Card is region (ZIP) locked and it doesn’t match the range of the POA location (ZIP)
• HTTP 401: message: access_denied - Invalid or missing API key
• HTTP 404: message: voucher_not_found - Voucher not found
• HTTP 500: message: ... - Server error
• Multiple Errors: type: errors, data: [ { message: "..." } ] - Multiple error messages

Example Success Response:

3.1. Cancel a Voucher Top UP

⚠️ Important: Cancellations of transfers can only be made on the same day.

POST /api/poa/cash-registers/voucher/top-up/cancel

Request Parameters:

• code: the voucher UUID or short_code
• transfers: list of transfer IDs received from the top up response

Possible Responses:

Possible Responses:

• HTTP 200: data: { message: cancel_successful } - Cancellation successful
• HTTP 400: message: transfer_cancellation_expired - Time window for cancellation expired
• HTTP 401: message: access_denied - Invalid or missing API key
• HTTP 404: message: voucher_not_found or transfer_not_found - Voucher or transfer ID not found
• HTTP 500: message: ... - Server error
• Multiple Errors: type: errors, data: [ { message: "..." } ] - Multiple error messages

Example Success Response:

Notes

• Voucher Types: Only compatible vouchers can be used at the register. Always validate response types.
• Transfer IDs: Returned in the top up response. Required for cancellation.
• Timeout Handling: Cancellations can only be made on the same day.

4. Integration Notes & Troubleshooting

When integrating the Poa Cash Registers API, please consider the following best practices and common issues:

Authorization Header Format

All routes require an Authorization header in the following format:

• ✅ Correct: Authorization: ApiKey abc123xyz456
• ❌ Incorrect: Authorization: Bearer abc123xyz456
• ❌ Incorrect: Authorization: abc123xyz456

Tip from development team: If you consistently receive access_denied errors, double-check your authorization logic. A common mistake is to treat the API key as a bearer token or forget to prepend it with ApiKey.

Connection Problems

If your application cannot connect to the endpoint (https://api.awiti.com), ensure that:

• HTTPS is supported by your environment.
• No corporate proxy or firewall is blocking outbound connections.
• You are not behind a transparent proxy rewriting headers.

Testing the API

Before going live, always:

• Use correct and valid voucher codes.
• Test both valid and edge-case scenarios (e.g. insufficient balance, expired vouchers).
• Implement proper retry and timeout handling (especially around the 15-second cancellation limit).

Error Logging

Always log the full error response from the API:

• The message field will guide your error handling logic.
• For multiple errors, inspect the data[] array under type: errors.