# Payments / Introduction # 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) API We would suggest [creating a trial store](https://shopfront.com.au/signup) 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 | 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.