Payment Gateways

You only teach it how to talk to your provider.

Read Fundamentals first if you haven’t.

Generate it

php artisan make:module Acme --type=gateway --webhook
php artisan module:enable AcmeGateway
php artisan module:migrate AcmeGateway
php artisan module:doctor AcmeGateway

Drop --webhook if the provider has no webhooks.

What you get

Modules/Gateways/AcmeGateway/
├── module.json
├── app/
│   ├── Providers/
│   ├── Http/Controllers/
│   │   ├── PaymentController      3 lines, inherits everything
│   │   └── SettingsController     admin page
│   ├── Services/
│   │   └── AcmeGatewayPaymentService   your work goes here
│   └── Models/AcmeCredential
└── routes/                        web, api (webhook), settings, payment

Two naming rules

Both are enforced by how discovery works, so they aren’t optional.

The module must be named {Something}Gateway

PaymentServiceProvider scans Modules/Gateways/* and derives a key from the name, so AcmeGateway becomes acme.

The payment service must be at Modules\{Module}\Services\{Module}PaymentService

And getGatewayName() has to return that same key.

Registration is lazy: nothing is instantiated at boot, so credentials are only decrypted when a payment actually happens. Don’t put API calls in your constructor.

What you implement

BasePaymentService handles every billing flow already. It looks at $paymentData['type'] and routes to the right one.

The flows it covers

Type	Meaning
`market`	New purchase
`renewal`	Renewal
`invoice`	Existing invoice
`upgrade`, `downgrade`	Plan change
`addon`	Addon purchase
`balance`	Account credit
`standalone`	Standalone invoice
`configurable_options_change`	Resource change

You write six methods. The generator stubs all of them.

app/Services/AcmeGatewayPaymentService.php

class AcmeGatewayPaymentService extends BasePaymentService
{
    // Create the payment at the provider. Return a payment id, plus an
    // approval URL if the customer needs to be redirected.
    public function createPayment(float $amount, string $currency, array $metadata = []): array

    // Confirm it actually succeeded. Re-query the provider here.
    public function executePayment(string $paymentId, ?string $payerId = null): bool

    public function getPaymentDetails(string $paymentId): array

    // Null means the token is dead and core should start over.
    public function getApprovalUrl(string $paymentId, array $paymentDetails): ?string

    // 'enabled' decides whether this shows at checkout.
    public function getConfig(): array

    public function validateNotification(array $data): bool

    // 'redirect', 'webhook' or 'both'
    public function getVerificationMethod(): string

    protected function getGatewayName(): string
}

enabled is the on/off switch

Keep it false until the gateway is fully configured. A half-set-up gateway appearing at checkout is worse than it not appearing at all.

'enabled' => (bool) $this->credentials()?->isConfigured(),

The available-gateways list is cached for five minutes, so your settings controller has to call flushPaymentGatewayCache() after saving. The generator does this. Remove it and admins will think saving is broken.

Verification: pick one

Value	What happens	Use when
`redirect`	Confirmed when the customer comes back	No webhooks available
`webhook`	Waits for the webhook, return page says “processing”	Provider is webhook-first
`both`	Redirect confirms right away, webhook reconciles	Default. Good UX plus a safety net

Four rules, and none of them are stylistic.

Never trust the redirect

Re-query the provider inside executePayment(). Query strings are attacker-controlled.

Verify the webhook signature against the raw body, before parsing

$expected = hash_hmac('sha256', $request->getContent(), $secret);

return hash_equals($expected, $signature);   // hash_equals, never ==

Assume webhooks arrive twice

Providers retry. handlePaymentSuccess() has to be safe to call again for the same payment, so check the PaymentToken state first.

Check the amount and the currency

Not just the status. Confirm what was paid is what you asked for.

Native subscriptions

Optional.

If your provider owns the recurring schedule (Stripe Subscriptions, PayPal Billing Agreements), add a flow handler. Core will use it instead of one-off payments.

Class	Intercepts
`Services\CheckoutHandler`	New service checkout
`Services\RenewalHandler`	Renewals
`Services\InvoicePaymentHandler`	Invoice payment (renewal and market only)

Each is a should...() predicate plus a handle...() action. Core probes with method_exists() first, so a half-finished handler falls back to the normal flow rather than erroring.

The argument lists are long and positional: handleCheckout() takes 23, handleRenewal() 7, handleInvoicePayment() 6. module:doctor checks yours against those counts.

Declare it explicitly rather than relying on the class name:

public function getGatewayFlowHandler(): object
{
    return app(CheckoutHandler::class);
}

Modules/Gateways/BankWireGateway/Services/CheckoutHandler.php is a short readable example: it creates the invoice and waits for proof of payment.

Several checkout options from one module

Optional.

Implement GatewayVariantInterface to appear more than once, like “PayPal” and “PayPal Subscription”.

public function getGatewayVariants(): ?array   // return null for normal behaviour
public function resolveVariant(string $variantKey): bool
public function getModuleName(): string

Test it

php artisan module:doctor AcmeGateway

Then run every flow in sandbox, because they all go through the same type switch:

New purchase

Renewal

Invoice payment

Upgrade

Balance top-up

Cancel halfway

Confirm no service is created.

Pay, then close the browser before the redirect

The webhook should still finish the order.

Replay the same webhook twice

Nothing should double-charge or double-provision.

The last two are where real gateways break.

Worth reading

BankWireGateway

Offline payment, no API at all.

CashfreeGateway

Clean HMAC webhook verification.

VippsGateway

Straightforward redirect flow.

StripeGateway

Cards plus native subscriptions.

PayPalGateway

Everything, including variants and disputes.

Two rough edges. PaymentGatewayInterface assumes one flow (create, approve, execute), so refunds and partial captures have no contract and gateways that support them expose their own methods. And BankWireGateway mixes root and app/ layouts, which makes it a good behavioural reference and a poor structural one.

GETTING STARTED

MAKE YOUR OWN

SPARTAN THEMES

Generate it

Two naming rules

What you implement

enabled is the on/off switch

Verification: pick one

Native subscriptions

Several checkout options from one module

Test it

Worth reading

BankWireGateway

CashfreeGateway

VippsGateway

StripeGateway

PayPalGateway

​Generate it

​Two naming rules

​What you implement

​enabled is the on/off switch

​Verification: pick one

​Native subscriptions

​Several checkout options from one module

​Test it

​Worth reading

BankWireGateway

CashfreeGateway

VippsGateway

StripeGateway

PayPalGateway

Generate it

Two naming rules

What you implement

enabled is the on/off switch

Verification: pick one

Native subscriptions

Several checkout options from one module

Test it

Worth reading