Download the PHP package ifthenpay/laravel without Composer

ifthenpay/laravel

Laravel package for ifthenpay payment gateway that facilitates payment generation with Portuguese payment methods and others.

Table of Contents

• Requirements
• Installation
• Usage
  • Generating payments
  • Persisting payments
  • Registering webhooks
  • Receiving webhooks
  • Expiring payments
  • Method Specific Utilities
  • MB WAY check status
  • Credit Card verify return
• Blade Components
• Events
  • Payment Expired
  • Payment Webhook Confirmed
  • Payment Webhook Refunded
  • Payment Webhook Rejected
  • Log
• License

Requirements

(working on backwards compatibility for Laravel 11 and 12)

• PHP ^8.3
• Laravel ^13.0

Installation

Publish the config file:

Run the migrations (creates the ifthenpay_payments table used for optional persistence, loaded automatically by the package):

Configure the package by adding these keys to your .env file. The following is an example of how you would fully configure the package.

Configure only what you need, use the table below for reference.

Usage

Generating Payments

There are two ways to generate payments:

Using the facade This is the recommended approach, but keep in mind it requires you to configure the payment method keys you'll be using.

Direct instantiation In this approach you are responsible for configuring and instantiating the gateway object

Given the payment method type, the generatePayment() method will expect different parameters.

But their return will always be an implementation of IfthenpayResponse interface.

Multibanco

MB WAY

Payshop

Credit Card

Pix

Pay by Link

Persisting payments

If you published and ran the migration for this package, you can use the Payment model Ifthenpay\Laravel\Models\Payment to persist the payments in your database

You can store a payment separately right after generating it:

Or add the HasIfthenpayPayments trait to any Eloquent model (e.g. your Order) to generate and persist a payment linked to it in one line.

Equivalent methods to createMbwayPayment() and mbwayPayments() exist for every payment method.

The payment model also exposes the following methods

Registering webhooks

Register your callback URL with ifthenpay via the ifthenpay:register-webhook command. Note: If IFTHENPAY_ANTIPHISHING_KEY isn't set yet, the command offers to generate and save one for you.

With no options (recommended), it registers a webhook for every payment method you have a key configured for (including every method bundled into paybylink_methods):

Or register a single method explicitly, if you are not using the config to load the method keys and are instantiating the gateway classes directly:

By default this command registers the named route ifthenpay.webhook as the url, but you can use --url to override it and set your own route, just be sure to pass an absolute path without any querystrings.

If you need to add more parameters in the webhook, you must add them with --params

Warning: If the same key is used both standalone and inside paybylink_methods (e.g. IFTHENPAY_MULTIBANCO_KEY=ITP-000000 and IFTHENPAY_PAYBYLINK_METHODS=MULTIBANCO|ITP-000000;...), running the command with no options registers a webhook for that key twice — once for the standalone method, once for paybylink — and whichever registration ifthenpay processes last wins, silently overriding the other's callback URL. This is easy to hit by accident since paybylink_methods commonly reuses the same keys configured for the individual methods. Avoid reusing a key across a standalone method and paybylink_methods if they need different callback URLs, or re-run the command for the affected method/key after registering all methods to make sure the URL you want ends up as the last one registered.

Receiving webhooks

By default the package registers a route at the path configured by ifthenpay.webhook_path (default ifthenpay/webhook), protected by the api middleware group and a named rate limiter (ifthenpay-webhook, default 60/minute — configurable via IFTHENPAY_WEBHOOK_RATE_LIMIT_PER_MINUTE).

To fully customize or disable this route (e.g. to point it at your own controller), publish the routes file into your app:

Once routes/ifthenpay.php exists in your application, the package loads that file instead of its own — edit, replace, or empty it as needed.

Incoming requests are validated (required pm/apk/val/oid/ref/req query params, apk checked against IFTHENPAY_ANTIPHISHING_KEY), matched to a stored Payment by method-specific fields, and amount-checked in cents to avoid float issues. On success the matching payment is marked paid; a negative amount is treated as a refund and leaves the payment's status untouched. Every outcome fires an event you can listen for — see Rejected below.

Expiring payments

All payment methods can be attributed an expiration, but only Multibanco(online), Payshop, Pay-by-link can use it to block access to payment after that time expires, meaning after that payment has expired, the user will not be able to pay (Multibanco and Payshop) or access the gateway page (Pay-by-link).

This functionality can still be used to manage abandoned payments for all payment methods, so that you can update the payments that are pending to expired. To use this functionality you need to pass the expiration (varies by payment method: days or minutes) when generating the payment.

