Shopfront Developers

Payments API

This API allows you to integrate your payment services directly into our sell screen.

Setting Up

Before you begin development on your integration you'll need to know a few things:

  • We only support the Google Chrome browser
  • Your integration must be able to run in a web browser (or interface with one)
  • We communicate with your integration by using the postMessage API

We would suggest creating a trial store to develop and test your integration with rather than using a live store.

Once you're ready to begin integrating your payment service you must setup a web address (from now on referred to as "gateway address") that is accessible from the device that will be performing the payment (it does not need to be accessible from the general internet).

Once you have setup your gateway address you'll need to map a payment method to use it. Open the Payment Method Settings page in Shopfront (Menu > Setup > Payment Methods). Create a new Payment Method (can call it whatever you want) and set the Payment Method Type to Custom

When the Payment Method has finished creating, you'll need to press the Edit button next to it. You should be able to see the field for Gateway, in this field enter the gateway address from earlier. We would also suggest enabling Allow Cash Out to test when people enable that setting in the register. You may change any other setting to your liking, but they do not affect the integration.

Once you've finished customising your Payment Method, press Save.

Payment Method Flow

The typical flow for an integrated payment method is the following:

  • Add product to the sale
  • (Optional) Add a customer to the sale
  • Enter the finalise sale screen
  • (Optional) Specify the amount to pay
  • Select the payment method
  • The payment gateway opens
  • Data is sent to the gateway
  • Gateway processes payment
  • (Optional) Gateway prints receipt
  • Gateway returns results to the POS
  • POS closes gateway and proceeds with sale (based off result from gateway)

There is a second flow that needs to be accounted for, which is the cashout without sale flow:

  • Select cashout without sale
  • The payment gateway opens
  • The gateway determines if cashout without sale is allowed (returns error if not)
  • The gateway processes the cashout
  • (Optional) Gateway prints receipt
  • Gateway returns results to the POS
  • POS closes gateway and proceeds with cashout (based off result from gateway)

Events

These events allow you to interact with the POS to process the sale.

A normal event flow looks like (events are in bold):

  • POS: Open gateway,
  • Gateway: Load required any data and prepare the gateway,
  • Gateway: Request sale data from POS after gateway has loaded (REQUEST_DATA),
  • POS: Data about sale is sent to the gateway (DATA),
  • Gateway: Process the sale / cashout
  • POS: Ping the gateway to ensure that it is still correctly processing (PING),
  • Gateway: Reply that the gateway is still working (PONG),
  • Gateway: (optional) Print a receipt (e.g. merchant copy) (RECEIPT),
  • Gateway: Finished processing the sale / cashout, reply the result to the POS (FINISH),
  • POS: Close the gateway

A few other events can happen (such as an error occurring or the payment being cancelled).

The events are described below:

From Shopfront to Gateway

DATA

This sends the sale data to the gateway after being request (by the REQUEST_DATA event).

Data:

This is an object with the following fields:

Field Type Description
type "SALE" The type of request from Shopfront (always set to SALE at the moment)
sale Object The sale data, includes the products, customer and more
cashout ?Number The amount requested as cashout (always positive)
amount Number The amount to process for the sale (always positive)
reference String A reference for the payment for logging
refund Boolean Whether the payment is a refund or not

PING

This checks whether the gateway is still processing the sale and that it isn't stuck (and responds with the PONG event). If the gateway is unable to process the request (e.g. infinitely waiting for an external service) it should not respond to this.

Data:

This is a number that contains the ID of the ping (to be returned on the PONG event).

CANCEL

This occurs when the user cancels the payment in progress (by pressing the cancel button). It is expected that the gateway then cancels the current payment if possible.

Data:

This does not send any data.

From Gateway to Shopfront

REQUEST_DATA

This requests the sale data from Shopfront, it is expected that the gateways calls this once it is ready to begin processing the transaction.

Data:

No data is expected from this.

FINISH

This indicates that the payment has finished processing (whether it was successful or not). The gateway will close after this has been sent.

Data:

This is an object with the following fields:

Field Type Description
status String The status of the payment, one of "approved", "cancelled" or "declined"
amount Number The amount of money processed (excluding cashout) - this is typically the amount originally specified
cashout Number The cashout amount processed - this is typically the amount originally specified
subtype String? The subtype of the payment (e.g. Visa, Mastercard, etc) that was used. If not specified this will be "Not Implemented"
metaData Record<string, any> Any meta data you would like to store alongside the transaction

Note: You can specify the metaData fields name.display.pre and name.display.post (each dot is a nested object) to add additional information onto the receipts, sales history and sell screen

PONG

This should be called when the gateway receives a PING event and the gateway is not stuck processing (i.e. the gateway should still be functioning correctly).

Data:

This is a number that was originally provided by the PING event.

ERROR

You should send this message when your gateway has encountered an error that is unrelated to the payment (e.g. could not load a required script). This currently does not close the gateway when received, you'll still need to fire the FINISH event.

Data:

You can send any data to assist with handling the error. It is not processed by Shopfront and should be used internally.

RECEIPT

This event can be used in two ways, firstly to immediately print a receipt (e.g. to request a customer signature) and secondly to add data to the customer's receipt (e.g. a customer's copy).

Data:

This is an object with the following fields

Field Type Description
receiptText String The text to print on the receipt
print Boolean Whether the receipt should be printed now (separately from the customer's receipt)

Additional Features

In addition to being able to process payments, the Shopfront payment API supports the following additional features (you'll have to be approved by Shopfront before using them):

  • Settlement
  • Assisted Calculator (for closing the register)
  • Custom Features

Please contact the Shopfront API team to discuss the additional features before attempting to implement them.