Simple Commerce Logo

Building a custom gateway

There's a couple of cases where you might end up building a custom gateway. Either you need to extend an existing gateway and maybe send more/different information to the processor or you may need to connect with a payment processor that we don't include support for.

Creating your gateway

To get you started, you can use the make:gateway command.

1php please make:gateway PayMate

Explaining the methods

The boilerplate gateway has quite a few methods. Here's a quick overview of what each gateway method does and what you should return.

  • name() - should return the name of your gateway
  • prepare() - should be used to either: generate tokens used later on for displaying the payment form or generating an off-site checkout link.
  • purchase() - should be used to do the actual purchase (aka. taking the money from the customer)
  • purchaseRules - should return an array of Laravel Validation Rules for the checkout request.
  • getCharge() - should get information about a specific order's charge/transaction.
  • refundCharge() - should refund an order
  • webhook() - should accept incoming webhook payloads, used for off-site payment gateways.

Gateway types

Simple Commerce supports two types of gateways: on-site and off-site.

On-site gateways are ones on which the customer will enter their credit card information on your site. As an example: think Stripe Elements.

Off-site gateways are ones where the customer is redirected to the payment processor in order to enter their payment information and then once entered, they will usually be redirected back to your website. Mollie is a good example of this.

DTOs

DTOs (also known as Data Transfer Objects) are used to return information back from your gateway to Simple Commerce so it can process it. There's a couple gateway related ones you'll need to know about:

Each of these DTOs will have slightly different uses. You can view some examples of usage on some of the built-in gateways.

Off-site gateways

Callback

Recently, a new callback method has been introduced for off-site gateways. It will be called by Simple Commerce whenever a user is redirected back to your site from the payment gateway.

The method is the deciding factor towards whether the payment was successful or not, this triggers error handling if the payment was not successful.

An example of where this is being used is in the PayPalGateway, see below:

1public function callback(Request $request): bool
2{
3 $this->setupPayPal();
4 
5 $order = OrderFacade::find($request->get('_order_id'));
6 
7 if (!$order) {
8 return false;
9 }
10 
11 $paypalOrder = $order->get('paypal')['result'];
12 
13 $request = new OrdersGetRequest($paypalOrder['id']);
14 
15 $response = $this->paypalClient->execute($request);
16 
17 return $response->result->status === 'APPROVED';
18}

This method may be useful if the status of a payment has not been made clear at the time the user comes back to the server (eg. webhook has not been received yet). You can instead do an API request, or whatever is required, to figure it the status.

Need some help?

There's plenty of ways of getting help: either via opening a GitHub Issue, starting a conversation on the Statamic Discord or directly emailing me.