Pay on delivery (#90)

Author: duncanmcclean

docs/docs/payment-gateways.md

@@ -336,6 +336,65 @@ You can workaround this by setting up a tunneling service, like [Expose](https:/
 
 You will need to update the `APP_URL` key in your `.env` while your tunnel is active, so the gateway points towards the tunnel.
 
+## Pay on delivery
+In some markets, you may wish to offer "Pay on delivery" instead of requiring payment upfront. To do this, simply add the built-in `pay_on_delivery` payment gateway to your gateways array:
+
+```php
+// config/statamic/cargo.php
+
+'gateways' => [
+    'pay_on_delivery' => [], // [tl! add]
+],
+```
+
+:::tip note
+The "Pay on delivery" gateway will only be shown to customers when their selected shipping option supports it. 
+
+```php
+// app/ShippingMethods/LocalPostageService.php
+
+public function options(Cart $cart): Collection  
+{  
+	return collect([  
+		ShippingOption::make($this)  
+			->name(__('Standard Shipping'))  
+            ->price(499)
+            ->acceptsPaymentOnDelivery(true), // [tl! add]
+        ]);  
+}
+```
+:::
+
+When orders are placed using "Pay on delivery":
+- They'll start with a status of "Payment Pending"
+- When you ship the order, update the status to "Shipped"
+- Once the delivery company has collected payment and confirmed delivery, update the status to "Payment Received"
+
+Depending on the delivery company, you may be able to automate the final status update via a custom API integration.
+
+### Payment Form
+
+:::tip note
+You don't need to copy this into your project if you're using the [built-in checkout flow](/frontend/checkout/prebuilt), as you'll already have it.
+:::
+
+To use the Pay on delivery gateway, copy and paste this template into your checkout flow:
+
+::tabs
+::tab antlers
+```antlers
+<form x-data="{ busy: false }" action="{{ checkout_url }}" method="POST" @submit="busy = true">
+    <button>Place Order</button>
+</form>
+```
+::tab blade
+```blade
+<form x-data="{ busy: false }" action="{{ $checkout_url }}" method="POST" @submit="busy = true">
+    <button>Place Order</button>
+</form>
+```
+::
+
 ## Build your own
 If you need to use a payment processor that Cargo doesn't support out-of-the-box, it's pretty easy to build your own payment gateway.
 

docs/docs/shipping.md

@@ -40,6 +40,8 @@ class RoyalMail extends ShippingMethod
 
 The `options` method should return a collection of `ShippingOption` objects. The name and the price are displayed to the customer during checkout.
 
+If you want to accept [payment on delivery](/docs/payment-gateways#pay-on-delivery), you'll also need to chain `->acceptsPaymentOnDelivery(true)` when creating shipping options.
+
 You can optionally provide a `fieldtypeDetails` method to your shipping method, allowing you to display information about the shipment in the Control Panel, under the "Shipping" tab:
 
 ```php

resources/views/checkout/payment-forms/_pay_on_delivery.antlers.html

@@ -0,0 +1,5 @@
+<form x-data="{ busy: false }" action="{{ checkout_url }}" method="POST" @submit="busy = true">
+    <div>
+        {{ partial:checkout/components/button label="Place Order" type="submit" }}
+    </div>
+</form>

src/Cart/Cart.php

@@ -128,7 +128,8 @@ public function shippingOption(): ?ShippingOption
         return ShippingOption::make($this->shippingMethod())
             ->name(Arr::get($this->get('shipping_option'), 'name'))
             ->handle(Arr::get($this->get('shipping_option'), 'handle'))
-            ->price(Arr::get($this->get('shipping_option'), 'price'));
+            ->price(Arr::get($this->get('shipping_option'), 'price'))
+            ->acceptsPaymentOnDelivery(Arr::get($this->get('shipping_option'), 'accepts_payment_on_delivery'));
     }
 
     public function paymentGateway(): ?PaymentGateway

src/Http/Controllers/CartPaymentGatewaysController.php

@@ -17,6 +17,7 @@ public function __invoke()
         $cart = CartFacade::current();
 
         return Facades\PaymentGateway::all()
+            ->filter(fn (PaymentGateway $paymentGateway) => $paymentGateway->isAvailable($cart))
             ->map(function (PaymentGateway $paymentGateway) use ($cart) {
                 $setup = $cart->isFree() ? [] : $paymentGateway->setup($cart);
 

src/Payments/Gateways/PayOnDelivery.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace DuncanMcClean\Cargo\Payments\Gateways;
+
+use DuncanMcClean\Cargo\Cargo;
+use DuncanMcClean\Cargo\Contracts\Cart\Cart;
+use DuncanMcClean\Cargo\Contracts\Orders\Order;
+use DuncanMcClean\Cargo\Orders\TimelineEvent;
+use DuncanMcClean\Cargo\Orders\TimelineEventTypes\OrderStatusChanged;
+use DuncanMcClean\Cargo\Support\Money;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+
+class PayOnDelivery extends PaymentGateway
+{
+    protected static $title = 'Pay on delivery';
+
+    public function isAvailable(Cart $cart): bool
+    {
+        return $cart->shippingOption()?->acceptsPaymentOnDelivery() ?? false;
+    }
+
+    public function setup(Cart $cart): array
+    {
+        return [];
+    }
+
+    public function process(Order $order): void
+    {
+        //
+    }
+
+    public function capture(Order $order): void
+    {
+        //
+    }
+
+    public function cancel(Cart $cart): void
+    {
+        //
+    }
+
+    public function webhook(Request $request): Response
+    {
+        return response();
+    }
+
+    public function refund(Order $order, int $amount): void
+    {
+        $order->set('amount_refunded', $amount)->save();
+    }
+
+    public function logo(): ?string
+    {
+        return Cargo::svg('cargo-mark');
+    }
+
+    public function fieldtypeDetails(Order $order): array
+    {
+        $paymentReceivedEvent = $order->timelineEvents()
+            ->filter(function (TimelineEvent $timelineEvent): bool {
+                return get_class($timelineEvent->type()) === OrderStatusChanged::class
+                    && $timelineEvent->metadata()->get('New Status') === 'payment_received';
+            })
+            ->first();
+
+        return [
+            __('Amount') => Money::format($order->grandTotal(), $order->site()),
+            __('Payment Date') => $paymentReceivedEvent
+                ? __(':datetime UTC', ['datetime' => $paymentReceivedEvent->datetime()->format('Y-m-d H:i:s')])
+                : __('Awaiting Payment'),
+        ];
+    }
+}

src/Payments/Gateways/PaymentGateway.php

@@ -16,6 +16,11 @@ abstract class PaymentGateway
 {
     use HasHandle, HasTitle, RegistersItself;
 
+    public function isAvailable(Cart $cart): bool
+    {
+        return true;
+    }
+
     abstract public function setup(Cart $cart): array;
 
     abstract public function process(Order $order): void;

src/Payments/PaymentServiceProvider.php

@@ -10,6 +10,7 @@ class PaymentServiceProvider extends AddonServiceProvider
     protected array $paymentGateways = [
         Gateways\Dummy::class,
         Gateways\Mollie::class,
+        Gateways\PayOnDelivery::class,
         Gateways\Stripe::class,
     ];
 

src/Shipping/FreeShipping.php

@@ -15,7 +15,8 @@ public function options(Cart $cart): Collection
         return collect([
             ShippingOption::make($this)
                 ->name(__('Free Shipping'))
-                ->price(0),
+                ->price(0)
+                ->acceptsPaymentOnDelivery(true),
         ]);
     }
 

src/Shipping/ShippingOption.php

@@ -21,6 +21,7 @@ class ShippingOption implements Augmentable, Purchasable
     public $name;
     public $handle;
     public $price;
+    public $acceptsPaymentOnDelivery = false;
     public $shippingMethod;
 
     public static function make(ShippingMethod $shippingMethod): self
@@ -51,6 +52,11 @@ public function price($price = null)
         return $this->fluentlyGetOrSet('price')->args(func_get_args());
     }
 
+    public function acceptsPaymentOnDelivery($acceptsPaymentOnDelivery = null)
+    {
+        return $this->fluentlyGetOrSet('acceptsPaymentOnDelivery')->args(func_get_args());
+    }
+
     public function shippingMethod($shippingMethod = null)
     {
         return $this->fluentlyGetOrSet('shippingMethod')
@@ -105,6 +111,7 @@ public function augmentedArrayData(): array
             'name' => $this->name(),
             'handle' => $this->handle(),
             'price' => $this->price(),
+            'accepts_payment_on_delivery' => $this->acceptsPaymentOnDelivery(),
             'shipping_method' => $this->shippingMethod(),
         ];
     }
@@ -115,6 +122,7 @@ public function toArray(): array
             'name' => $this->name(),
             'handle' => $this->handle(),
             'price' => $this->price(),
+            'accepts_payment_on_delivery' => $this->acceptsPaymentOnDelivery(),
         ];
     }
 }