Extending Payments

Custom payment drivers can be added to support any payment provider.

Overview

Lunar provides an easy way for you to add your own payment drivers, by default, there is a basic OfflinePayment driver that ships with Lunar, additional providers should be added to your Storefront via addons. Below is a list of available payment drivers.

Available drivers

First party

Stripe

Community

Made a custom driver that should be listed here? Get in touch on the Lunar discord channel to get it added.

Building your own

A payment driver should take into account 2 fundamentals:

Capturing a payment (whether straight away, or at a later date)
Refunding an existing payment

Registering your driver

use Lunar\Facades\Payments;

Payments::extend('custom', function ($app) {
    return $app->make(CustomPayment::class);
});

The payment driver class

The following is the complete class, which is then broken down below.

<?php

namespace App\PaymentTypes;

use Lunar\Base\DataTransferObjects\PaymentAuthorize;
use Lunar\Base\DataTransferObjects\PaymentCapture;
use Lunar\Base\DataTransferObjects\PaymentRefund;
use Lunar\Events\PaymentAttemptEvent;
use Lunar\Models\Transaction;
use Lunar\PaymentTypes\AbstractPayment;

class CustomPayment extends AbstractPayment
{
    /**
     * {@inheritDoc}
     */
    public function authorize(): ?PaymentAuthorize
    {
        if (!$this->order) {
            if (!$this->order = $this->cart->order) {
                $this->order = $this->cart->createOrder();
            }
        }

        // ...
        
        $response = new PaymentAuthorize(
            success: true,
            message: 'The payment was successful',
            orderId: $this->order->id,
            paymentType: 'custom-type'
        );
        
        PaymentAttemptEvent::dispatch($response);

        return $response;
    }

    /**
     * {@inheritDoc}
     */
    public function refund(Transaction $transaction, int $amount = 0, $notes = null): PaymentRefund
    {
        // ...
        return new PaymentRefund(true);
    }

    /**
     * {@inheritDoc}
     */
    public function capture(Transaction $transaction, $amount = 0): PaymentCapture
    {
        // ...
        return new PaymentCapture(true);
    }
}

This is the most basic implementation of a driver, extending the AbstractPayment class provided by Lunar. This class contains useful helpers that can be used in custom drivers. See available methods

Releasing payments

public function authorize();

This is where you’d check the payment details which have been passed in, create any transactions for the order and return the response. If payment is not being taken straight away, any transactions should be set to the type of intent. When the payment is later captured, it is recommended to create another transaction that is related to the intent via the parent_transaction_id.

Capturing payments

public function capture(Transaction $transaction, $amount = 0): PaymentCapture

When you have a transaction that has a type of intent the Staff member who is logged into the hub can then decide to capture it so the card used gets charged the amount that has been authorised. You can pass an optional amount, but be cautious as you generally cannot capture an amount that exceeds the original amount on the intent transaction. If you capture an amount less, services like Stripe will treat that as a partial refund and no further captures can take place on that order. Here you should create an additional transaction against the order to show how much has been captured.

Refunding payments

public function refund(Transaction $transaction, int $amount = 0, $notes = null): PaymentRefund

When refunding a transaction, you can only do so to one that’s been captured. If you need to refund an order that hasn’t been captured you should instead capture an amount less to what’s been authorised. You should only refund transactions with the type capture.

The AbstractPayment class

`cart`

public function cart(Cart $cart): self

Sets the $cart property on the payment driver. When using the authorize method, it is recommended to expect a $cart instance and check for the existence of an order.

`order`

public function order(Order $order): self

Sets the $order property on the payment driver.

`withData`

public function withData(array $data): self

This method allows you to add any additional data to the payment driver, this can be anything that the payment driver needs to function, for example.

Payments::driver('stripe')->withData([
    'payment_intent' => $paymentIntentId
])->authorize();

`setConfig`

public function setConfig(array $config): self

Here you can set up any additional config for this payment driver. By default, this will be called when you register your payment driver and will take any values which are set in config/lunar/payments.php for that type.

Creating transactions

Depending on how your driver works, you’re likely going to need to create some transactions depending on different scenarios.

Database Schema

Lunar\Models\Transaction

Field	Type	Description
`id`	`bigint`	Primary key
`parent_transaction_id`	`foreignId` `nullable`	The ID of the preceding transaction
`order_id`	`foreignId`	The associated order
`success`	`boolean`	Whether the transaction succeeded
`type`	`enum`	One of `intent`, `capture`, or `refund`
`driver`	`string`	The payment driver, e.g. `stripe`
`amount`	`integer`	Amount in the currency’s smallest unit, e.g. `10000`
`reference`	`string`	Provider reference, e.g. `STRIPE_123456`
`status`	`string`	Provider-specific status
`notes`	`string` `nullable`	Any additional notes for the transaction
`card_type`	`string` `nullable`	Card brand, e.g. `visa`
`last_four`	`string` `nullable`	Last four digits of the card
`meta`	`json` `nullable`	Additional provider data
`captured_at`	`dateTime` `nullable`	When the payment was captured
`created_at`	`timestamp` `nullable`
`updated_at`	`timestamp` `nullable`

Best Practices

Releasing

When releasing a payment, if you’re not charging the card straight away, you should create a transaction with type intent. This tells Lunar you intend to charge the card at a later date.

Transaction::create([
    //...
    'type' => 'intent',
]);

If you are charging the card straight away, set the type to capture.

Transaction::create([
    //...
    'type' => 'capture',
]);

Capturing

If the card is already being charged, this step can be skipped as payment has already been received.

When capturing a transaction, you should create an additional transaction with the amount that’s been captured. Even if this is the same amount as the intent transaction.

$intent = Transaction::whereType('intent')->first();

Transaction::create([
    //...
    'parent_transaction_id' => $intent->id,
    'type' => 'capture',
    'amount' => 2000,
]);

Refunding

$capture = Transaction::whereType('capture')->first();

Transaction::create([
    //...
    'parent_transaction_id' => $capture->id,
    'type' => 'refund',
]);

​Overview

​Available drivers

​First party

​Community

​Building your own

​Registering your driver

​The payment driver class

​Releasing payments

​Capturing payments

​Refunding payments

​The AbstractPayment class

​Available methods

​cart

​order

​withData

​setConfig

​Creating transactions

​Database Schema

​Best Practices

​Releasing

​Capturing

​Refunding

Overview

Available drivers

First party

Community

Building your own

Registering your driver

The payment driver class

Releasing payments

Capturing payments

Refunding payments

The AbstractPayment class

Available methods

`cart`

`order`

`withData`

`setConfig`

Creating transactions

Database Schema

Best Practices

Releasing

Capturing

Refunding