Search by

masterpuffin / payment-gateways

MasterPuffin

Package info

github.com/MasterPuffin/PaymentGateways

pkg:composer/masterpuffin/payment-gateways

Statistics

Installs: 191

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

4.4.0 2026-11-21 10:52 UTC

This package is auto-updated.

Last update: 2026-11-21 10:53:21 UTC


README

Integrate payments with just a few lines of code.

Why does this exist?

There are two main reasons which no other payment library offered which made me write this library:

  1. I want a unified approach to process payments from different payment providers. This means I want to always call the same function in the same order regardless of the process of the payment provider. This rules out using the libraries of the payment providers on their own. This also rules out Omnipay.
  2. It should be simple to use and shouldn't require a framework like Laravel or Symfony. This rules out Payum.

What does it do?

It creates the payment and returns the redirection url to the payment provider. After the payment provider redirects back to your site, this will verify the payment has been made. It will also handle incoming webhooks, verify them and return the payment status.

What does it not do?

Saving the payments. You have to save the payment before redirecting to the payment provider and retrieve it to verify the payment.

Which gateways are supported?

Currently Stripe Checkout and PayPal REST.

Can you give me an example?

Sure!

First create a payment and set its data

$payment = new Payment();
$payment->setAmount(123.45);
$payment->setCurrencyCode('EUR');
$payment->setDescription('Test payment');
$payment->getCustomer()->setName('John Doe');
$payment->getCustomer()->setEmail('john@doe.com');

Then make a gateway. Some gateways require additional data. If not supplied, this library will throw an exception.

$gateway = new PaymentGateway(Provider::Stripe, ['secret_key' => 'abc'], ['payment_method_types' => ['card']]);
$gateway->setSuccessUrl('https://www.example.com/success');
$gateway->setCancelUrl('https://www.example.com/success');

Now create the gateway for the payment. This will return the redirection url to the payment provider.

$redirectUrl = $gateway->create($payment);

Stripe Checkout creates a Stripe customer with the customer's name and e-mail address for every payment that has an e-mail address, so the dashboard shows them for every payment method (Klarna and SEPA Direct Debit collect none themselves). A returning buyer gets a new customer each time.

Also save the payment somewhere, for example to a database. Creating the gateway also updated the providerId of the payment which will be needed later to verify the payment. Then redirect to the redirectUrl.

After the user has been redirected back to your site, execute/capture and verify the payment.

$gateway = new PaymentGateway(Provider::Stripe, ['secret_key' => 'abc'], ['payment_method_types' => ['card']]);
$result = $gateway->execute($payment);

You can now use the result (which can be different e.g. succeeded, pending or failed). It is best practice to check if the cart has been modified during the checkout process, by comparing $payment->getAmount() with the amount of the cart.

Important! Some Stripe Payment methods don't allow asynchronous capture (e.g. SEPA debit). This library tries to use asynchronous capture, whenever possible. Where not possible, that payment will be created and captured on create. The best way to handle this, is either avoiding payment methods which can't be captured asynchronously or to call $paymentGateway->cancel($payment) which cancels the payment. This however only works, if the payment state is pending.
See the Stripe Docs for more info.

Webhooks

Look up the saved payment with the id from the webhook, then let the library verify the event and return the status.

$gateway = new PaymentGateway(Provider::Stripe_Checkout, ['secret_key' => 'abc', 'webhook_secret' => 'whsec_abc']);
$providerId = $gateway->getProviderIdFromWebhook($request); // PSR-7 request, not verified yet
//TODO load the payment saved with $providerId
$status = $gateway->getStatusFromWebhook($payment, $request);

Stripe events are verified with the webhook secret. PayPal events are not signed reliably, so the library fetches the status of the capture from the PayPal API instead of trusting the payload.

Should I use this?

If you just want to integrate payments, then yes. If you need any more functionality, like subscriptions or more gateways I would suggest taking a look at Payum.

Known issues

PayPal disputes need a direct API call

The PayPal Server SDK has no disputes API, so the dispute check calls it directly with the SDK's OAuth token (requires ext-curl).

Disputes via PayPal webhooks

Incoming PayPal webhooks can't be securely verified without preventing MITM attacks, so the payload is never trusted. For dispute events the library requests the dispute from the dispute API and only reports Disputed if it is unresolved and belongs to the payment's capture. Resolved disputes return the status of the capture. A capture stays COMPLETED while it is disputed, so for a payment stored as Disputed a completed capture is only reported as Succeeded (with disputeWon) for a dispute of this capture that the API confirms as resolved in favour of the seller (dispute_outcome.outcome_code RESOLVED_SELLER_FAVOUR, RESOLVED_WITH_PAYOUT, CANCELED_BY_BUYER or DENIED); every other event keeps it Disputed. Amount and id of the dispute come from the API as well.

