Payment Callback API Specification¶

Overview¶

The Payment Callback APIs handle browser redirects from the Telr payment gateway after a customer completes, cancels, or has a payment declined. These are GET endpoints (not POST) because Telr redirects the customer's browser directly to them. They return HTML pages (not JSON), loaded from templates in $TLINQ_HOME/templates/.

There are two callback API classes:

API Class	Base Path	Purpose
`PaymentCallbackApi`	`/payment/offline`	Offline ticket payment callbacks
`HotelPaymentCallbackApi`	`/payment/hotel`	Hotel package booking payment callbacks

Content Type: Response is text/html

Authentication: These endpoints are accessible to guest, agent, and admin roles since they are hit by browser redirects from the payment gateway.

Offline Ticket Payment Callbacks¶

Base Path: /payment/offline

GET /payment/offline/success¶

Called when the customer completes a payment successfully. Confirms the payment, updates sale and ticket statuses to PAID/SOLD, creates an Odoo invoice, and sends a download email to the customer.

Roles: guest, agent, admin

Query Parameters:

Field	Type	Required	Description
ref	string	Yes	Cart reference identifying the reservation

Behavior:

Calls OfflineTicketFacade.confirmPaymentAndNotify() which:
Updates sale payment status to PAID and sale status to COMPLETED
Updates ticket status to SOLD
Creates/confirms the Odoo invoice
Sends a download email with ticket links to the customer
Renders the payment-success.html template with placeholders:
{{customerName}} — Customer name
{{customerEmail}} — Customer email
{{cartReference}} — Cart reference
{{ticketCount}} — Number of tickets purchased

Response: HTML page confirming successful payment.

Error Handling: If processing fails after payment, returns an HTML error page asking the customer to contact support with their reference number.

GET /payment/offline/cancel¶

Called when the customer cancels the payment process. Updates payment status but keeps the reservation active so the customer can retry.

Roles: guest, agent, admin

Query Parameters:

Field	Type	Required	Description
ref	string	Yes	Cart reference

Behavior:

Updates sale payment status to CANCELLED_PAYMENT (reservation stays active)
Sends a payment failure notification email
Renders the payment-cancelled.html template with:
{{customerName}} — Customer name
{{cartReference}} — Cart reference

Response: HTML page informing the customer the payment was cancelled.

GET /payment/offline/decline¶

Called when the payment gateway declines the transaction. Similar to cancel, but indicates a gateway-side rejection.

Roles: guest, agent, admin

Query Parameters:

Field	Type	Required	Description
ref	string	Yes	Cart reference

Behavior:

Updates sale payment status to DECLINED (reservation stays active)
Sends a payment failure notification email
Renders the payment-declined.html template with:
{{customerName}} — Customer name
{{cartReference}} — Cart reference

Response: HTML page informing the customer the payment was declined.

Hotel Package Payment Callbacks¶

Base Path: /payment/hotel

These endpoints follow the same pattern as the offline ticket callbacks but handle hotel package bookings via PackageBookingFacade.

GET /payment/hotel/success¶

Called on successful hotel package payment.

Roles: guest, agent, admin

Query Parameters:

Field	Type	Required	Description
ref	string	Yes	Cart reference for the hotel booking

Behavior:

Calls PackageBookingFacade.confirmPaymentByCartRef() to confirm the booking payment
Renders the hotel-payment-success.html template with:
{{customerName}} — Customer name
{{cartReference}} — Cart reference

Response: HTML page confirming successful payment.

GET /payment/hotel/cancel¶

Called when the customer cancels hotel package payment.

Roles: guest, agent, admin

Query Parameters:

Field	Type	Required	Description
ref	string	Yes	Cart reference

Behavior:

Calls PackageBookingFacade.updatePaymentStatus() with status CANCELLED_PAYMENT
Renders the hotel-payment-cancelled.html template with:
{{cartReference}} — Cart reference

Response: HTML page informing the customer the payment was cancelled.

GET /payment/hotel/decline¶

Called when the hotel package payment is declined.

Roles: guest, agent, admin

Query Parameters:

Field	Type	Required	Description
ref	string	Yes	Cart reference

Behavior:

Calls PackageBookingFacade.updatePaymentStatus() with status DECLINED
Renders the hotel-payment-declined.html template with:
{{cartReference}} — Cart reference

Response: HTML page informing the customer the payment was declined.

HTML Templates¶

Templates are loaded from $TLINQ_HOME/templates/ on each request (no caching), so changes take effect immediately.

Template File	Used By	Purpose
`payment-success.html`	`/payment/offline/success`	Offline ticket payment success
`payment-cancelled.html`	`/payment/offline/cancel`	Offline ticket payment cancelled
`payment-declined.html`	`/payment/offline/decline`	Offline ticket payment declined
`hotel-payment-success.html`	`/payment/hotel/success`	Hotel booking payment success
`hotel-payment-cancelled.html`	`/payment/hotel/cancel`	Hotel booking payment cancelled
`hotel-payment-declined.html`	`/payment/hotel/decline`	Hotel booking payment declined

Templates use {{placeholder}} syntax. All placeholder values are HTML-escaped before insertion.

If a template file is missing, a generic fallback HTML page is returned.

Configuration¶

The Telr callback URLs are configured in tlinqapi.properties:

pgw.callback-base=https://yourdomain.com/tlinq-api

This base URL is used to construct the full callback URLs that are registered with Telr when creating a payment session: - Success: {base}/payment/offline/success?ref={cartReference} - Cancel: {base}/payment/offline/cancel?ref={cartReference} - Decline: {base}/payment/offline/decline?ref={cartReference}

Important Notes¶

These endpoints are GET requests (browser redirects), not POST. This is an exception to the standard TQPro API convention.
Responses are HTML, not JSON. They are meant to be displayed directly to the customer in their browser.
The ref query parameter maps to the internal cartReference used throughout the offline ticket and hotel booking systems.
On success callbacks, the system performs side effects (invoice creation, email sending). If these fail, the error is logged and an error HTML page is shown, but the payment itself is not reversed — manual intervention may be needed.