UX guidelines for payment customizations
All apps should follow the general guidance provided by App Design Guidelines. This guide provides additional guidance for designing payment customizations with Shopify Functions.
Required pagesAnchor link to section titled "Required pages"
Payment customizations require the following kinds of pages:
- A template for the merchant to create the customization
- A customization detail page for the merchant to edit existing customizations
The merchant views the blank template page when they first create a customization:
The merchant views a customization detail page when they edit an existing customization. We recommend that Save buttons are enabled only when the merchant has made changes to the form:
Merchant navigationAnchor link to section titled "Merchant navigation"
Merchants can configure payment customizations in the Shopify admin under Settings > Payments > Payment method customizations.
When an app using a payment customization is installed, the merchant sees a button to add the customization, and is directed to an empty index page. From that index page, the merchant can open a modal with available templates. Your app's template page routes will appear in this list.
The template page has a breadcrumb button (the arrow
← next to the page title). This button must always go back to the page that the user came from.
For example, when the template page is reached from Settings in the Shopify admin, the button must return the user to the same Settings page. If you choose to link to your customization page from somewhere else, such as a page in your app, then the breadcrumb button must return the user to that page.
Error validationAnchor link to section titled "Error validation"
You'll get errors back from bad data passed to API calls, but validating the data client-side before firing off a network request makes for a faster UI experience.
If you choose to validate on the client, then take extra care with free-form entry, such as text fields. Run your validation check only after focus moves away from the field and there's at least one character in the field. This helps avoid marking the field with an error before users have committed a value.
You might choose not to validate client-side in some cases, such as when validation on a given field takes longer than 1000 ms and validation performance can’t be improved.
If you get any validation errors, then display them on the specific fields that contain the invalid data, including a message explaining what went wrong and how to fix it. Polaris form components have an error property that you can use for this purpose.
If there are multiple invalid fields, then provide an error banner at the top of the page, and focus the banner on submit. The banner should include a list of the fields with problems. Link each item in the banner to the corresponding field on the page, enabling the user to jump to that field.
If there is only a single field with an error, then move focus to that field instead.
Learn more about form validation.