Webhooks

Look the stored payment up by the ids the webhook names, most specific first, then let the gateway verify and parse it:

foreach ($gateway->getProviderIdsFromWebhook($request) as $id) {
    $payment ??= findStoredPayment($id);
}
$event = $gateway->parseWebhook($payment, $request);

$event->status is the status after the event (the stored one if the event doesn't change it). $event->refundedTotal is the sum of all refunds and $event->disputedAmount the chargeback, both in the major unit of the currency and null if unknown (PayPal's refund total and dispute amount are read from its API). With $event->checkoutCompleted the customer finished the Stripe Checkout page: call execute() to settle the payment, also when the customer never returns to your site. $event->disputeWon is true only when the dispute of the payment was closed in favour of the seller (Stripe charge.dispute.closed won or warning_closed, PayPal a dispute of the capture resolved for the seller). Only then end a chargeback in your ledger: a Succeeded without it is no decision about a dispute, e.g. a redelivered success event. With disputeWon, disputedAmount is the amount that comes back, null if no funds were withdrawn (an inquiry). Pass the stored status to parseWebhook() (read it under the lock you process the payment with), both providers answer by it.

Dispute events carry $event->disputeId. They are delivered repeatedly and in any order (a Stripe charge.dispute.closed can arrive before its charge.dispute.created), so book each dispute once by its id. A lost closing is reported as Disputed with its amount, a won one with the amount that came back, so a dispute whose opening never arrived can still be booked. A Stripe inquiry (status warning_*) withdraws no funds and keeps the payment's status; it becomes a chargeback when Stripe updates the same dispute to needs_response (charge.dispute.updated, charge.dispute.funds_withdrawn). Subscribe to charge.dispute.created, charge.dispute.updated, charge.dispute.funds_withdrawn and charge.dispute.closed.

Time and reason of a status

$event->occurredAt is the Unix time the reported status came about at the provider, null if unknown: the time of the event for webhooks; for fetchStatus() the time of the failed charge, the cancellation or the expired Checkout session (Stripe) or of the last change of a pending or declined capture (PayPal), only for payments without money movement (Pending, Authorized, Failed, Cancelled). Store it with the status: without webhooks a failure may only be noticed a day later, and dated by your check it would appear after things that happened before it. $event->failureReason tells why the latest attempt to pay failed: WebhookEvent::REASON_BLOCKED (the provider refused it as too risky, e.g. Stripe Radar) or WebhookEvent::REASON_DECLINED (bank or card issuer); null otherwise or if unknown (webhooks don't name it). A Stripe payment whose card failed waits for another payment method (Pending) and is cancelled a day later (Failed); both report the time and reason of the failed charge.

Status::supersedes() tells whether a reported status is outdated, webhooks arrive in any order. execute() returns Open for a Stripe Checkout session the customer has not completed and Cancelled for an expired one; cancel() expires an open session. A Stripe payment that was refunded or disputed meanwhile is returned as such (the payment intent stays succeeded after a refund).

Without webhooks

fetchStatus($payment) reads the current state of a stored payment and returns a WebhookEvent like parseWebhook(), without changing anything (no capture). Use it to settle pending payments (Stripe SEPA, PayPal eCheck) on a schedule or when staff check a payment by hand. Stripe reports refunds with their sum and the dispute of the charge; PayPal reports the capture's status (the refund sum only for a complete refund, a disputed payment stays Disputed).

Tests

Every provider behaviour is tested against the real test APIs (tests/StripeTest.php, tests/PayPalTest.php, base tests/NetworkTestCase.php). They run only with credentials in the environment and are skipped otherwise:

export STRIPE_TEST_SECRET_KEY=sk_test_...
export PAYPAL_SANDBOX_CLIENT_ID=...
export PAYPAL_SANDBOX_SECRET=...
vendor/bin/phpunit

Only test objects are created: Stripe payments with test cards and the test IBAN, PayPal payments with sandbox cards (card processing must be enabled for the sandbox app). The Stripe Checkout page and PayPal's approval page need a buyer in the browser, so payments are made through the API. Stripe webhooks are the real events from the Events API, PayPal webhooks the payloads of PayPal's webhook simulator. A full run takes a few minutes, it waits for Stripe's events and disputes.

Offline (*OfflineTest.php, StatusTest.php) is only what the providers can't produce on request: a completed Stripe Checkout, closed Stripe disputes, PayPal disputes, the return after a PayPal approval, rare capture statuses and failures (tests/FakePayPal.php replaces PayPal's SDK client).