The command ifthenpay:payments:expire, marks pending payments as expired once expires_at has passed and fires an event Ifthenpay\Laravel\Events\PaymentExpired for each (--dry-run lists them without changing anything). Schedule it yourself in routes/console.php, and set the frequency you like.

If you want to add expiration to payments you may use this table as suggestion

Method Specific Utilities

You can make use of these utilities if you want to change/improve the user experience, but are optional and you can still implement the methods without relying on them.

MB WAY check status

MB WAY payments can be actively polled for status via checkStatus(), in addition to being updated by webhook. It requires the Payment's request_id (returned by ifthenpay when the payment was generated) to be set. This functionality is useful when implementing a countdown timer that shows feedback about the status to the user.

checkStatus() returns a MbwayStatusResponse with a typed status (Ifthenpay\Laravel\Enums\MbwayStatus: PENDING, PAID, EXPIRED, REFUSED_BY_USER, REJECTED_BY_MBWAY) and a message. isSuccessful() only returns true when status is MbwayStatus::PAID.

Credit Card verify return

When generating a credit card payment, you'll get a Credit Card gateway page url in the response, to which you will redirect the user, upon being redirected back (to successUrl, errorUrl, or cancelUrl), ifthenpay appends a sk (secret key) query parameter. Use verifyPayment() to confirm the redirect is authentic before trusting it — e.g. before showing a success page. You can also ignore this verification system and rely solely on the webhook.

verifyPayment() returns void on success and throws IfthenpayException (secret key mismatch) on failure — it does not return a response object like the other gateway methods.

Blade Components

The package registers its views under the ifthenpay namespace, so its Blade components are available anywhere in your app as <x-ifthenpay::*>, no publishing required.

All of them are styled with Tailwind CSS v4 utility classes (including dark: variants for dark mode) and ship no CSS of their own — they render correctly out of the box only in an app that already has Tailwind set up. See Customizing the components below if your app doesn't use Tailwind, or if you just want a different look.

<x-ifthenpay::payment-details>

Renders a card summarizing a Payment model, dispatching to the right method-specific partial (below) based on $payment->method.

Any attributes you pass through (e.g. class="...") are merged onto the root <div>.

Method-specific partials

payment-details renders one of these internally based on $payment->method, but each can also be used standalone if you're building your own layout — they all just take a :payment prop:

Each partial no-ops (renders nothing) if the field it needs (entity/reference/payment_url) isn't set on the payment yet.

Customizing the components

These components are bland and generic, because they are meant as a base for what you may want to display to your user. Publish the views to get an editable copy in your own app and customize it to your needs:

This copies every .blade.php file (payment-details and all six method-specific partials) into resources/views/vendor/ifthenpay/components/. Laravel prefers published views over the package's own, so once they exist there, editing them (markup, copy, or swapping the Tailwind classes for your own CSS/framework) is picked up automatically by every <x-ifthenpay::*> tag already in use — no need to change any of your existing usages.

If you keep the Tailwind classes, make sure your resources/views/vendor/ifthenpay/** directory is covered by Tailwind's @source/content scanning (Tailwind v4's automatic content detection already covers resources/views by default, so this is usually a non-issue unless you publish elsewhere or use a custom Tailwind config).

Events

The package fires typed events for webhook outcomes and payment expiry. Every event implements Ifthenpay\Laravel\Contracts\LoggableEvent (logLevel(), logMessage(), logContext()), which is what the bundled LogIfthenpayEvent listener relies on.

Payment Expired

Fired by the ifthenpay:payments:expire command for each payment it marks as expired (see Expiring payments).

Payment Webhook Confirmed

Fired when an incoming webhook passes validation with a positive amount matching the stored payment. The payment has already been marked as paid by the time this fires.

Payment Webhook Refunded

Fired when an incoming webhook carries a negative amount. The matching payment's status is left untouched. This packaged does not have a refund feature, but you can make use of this event to implement it yourself. Check the official documentation on how to implement the refund endpoint LINK

Payment Webhook Rejected

Fired when an incoming webhook fails validation — missing/invalid query params, an anti-phishing key mismatch, no matching payment, or an amount mismatch. The HTTP response is always a generic 400 regardless of reason, so a caller can't learn which check failed; the reason is only available to your listener.

Log

Optionaly, you can log the webhook events by just using the event listener LogIfthenpayEvent included in this package to enable logging for the four events mentioned above. To enable it, just add this line in the your AppServiceProvider.

This log never includes secrets (e.g. the webhook's anti-phishing key is stripped before logging). It reports method, order_id, reference, request_id, amount for webhook events, or id, method, order_id, expires_at, status for PaymentExpired.

License

MIT.