Hooks Reference

artisanpack-ui/ecommerce-paypal exposes its extension points through artisanpack-ui/hooks. Every hook this package fires uses the ap. prefix with camelCase segments.

Register callbacks in a service provider's boot() method. Filters must return a value. Actions return nothing.

use ArtisanPackUI\Ecommerce\Models\Cart;
use ArtisanPackUI\EcommercePayPal\Gateways\PayPalGateway;

addFilter( 'ap.ecommerce.paypal.orderPayload', function ( array $payload, Cart $cart, PayPalGateway $gateway ): array {
    // …
    return $payload;
}, 10, 3 );

Pass the accepted-argument count (the fourth argument) when your callback takes more than one parameter.

For worked examples of the availability hooks, see Availability.

Hooks this package fires

ap.ecommerce.paypal.orderPayload

Filters the POST /v2/checkout/orders body before it is sent. Return the full payload.

Returns array. A non-array return is ignored.

// Add a reference to every PayPal Order.
addFilter( 'ap.ecommerce.paypal.orderPayload', function ( array $payload, Cart $cart ): array {
    $payload['purchase_units'][0]['description'] = 'Order from ' . config( 'app.name' );

    return $payload;
}, 10, 2 );

Changing amount, items, or payment_source can make PayPal reject the Order. PayPal requires the breakdown to add up to amount.value.

ap.ecommerce.paypal.clientOptions

Filters the options of the client config the storefront drivers and paypal-checkout.js read, for example button style or extra SDK settings.

Returns array. The filter can't change order_id, amount, currency, or intent: those are put back from the session. The driver, client id, and Order id outside options aren't passed to it.

addFilter( 'ap.ecommerce.paypal.clientOptions', function ( array $options ): array {
    // The PayPal buttons read their style from `button`.
    if ( isset( $options['button'] ) ) {
        $options['button'] = [ 'layout' => 'horizontal', 'color' => 'black' ];
    }

    return $options;
} );

ap.ecommerce.paypal.supportedCurrencies

Filters the currencies a payment method accepts. A gateway is hidden at checkout for carts in other currencies.

Returns array<int, string>.

ap.ecommerce.paypal.captured

Fires once per order when a capture takes money (COMPLETED) or starts to (PENDING, settled later by webhook). A retried finalize that finds the same capture doesn't fire it again. A capture first recorded after it was already refunded at PayPal reports PARTIALLY_REFUNDED or REFUNDED. A listener that throws is reported and never fails the capture.

addAction( 'ap.ecommerce.paypal.captured', function ( Order $order, string $captureId, string $status ): void {
    Log::info( "PayPal capture {$captureId} ({$status}) for order {$order->order_number}" );
}, 10, 3 );

ap.ecommerce.paypal.captureDenied

Fires when PayPal denies a capture that was pending on a placed order (PAYMENT.CAPTURE.DENIED/DECLINED), after the order note and timeline entry are written and the order's payment status is set to failed (see Webhooks). It fires once those writes have committed. A listener that throws is reported, not rethrown, so the webhook job doesn't retry and write the note and timeline entry again.

ap.ecommerce.paypal.authorizationExpiring

Fires once per authorization, from the daily ecommerce-paypal:authorizations:reauthorize run, when an uncaptured authorization is within 2 days of expiring.

ap.ecommerce.paypal.disputeCreated / disputeUpdated / disputeResolved

Fire for CUSTOMER.DISPUTE.CREATED, .UPDATED, and .RESOLVED, after the order note and timeline entry are written and committed. A listener that throws is reported, not rethrown, so the webhook job doesn't retry and write them again. Disputes never change the order status, so these hooks are where store policy goes.

addAction( 'ap.ecommerce.paypal.disputeCreated', function ( Order $order, array $dispute ): void {
    Notification::route( 'mail', 'support@example.com' )->notify( new DisputeOpened( $order, $dispute ) );
}, 10, 2 );

ap.ecommerce.paypal.webhookEvent

Fires for every verified PayPal webhook delivery the engine hasn't seen before, whether or not this package acts on its type. It runs in the webhook request, so queue anything slow.

The event body may hold payer details, so don't log or store it unredacted. PayPal signs a CRC of the body, not the body itself: fetch a resource from PayPal before acting on it, as this package's handlers do.

Engine hooks this package relies on

ap.ecommerce.payment.availableGateways

The engine filters the gateways offered for a cart. This package uses it to hide a PayPal method that is switched off, or that doesn't accept the cart's currency. Buyer-country eligibility is decided by the PayPal JS SDK in the browser. Hosts can use the filter too.

The engine only accepts narrowing or reordering: entries that aren't the registered gateway for their key are dropped.

use ArtisanPackUI\EcommercePayPal\Gateways\PayPalGateway;

// Hide every PayPal method for orders over $10,000.
addFilter( 'ap.ecommerce.payment.availableGateways', function ( array $gateways, Cart $cart ): array {
    if ( (int) $cart->total_amount <= 1_000_000 ) {
        return $gateways;
    }

    return array_filter( $gateways, fn ( $gateway ): bool => ! $gateway instanceof PayPalGateway );
}, 20, 2 );

Use a priority above 10 so your filter runs after this package's own.

ap.ecommerce.payment.clientConfig

The engine filters the client config of every gateway after the gateway builds it, so it sees the whole config (driver, flow, publishable_key, client_secret, redirect_url, options). Prefer ap.ecommerce.paypal.clientOptions for PayPal options: it keeps the Order and amount from being changed.

use ArtisanPackUI\EcommercePayPal\Gateways\PayPalGateway;

addFilter( 'ap.ecommerce.payment.clientConfig', function ( ?array $config, $gateway ): ?array {
    if ( $gateway instanceof PayPalGateway && null !== $config ) {
        $config['options']['button']['shape'] = 'pill';
    }

    return $config;
}, 10, 2 );