Application Wireframe Document

This topic provides an example of the wireframe document you need to complete as part of your submission to list your application on the Square App Marketplace.

A wireframe document requests the following information about your application:

• A high-level summary of what your application does and what it will do with a seller's Square account data.

• A diagram (such as a UML, a swimlane, or another robust diagram) for each way a seller can access their Square account information through your application.

• A UML diagram of your OAuth flow that shows you have properly implemented OAuth and you are following the best practices for handling sensitive Square user data.

• API-specific questions in Partner Team-provided questionnaires.

Link to section

High-level summary

The summary can be a short paragraph that describes the intended market for your application and how the application should be used. An application called Dogfood POS might be summarized as follows:

“Dogfood POS is a point of sale management system for restaurants that serves canines of all kinds. We leverage Square's Terminal API to help restaurants take Card Present Swipe, Chip and PIN, and Contactless transactions. The application uses the Devices API to create device codes and the Terminal API to create and manage checkout sessions on the Square Terminal.”

Link to section

Diagram Square API calls

The following diagram is an example of how you might create a UML diagram for the Square API call flow in your application. You can provide cURL examples for the Square API request and a JSON object that represents the response that you will parse. If you are handling webhook events resulting from the call flow, be sure to note the events that you handle and the application component that is handling them.

In this wireframe example, Dogfood POS has a working business logic and data access layer. The UI layer is not complete so the developer mocked it using balsamiq. You can also capture application screens if your application prototype has a running UI. High-fidelity or low-fidelity screens are fine in your wireframe—Square needs to understand how your application uses the Square APIs and platform to provide the best feedback possible.

The Partner team uses the UML diagrams to verify the sequence of API calls that you make, how you are forming API requests, and whether you are using webhooks to make your application reactive to asynchronous events from Square.

This diagram captures only one of the Square API call flows that Dogfood POS makes. A complete wireframe would include the OAuth call flow and any other Terminal API calls as documented in the Square Terminal API Overview. Be sure to diagram all Square API calls and webhook events that your application uses.

Link to section

Commit to implementing OAuth

The Square Partner team provides you with a questionnaire to add to your wireframe document. The answers you provide in the questionnaire gauge the completeness of your OAuth implementation and its conformance to OAuth API Requirements.

REQUIREMENTS

OAuth questionnaire example

• What OAuth permissions are requested?

"DEVICE_CREDENTIAL_MANAGEMENT, MERCHANT_PROFILE_READ, PAYMENTS_READ, and PAYMENTS_WRITE."

• How does your refresh token logic work?

"We run a cron job every 7 days that refreshes all tokens in our database."

• How do you implement your OAuth state parameter?

"We generate a random and unique hex string that is validated on the client side via JavaScript cookie logic."

• How do you ensure that your access tokens are consistently valid?

"We maintain a cron job and in our settings page, we run health checks on load to make sure the access token is still valid. If it is not, we display an error message that suggests reconnecting with Square."

• How do you handle access tokens being revoked?

"We alert the seller before a payment and display a notification on the POS application."

Link to section

Integration-specific API questionnaire

The Square Partner team gives you a questionnaire for each Square API that you integrate. In the previous example, you would receive a questionnaire for your conformance to Terminal API requirements. The questionnaire asks questions in several categories related to the steps in completing a checkout using the Terminal API. The following questions and answers are examples from such a questionnaire:

Onboarding Terminal example

• How are Square locations chosen to register a particular Terminal?

"When setting up the POS application, we provide a location selector that the Square Terminal will connect to."

• How and when are device codes generated for a particular Terminal?

"We generate a device code when a user logs in to Dogfood POS, connects with Square via OAuth, and selects Connect a Square Terminal."

• How is successful or failed pairing presented to the seller?

"We leverage the device.code.updated webhook provided by Square to automatically update the Dogfood POS UI when a Terminal has been successfully paired or if the pairing process failed."

Terminal checkout status example

• Have you enabled tipping?

"We enable tipping using the device_options.tip_settings attribute in the Terminal Checkout object."

• Do you set the reference_id to manage complicated orders?

"We do use the reference_id to reconcile transactions made with the Terminal API with our own backend reporting."

• Do you set the note field to have the Partner Name + Order Number?

"We set the Checkout note field to “DogfoodPOS ####” to help sellers reconcile their Seller Dashboard transactions with the ones that they can see in the Dogfood POS."

• Are you adjusting the timeout deadline for any reason?

"We adjust the deadline to 1 minute using the deadline_duration attribute in the Terminal Checkout object."

• Do you subscribe to the terminal.checkout.created and terminal.checkout.updated webhooks?

"We subscribe to both webhook events."

• How do you update the checkout status on the application?

"We use the webhooks to determine what message to print on the Dogfood POS UI. When a checkout is created, our backend listens for the checkout and updates the Dogfood POS UI. When the checkout is updated, it automatically updates the message presented in the UI to reflect the current checkout status."

• How do you handle Seller Cancellation functionality?

"We provide sellers the ability to cancel a Terminal checkout that has not yet been presented on the Square Terminal Screen."

• How do you handle a Buyer Cancellation event?

"We use the terminal.checkout.updated webhook to listen to whether the buyer has canceled the checkout."

Payments and Refunds example

• Do you leverage the Payments API to maintain a permanent record?

"We do. We keep a permanent copy of the Payments API IDs associated with the transaction items in Dogfood POS."

• Do you leverage the Refunds API to manage refunds? If not, how do you process refunds?

"We do. When a seller leverages our refunds or issues a refund through Square, we use the Refunds API and the refunds webhooks to update that information in both Square and Dogfood POS."