Build a redeemables payment extension

To build a redeemables payments extension you will need to create a new app, with a redeemables payments extension and Checkout UI extension correctly applied.

Create your new app using the Shopify CLI.

After creating your app, generate a Checkout UI extension and deploy your app to Shopify. This extension will be used to collect gift card details from buyers directly on checkout.

1. Use the Shopify CLI to scaffold a Checkout UI extension for your app.
2. Name your extension
3. Choose to work in TypeScript React.

1. After you generate the extension, deploy your app to Shopify Partners. This will allow you to link the Checkout UI extension with your payments app extension.
2. In Shopify Partners, click Apps.
3. Select your app.
4. Click Extensions. At this point, you should have the Checkout UI extension you created.
5. Click the name of your Checkout UI extension.

1. Follow this guide to create and release a new version of your app.

Your Shopify app becomes a payments app after you've created and configured your payments extension.

Redeemables describes a payment method that can be redeemed. Examples are gift cards, store credit, etc.

1. Run the following command to start generating your payment extension:

2. When prompted, choose your organization & create this as a new app

3. When prompted for "Type of extension", select "Payments App Extension > Redeemable" and name your extension

In this section, you will configure and deploy your application with the payments extension.

1. Disable embedding

   Shopify apps are embedded by default, but payments apps are an exception to this, because they don't need to render anything in Shopify admin. In shopify.app.toml, update the embedded and set it to false.

2. Configure basic app settings

   In shopify.app.toml, update the name and client_id to match the information about the app that you manually created. You can find the client_id in the Client credentials section of you app's overview page in the Partner Dashboard.

3. Push the configuration changes to your app and start your server

   In a terminal, run the following commands to push the configuration changes to your app:

   1. Install the packages required to run the payments app:
   1. Deploy your app to update the config, which is defined in shopify.app.toml:

4. Start your development server

   To run the app locally, start your development server:

   1. You might be prompted to log in to your Partner account.

      In your terminal, select your development store. You can use the generated URL to test your payments app by using it in your payments app configuration. If you want a consistent tunnel URL, then you can use the --tunnel-url flag with your own tunnel when starting your server.

   2. Press p to open the app in your browser. This brings you to your development store's admin, where you can install your payments app.

Configuration of a redeemables payments extension is similar to a Offsite payments extension.

Your payments extension configures the following fields:

The UI extension generated in Create a Checkout UI extension will determine what fields, validation, and form submission behavior is presented to buyers during checkout.

This is where you would identify the checkout extension you built prior to creating your payment extension to tie them into one another.

The fields you are looking to accept from your UI extensions so the payment method can validate the correct data is sent from the front end.

The above field definitions would be defined for something that looks like this:

Your UI extension must extension target the purchase.checkout.gift-card.render extension point. This will ensure your UI renders in the correct location for gift card payments and has access to the applyRedeemableChange API method to apply a gift card to a checkout.

applyRedeemableChange is a new API method which can be pulled from the useApplyRedeemableChange hook on @shopify/ui-extensions-react/checkout.

This method applies a redeemable (i.e. gift card) to the checkout your extension is rendered on. This method triggers a Fetch Balance request explained later.

The attributes provided to this method should mirror the definitions in the UI Extension Field Definitions configuration on your payments app extension. If the attributes provided don’t match your field definitions, the call will fail and an error will be returned.

Example applyRedeemableChange payload:

Example applyRedeemableChange usage:

When applyRedeemableChange successfully completes, the following will be returned:

A number of errors may rise when applyRedeemableChange is run and fails. The output would look like:

message is human-readable, and can be any of:

• Could not apply redeemable
• Access denied: the extension does not have the required approval scopes
• Invalid RedeemableChange type
• Could not apply redeemable change: the buyer journey is completed

These messages are for debugging and should not be displayed to the buyer. Shopify owns displaying errors to buyers within checkout.

Refer to the Sample Checkout UI extension for an example implementation of what your gift card form will look like.

While implementing the UI extension you may want to consider the following:

• Localization - The labels and visible text displayed to the buyer should be localized. We provide the useTranslate hook through the StandardAPI for this purpose.
• Field validation - Before making the applyRedeemableChange request, it is advisable to validate the gift card input fields. To present field validation messages, you can utilize the error property provided by the TextField component.
• Loading, Error, and Success states - When the buyer submits a gift card, your UI extension needs to handle loading, error, and success states. To accomplish this:
  • Loading state: Display a loading spinner in the “Apply” button while the request is pending. To achieve this, you can use the Spinner component.
  • Success state: Reset the form fields to their initial state after successfully applying the gift card to the checkout.
  • Error state: Do not reset the form fields in case of an error. Instead, you may want to indicate which fields need to be corrected by utilizing field validation errors.
• Responsive UI - Use StyleHelper to make your UI extension responsive to different viewport sizes, focus states, and hover states.

Payments apps for gift cards are implemented very similarly to the existing offsite payments apps. The key difference is that, for gift cards, payments apps have an operation that occurs prior to a checkout completing - fetching the balance of a gift card.

The first step in a gift card payment is to retrieve the balance, so that it can be applied to a checkout. In order to do so, we require that you set up a Balance URL in the payments app extension. Shopify will make a request to that URL to retrieve the balance of a gift card during checkout.

Example request payload:

If the balance can be successfully fetched, send a HTTP 2xx response to the above request with a JSON body in the following format, including the balance:

The provided value for currency can be any ISO 4217 currency code (i.e. USD, CAD).

In the event a balance fetch fails, there are a number of predefined codes you can respond with to surface an error to buyers.

Example failure response (HTTP 2xx):

1. The buyer enters their gift card details into the UI Extension.
2. The UI extension, with the gift card details, calls applyRedeemableChange, available through @shopify/ui-extensions-react/checkout.
3. Shopify will call the payments app’s endpoint located at their configured Balance URL, with a request to fetch the balance of the provided gift card.
4. The payments app returns the balance for the gift card.
5. Shopify applies the gift card to the buyer’s checkout.
6. The buyer is shown that the gift card has been applied to their checkout.

Payments with payments apps are processed asynchronously. When the buyer completes their checkout, a request will be sent from Shopify to the Payment session URL defined in Configure your payments app extension, with the checkout and payment details. The Payments app should respond with HTTP 2xx to indicate that the payment session was started, and should begin processing the gift card payment at this point.

Example request body:

Details on each attribute can be found here.

The payment method data object in the payment session request body is defined by the aforementioned UI Extension Field Definitions configuration in your app extension, just like for Fetch Balance.

If the request fails, then it's retried several times. If the request still fails, then the customer needs to retry their payment through Shopify checkout.

If there's an error on the payments app's side, then don't respond with an HTTP 2xx. Use an appropriate error status code instead.

Once the payments app has responded to the initial start payment session request, it should begin processing the payment. Since this is an asynchronous process, the payments app will be performing the next step independently, through the paymentSessionResolve mutation on the Payments Apps GraphQL API. This mutation will resolve the payment session, indicating that the payment was successful.

Example GraphQL mutation:

With this input:

Example JSON response:

After this, the payment will be marked as resolved in Shopify.

If a payment was unsuccessful for any reason, the payments app must use the paymentSessionReject mutation.

Example GraphQL mutation:

With this input:

Example JSON response:

There are some defined errors that you can reject a paymentSession with.

Refunds operate the same as they do with regular payments. Documentation can be found here.

Authorizations, captures, and voids allow merchants to use your payment app to initiate separate transactions to authorization and capture payments. These will operate the same as they do with regular payment apps. More context about authorizations can be found here.

Merchants control whether or not they use "sale or "authorization" payment transactions by changing their Payment capture method payment setting to "Manual" or "Automatically when order is fulfilled".

For details on how to implement and respond to capture and void session requests see:

Use the following example for implementing your gift card form:

Congratulations! You set up a redeemable payments extension.