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 octane:reload
php artisan module:doctor AcmeGateway

Drop --webhook if the provider has no webhooks. Gateways are registered when an Octane worker boots, so the new one only reaches checkout after the reload.

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

Saved payment methods

Optional.

Customers can save a card or account once, then have renewals and invoices charged to it automatically. To offer that, add Services\{Module}VaultProvider implementing App\Services\Payment\Vault\VaultProviderInterface. Core finds it by name, the same way it finds your payment service, and module:doctor checks it.

Method	Called when
`isAvailable()`	Before the provider is offered anywhere. Return `false` until it’s configured
`clientConfig($user)`	The add-payment-method form renders
`beginSetup($user, $input)`	The customer starts adding a method
`completeSetup($user, $input)`	The provider has confirmed it. Return a `VaultedMethod`
`charge($method, $request)`	Core bills a saved method: auto-renewal, an invoice, a checkout
`remove($method)`	The customer deletes it. Detach it at the provider too

clientConfig()['flow'] picks how the details are collected:

redirect
element

beginSetup() returns ['redirect_url' => ...] and the customer is sent there. Point the provider’s return URL at a route in your module, and finish through core from it:

$method = app(PaymentMethodService::class)->completeSetup(
    $request->user(), 'acme', ['setup_id' => $setupId], null, $makeDefault,
);

PayPalGateway’s VaultController is the reference.

An inline form on the page. Return a component key from clientConfig(), then register a React form under that key from your module’s register.ts:

resources/js/register.ts

import { registerPaymentMethodForms } from '../../../../../resources/js/lib/payment-methods';

registerPaymentMethodForms({
    'acme-card': () => import('./Vault/AcmeCardForm'),
});

The form receives provider, makeDefault, onSaved and onCancel. StripeGateway is the reference.

Charging has its own rules:

Send the idempotency key to the provider

ChargeRequest::$idempotencyKey stays the same when core retries a charge. Pass it as the provider’s idempotency key so a retry can never charge twice.

Return a result, don't throw

A decline is ChargeResult::failed($code, $message). Set methodUnusable when the method is dead (expired, closed, detached) so core stops trying it. If you couldn’t reach the provider, return ChargeResult::unknown(): core holds the attempt and checks again later rather than assuming it failed.

customerPresent tells you who is paying

It’s false for automatic renewals and true when the customer is paying at the keyboard. Tell the provider which kind of charge it is, because off-session charges are treated differently.

Implement lookup() if charges can stay pending

Implementing LooksUpCharges lets core’s sweeper settle attempts left pending or unknown by asking the provider. Return null when the provider has no record of the charge, and core releases the attempt as never submitted. Without lookup(), an unresolved attempt is released after a timeout with a critical log asking an admin to check the provider’s dashboard.

3-D Secure and other confirmations

Return ChargeResult::requiresAction() with what the browser needs, implement HandlesCustomerAction, and register a browser handler for it with registerPaymentActionHandlers() in register.ts, the way StripeGateway does.

Implement ImportsExistingPaymentMethods too if the provider already holds methods for your customers, so they can be listed without being added again.

Subscriptions the gateway bills

Optional.

If your provider runs the recurring schedule itself, add Services\{Module}SubscriptionProvider implementing App\Services\Payment\Subscriptions\GatewaySubscriptionProvider, so core knows the subscription exists:

Method	Core uses it to
`managesRenewal($service)`	Skip its own auto-renewal for that service, so the customer isn’t billed twice
`describeActiveSubscription($service)`	Show the subscription on the customer’s service page
`hasCancellableSubscription($service)`, `cancelSubscriptions($service, $reason)`	Cancel it at the provider when the service is cancelled

This pairs with the checkout and renewal handlers in Native subscriptions, which start the subscription. PayPalGateway is the reference.

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

Saved payment methods

Subscriptions the gateway bills

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

​Saved payment methods

​Subscriptions the gateway bills

​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

Saved payment methods

Subscriptions the gateway bills

Test it

Worth reading