Download the PHP package yacoubalhaidari/telr-laravel without Composer

Telr Laravel

Laravel package for the Telr Payment Gateway: Hosted Payment Page, QuickLinks, Remote Invoicing, Repeat Billing Agreements, Webhooks, and the Service API — built directly against Telr's published API documentation.

Installation

Supports Laravel 10, 11, 12, and 13. PHP 8.1 or newer is required by this package; Laravel 13 requires PHP 8.3 or newer. Use the PHP version supported by your selected Laravel release.

Laravel's package auto-discovery will register TelrServiceProvider and the Telr facade automatically.

Laravel 13 is supported by both Illuminate dependency constraints. No vendor edits or application-side DTO patches are needed. Authenticated request DTOs (CreateOrderDTO, CreateQuickLinkDTO, and CreateInvoiceDTO) extend AuthenticatedRequestDTO; nested DTOs extend BaseDTO. Existing toArray(store, credential) signatures, including named arguments, are preserved.

Publish the config file:

Optionally publish the example telr_transactions migration:

Configuration

Add to your .env:

Configure the webhook URL in Merchant Admin under Payment Page / Security → Transaction advice to point at:

(or whatever TELR_WEBHOOK_PATH you set).

The webhook route is registered without the web middleware group since it's a direct server-to-server POST. If your app's VerifyCsrfToken middleware is applied globally elsewhere, add the path to its $except array as well.

Transaction advice must use a nonempty TELR_SECRET_KEY. The verifier accepts the optional tran_order signature field when enabled for your store and works with form data already decoded by PHP. Do not URL-decode the request a second time. See Telr's signature specification.

TELR_SHOW_INVOICE_DATA controls the authenticated-user fallback only. When you pass customer: to CreateOrderDTO, that billing block is always sent to the Hosted Payment Page so name and email can be pre-filled while the customer still enters card details manually. Set the flag to true when you want the package to build customer data from auth()->user() automatically:

Prefer an explicit customer from your domain model (order customer, merchant / join request, subscription owner):

Incomplete fields simply remain editable on Telr's page.

Usage

1. Hosted Payment Page (create + check an order)

Check status later:

2. QuickLinks

Update the card on an existing repeat-billing agreement:

3. Remote Invoicing (XML)

4. Repeat Billing Agreements

5. Browser return + Webhooks

Browser return (recommended application pattern)

Create the Telr order with one signed, payment-specific return URL for authorised, declined, and cancelled outcomes. On return, reload the local payment attempt and call Telr::checkOrderStatus($savedOrderReference). Only OrderStatus::PAID with a matching cart, amount, currency, and test mode should deliver the service. YacoubAlHaidari.com's TelrPaymentController follows this pattern.

Optionally enable the package's static return controller when you use TELR_RETURN_* URLs instead of a payment-specific route:

Transaction advice webhooks

Listen for the typed events dispatched by the built-in webhook controller:

OrderPaymentReconciliation above is an application service you implement. It should resolve the stored checkout by cart ID and use Telr::checkOrderStatus($savedOrderReference) to verify the reference, cart, amount, currency, and environment before changing local state. Only OrderStatus::PAID confirms capture; an authorised event can represent a hold. Use a transaction and idempotent updates so repeated advice cannot deliver an order twice. Configure either automatic event discovery or explicit listener registration for this listener, avoiding duplicate registration.

6. Service API (reporting / reconciliation)

Test Cards

[!IMPORTANT] These cards are for test mode only and will not work for live transactions. Use CVV 123 for an authorised response, except American Express, which uses 1234. Any other CVV returns a declined response.

Use the cards below to exercise hosted payment page integrations. Cards marked with 3DS open Telr's simulated 3D Secure authentication page.

Simulate Declines and Errors

In test mode, pad a Telr transaction response code with a leading 0 to make it a three-digit CVV. For example, use 041 to simulate Insufficient Funds (D, response code 41).

To simulate an on-hold transaction, use CVV 999. The transaction is authorised but held for anti-fraud inspection; no funds are debited until the transaction is accepted in the Merchant Administration System.

For remote invoice or other remote transaction decline simulations, contact Telr Support.

See the official Telr test card documentation for the full response-code reference.

Testing

The suite uses fake HTTP requests and does not call a payment gateway. It covers all DTO classes, provider/container bindings, the facade, hosted checkout, QuickLinks, invoice XML, and authenticated webhook events. The GitHub Actions matrix runs the supported Laravel 10–13 environments using Testbench 8–11.

For Laravel 13 specifically, use PHP 8.3+ and Testbench 11; the included PHP 8.4 CI job uses PHPUnit 13. Composer selects a compatible PHPUnit version on older PHP versions. No application-level patches or edits inside vendor are needed when installing this corrected package version.

License

MIT