Epos Now webhook setup (admin)

What the webhook does

Once configured, every time an Epos transaction is completed, Epos sends an HTTP POST to a URL you control. Redeemio's webhook endpoint reads the bill, looks for a "Voucher" discount reason + a reference code that matches a Redeemio voucher, and records the redemption. See Epos Now till integration for the user-facing overview, or the POS integrations page for a comparison with other POS systems.

One-time setup in the Epos back-office

This takes about 2 minutes. You only do it once per Epos account.

1. Get your API credentials (if you don't have them)

1. Sign in to the Epos Now back-office.
2. Go to Settings → Integrations → API.
3. If you don't already have an API key, click Add API Device, give it a name (e.g. "Redeemio"), and copy the API key + secret into your Redeemio .env as EPOS_API_KEY and EPOS_API_SECRET.

2. Create the "Voucher" discount reason in Epos

This is the label that appears on the printed receipt when a voucher is redeemed. Redeemio auto-creates it on first run, but you can also set it manually:

1. Sign in to the Epos back-office.
2. Go to Settings → Discounts.
3. Add a new discount reason called "Voucher" with a default percentage of 0% (the amount is set per-transaction by the waiter).
4. Note the numeric DiscountReasonId (you'll see it in the URL of the discount reason page; it's also in GET /DiscountReason on the API). Paste it into your Redeemio .env as EPOS_VOUCHER_DISCOUNT_REASON_ID.

3. Add the webhook trigger in the Epos back-office

This step can only be done in the Epos back-office UI, not via the API. The Epos API exposes GET /Webhook to read the current config and PUT /Webhook to set the base URL, but the trigger list and Basic Auth credentials are not settable via the API.

As of the latest Epos Now release, the Epos team has redesigned the back-office UI several times. The general flow is:

1. Sign in at https://www.eposnowhq.com/back-office/.
2. Find the section for Webhooks or API (usually under Settings, Integrations, or Web Integrations — the exact location depends on your Epos release).
3. Find the existing API device (the one Redeemio uses) or create a new one.
4. Confirm the webhook URL is https://<your-redeemio-domain>/api/epos/webhook/transaction-completed (or equivalent — trailing slashes may or may not matter).
5. Add a new webhook trigger:
   • Route path: /transaction-completed
   • Event: CompleteTransaction (or "Transaction Completed" in the UI)
6. If Epos asks for Basic Auth credentials on the device, set them to the same values as EPOS_WEBHOOK_USERNAME and EPOS_WEBHOOK_PASSWORD in your Redeemio .env (currently redeemio-webhook / rWhk_8sJ2nQ4pT6vY9xZ_BcD3fG7hK1m).
7. Save.

Tip: if you can't find the right screen, take a screenshot of where you are and share it with us. The Epos UI changes often and I don't have a way to see your account's current state.

4. Test it

1. Sign in to Redeemio as a manager, go to /redeem/till.
2. Scan or type a test voucher (e.g. TESTER-50). Click Verify. Confirm it shows ACTIVE with the expected balance.
3. Ring up a bill in Epos (any amount greater than the voucher).
4. Apply the "Voucher" discount on the bill (with the voucher amount) and type the voucher code into the ReferenceCode field.
5. Tender the bill (Card or Cash) to close it.
6. Within a few seconds, check the voucher state in Redeemio — it should now be REDEEMED (or partially redeemed if the amount was less than the bill).
7. Check the admin audit log: you should see a webhook event with outcome "success" and the Epos transaction ID.

Troubleshooting

The voucher is not being marked as redeemed

• Check the Epos back-office → Web Integrations → API → Webhook Queue. Failed webhooks are listed there with the error message.
• Make sure the bill has both:
  • The "Voucher" discount reason (configured with the DiscountReasonId in your .env).
  • The voucher code in the ReferenceCode field.
• Open the Redeemio admin → Audit Log. Look for entries with eventType: epos_webhook_received — they show what Epos sent. Subsequent entries show whether Redeemio matched it to a voucher.

The bill is in "Partial" or "Ordered" state

Redeemio only acts on bills that Epos reports as StatusId=1 (Completed). If the bill is still open on the till, the webhook is ignored.

Reference code is missing or wrong

The webhook handler matches the ReferenceCode field against the voucher code in Redeemio's database. If they don't match (or the field is empty), the webhook is ignored and logged.

Removing the integration

To turn off the webhook entirely, go to the Epos back-office → Web Integrations → API → API Device → Webhooks, and either delete the trigger or set the device's Webhook URL to empty. Redeemio will simply stop receiving events; no data is lost.