Build an offsite payments extension with Shopify CLI

import CliVersionRequirements from 'app/views/partials/payments/cli-version-requirements.mdx' <Repo framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/main-js" /> <Picker name="framework"> <PickerOption name="remix" /> </Picker> <Overview> <CliVersionRequirements /> Offsite payments extension redirect customers to an app-hosted website to complete the payment process with the payment methods supported by the payments extension. When a store enables your offsite payments extension and a customer selects your payment method, the customer is redirected to a webpage specified by your payments extension where you can collect the customer's payment information, confirm the payment, and then redirect the customer back to Shopify to finalize the order. This tutorial provides step-by-step instructions on how to create and test an offsite payments app and payments extension. This tutorial is exclusively for testing and should be replaced with your own payment processing logic in a production extension. To make a production-ready extension, you need to make several changes to the template code to include your own payment processing capabilities. This tutorial highlights the areas you need to edit or extend with your own functionality. ## What you'll learn In this tutorial, you'll learn how to do the following tasks: - Set up your app - Create an offsite payments extension - Explore the payment, refund, void, reject and capture session flows, and how to implement them yourself - Submit your Payments extension for review </Overview> <Requirements> <Requirement href="https://www.shopify.com/partners" label="Create a Partner account" /> <Requirement href="/docs/apps/tools/development-stores" label="Create a development store"> The development store should be pre-populated with test data. </Requirement> <Requirement href="/docs/apps/build/payments/payments-extension-review#payments-partner-application-review" label="Become a Payments Partner"> Apply and receive approval to become a Payments Partner. </Requirement> </Requirements> <StepSection> <Step> ## Scaffold an app Scaffold a new payments app using [Shopify CLI](/docs/api/shopify-cli). <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/extensions-templates/blob/main/payments-app-extension-offsite/shopify.extension.toml.liquid" /> ### Scaffold an app using Shopify CLI 1. Run the following command to start creating your app: <Codeblock terminal> ```bash title="npm" npm init @shopify/app@latest ``` </Codeblock> 1. When prompted, enter the name of your app. 1. When prompted for the approach, select the option to add your first extension <Codeblock terminal> ```bash title="npm" Start with Remix(recommended) > Start by adding your first extension ``` </Codeblock> </Substep> </Step> <Step> ## Create a payments extension Your Shopify app becomes a payments app after you've created and configured your payments extension. <Substep> 1. Run the following command to start generating your payment extension: <Codeblock terminal> ```bash title="pnpm" pnpm shopify app generate extension ``` </Codeblock> 1. When prompted, choose your organization & create this as a new app 1. When prompted for "Type of extension", select "Payments App Extension > Offsite" and name your extension </Substep> </Step> <Step> ## Configure your payments extension When you [generate an app extension](/docs/api/shopify-cli/app/app-generate-extension), a TOML configuration file named `shopify.extension.toml` is automatically generated in your app's extension directory. You can find your extension configuration in `extensions/<extension-name>/shopify.extensions.toml`. <Substep> | Property name | Description | | ------------- | ---------------------------------------------------------------------------------- | | `payment_session_url` Required | The URL that receives payment and order details from the checkout. | | `refund_session_url` Required | The URL that refund session requests are sent to. | | `capture_session_url` Required | The URL that capture session requests are sent to. This is only used if your payments app supports merchant manual capture. | | `void_session_url` Required | The URL that void session requests are sent to. This is only used if your payments app supports merchant manual capture or void payments. | | `supported_countries` Required | The countries where your payments app is available. Refer to the [list of ISO 3166 (alpha-2) country codes](https://www.iso.org/iso-3166-country-codes.html) where your app is available for installation by merchants. | | `supports_3ds` Required | 3-D Secure support is mandated in some instances. For example, you must enable the 3-D Secure field if you plan to support payments in countries which have mandated 3-D Secure. | | `supported_payment_methods` Required | The payment methods (for example, Visa) that are available with your payments app. [Learn more](https://github.com/activemerchant/payment_icons/blob/master/db/payment_icons.yml). | | `supports_installments` Required | Enables installments | | `supports_deferred_payments` Required | Enables deferred payments | | `merchant_label` Optional | The name for your payment provider extension. This name is displayed to merchants in the Shopify admin when they search for payment methods to add to their store. Limited to 50 characters. | | `buyer_label` Optional | The name of the method. Your checkout name can be the same as your merchant admin name or it can be customized for customers. This name is displayed with the payment methods that you support in the customer checkout. After a checkout name has been set, translations should be provided for localization. | | `test_mode_available` Optional | Enables merchants using your payments app to test their setup by simulating transactions. To test your app on a development store, your payment provider in the Shopify admin must be set to test mode. | | `api_version` Optional | The Payments Apps GraphQL API version used by the payment provider app to receive requests from Shopify. You must use the same API version for sending GraphQL requests. You must not use unstable in production. API versions are updated in accordance with Shopify's general [API versioning timelines](/docs/api/usage/versioning). | | `multiple_capture` Optional, Closed Beta | Enables merchants using your payment provider app to partially capture an authorized payment multiple times up to the full authorization amount. This is used only if your payments app supports merchant manual capture. | </Substep> </Step> <Step> ## Set up your payments app <Substep> ### 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. </Substep> <Substep> ### 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 your app's overview page in the [Partner Dashboard](https://partners.shopify.com/apps/). </Substep> <Substep> ### 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: <Codeblock terminal> ```bash title="npm" npm install ``` ```bash title="Yarn" yarn install ``` ```bash title="pnpm" pnpm install ``` </Codeblock> 1. Deploy your app to update the config, which is defined in `shopify.app.toml`: <Codeblock terminal> ```bash shopify app deploy ``` </Codeblock> </Substep> <Substep> ### Start your development server To run the app locally, start your development server: 1. <Codeblock terminal> ```bash shopify app dev ``` </Codeblock> <Notice type="info"> You might be prompted to log in to your Partner account. </Notice> 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](#configure-your-payments-app-extension). If you want a consistent tunnel URL, then you can use the `--tunnel-url` flag with your own tunnel when starting your server. 1. 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. </Substep> </Step> <Step> ## Explore payment sessions In this step, you'll explore the flows that an app needs to implement to process a payment. In the app template, the endpoint that handles start payment session requests is predefined, and will automatically resolve or reject the payment by calling the Payments Apps API, based on the customer's name. Note that this behavior is exclusively for testing and should be replaced with your own payment processing logic in a production app. <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/routes/app.payment_session.jsx" tag="build-offsite-payments-app.payment-session" /> ### Start the payment session When a customer selects your payment provider, Shopify sends an HTTP `POST` request the payment session URL for the app. The request contains information about the customer and the order. To learn more about the request body and header, refer to the [Offsite payment request reference](/apps/payments/request-reference#offsite-payment-request-reference). When the `POST` request is received, the payments app returns an HTTP `2xx` response with a `redirect_url` in the body. The `redirect_url` should be less than `8192 bytes` in length. This response and parameter are required for the payment session creation to be successful. 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 return an appropriate error status code instead. --- You configure the payment session URL for your app as part of the [app extension configuration](#configure-your-payments-extension). </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/payments-apps.graphql.js" tag="build-offsite-payments-app.graphql.resolve" /> ### Resolve a payment The payments app uses the `paymentSessionResolve` mutation after the customer has successfully gone through the payment process to complete the payment. The `id` argument corresponds to the global identifier (`gid`) of the payment. --- In the referenced code, `this.resolveMutation` corresponds to the `paymentSessionResolve` mutation. <Resources> [`paymentSessionResolve`](/docs/api/payments-apps/latest/mutations/paymentSessionResolve) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/payments-apps.graphql.js" tag="build-offsite-payments-app.graphql.reject" /> ### Reject a payment The payments app should reject a payment if the customer can't complete a payment with the provider. The rejected payment tells Shopify that the checkout process will be halted. For example, if you don't want to process a high-risk payment, then you can reject the payment using the `paymentSessionReject` mutation. Rejecting a payment is final. You can't call other actions on a payment after it has been rejected. The payments app should retry a failed user attempt and complete the payment before calling `paymentSessionReject`. For example, if any of the following conditions are met, then you don't need to reject the payment: - The user doesn't interact with your payments app - The user cancels the payment - The user needs to retry the payment because of specific errors, such as the user entering the wrong CVV --- In the referenced code, `this.rejectMutation` corresponds to the `paymentSessionReject` mutation. <Resources> [paymentSessionReject](/docs/api/payments-apps/latest/mutations/paymentSessionReject) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/routes/app.payment_simulator.%24paymentId.jsx" tag="build-offsite-payments-app.payment-cancel" /> ### Cancel the payment If a customer wants to cancel a payment on your provider page, then they are redirected to the merchant's website or store by using the `cancel_url`. The `cancel_url` is sent to your payments app in the payment request request-body that was sent from Shopify. Don't use the `paymentSessionReject` mutation to cancel the payment, otherwise the customer will be unable to pay again with your provider. </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/payments-apps.graphql.js" tag="build-offsite-payments-app.graphql.pending" /> ### Mark the payment as pending You can mark a payment as pending if it's awaiting asynchronous action by the customer, the merchant, the payment Partner, or a payment network. Not all payments can be processed and finalized quickly. Some payments can take several days to complete. Pending a payment indicates to the customer that you have started processing the payment, but require more time to complete the payment. If an order is in pending payment status, then merchants might be restricted from editing, canceling, or manually capturing payment for the order until the payment is finalized. For more information, refer to the [pending payments documentation](https://help.shopify.com/en/manual/orders/manage-orders/alt_payments_pending) on the Shopify Help Center. --- In the referenced code, `this.pendingMutation` corresponds to the `paymentSessionPending` mutation. <Resources> [`paymentSessionPending`](/docs/api/payments-apps/latest/mutations/paymentSessionPending) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/routes/app.payment_simulator.%24paymentId.jsx" tag="build-offsite-payments-app.payment-simulator.process" /> ### Triggering resolve, reject, or pending for a payment in the template In the app template, after a start payment session request has been received by the app, the payment is automatically resolved or rejected based on the customer's name. If the customer's first name is `reject`, then the payment is rejected. If the customer's first name is `pending`, then the payment is marked as pending. Otherwise, the payment is resolved. </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/routes/app.payment_simulator.%24paymentId.jsx" tag="build-offsite-payments-app.next-action" /> ### Process next action Upon receiving the response from either the `paymentSessionResolve`, `paymentSessionReject`, or `paymentSessionPending` mutations, the next action that the payments app performs is specified under `nextAction`. The `nextAction will either be `nil` or contain two fields. In the case where it is `nil`, no next action is expected of the payments app. Otherwise, the fields are as follows: - `action`: A `PaymentSessionNextActionAction` enum that specifies the type of the action the app must perform. - `context`: A union type requiring inline fragments to access data on the underlying type. Takes a type of `PaymentSessionActionsRedirect`. <Resources> [nextAction](/docs/api/payments-apps/latest/objects/PaymentSessionNextAction) [PaymentSessionNextActionAction](/docs/api/payments-apps/latest/enums/PaymentSessionNextActionAction) [PaymentSessionActionsRedirect](/docs/api/payments-apps/latest/objects/PaymentSessionActionsRedirect) </Resources> </Substep> </Step> <Step> ## Explore refund sessions In this step, you'll explore the flows that an app needs to implement to process a refund. In the app template, the endpoint that handles start refund session requests is predefined to store sessions for an asynchronous resolution. The refund flow begins with an HTTP POST request sent from Shopify to the payments app's refund session URL provided during app extension configuration. To learn more about the request body and header, refer to the [Refund request reference](/apps/payments/request-reference#refund-request-reference). <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/routes/app.refund_session.jsx" tag="build-offsite-payments-app.refund-session" /> ### Start the refund session The refund flow begins with an HTTP `POST` request sent from Shopify to the payments app's refund session URL. Shopify must receive an HTTP `201` (Created) response for the refund session creation to be successful. If the request fails, then it's retried several times. If the request still fails, then the user needs to manually retry the refund in the Shopify admin. --- You configure the refund session URL for your app as part of the [app extension configuration](#configure-your-payments-extension). </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/payments-apps.graphql.js" tag="build-offsite-payments-app.graphql.resolve" /> ### Resolve a refund After the app successfully processed the refund request, it is resolved by using the `refundSessionResolve` mutation. The `id` argument corresponds to the `gid` of the refund. --- In the referenced code, `this.resolveMutation` corresponds to the `refundSessionResolve` mutation. <Resources> [`refundSessionResolve`](/docs/api/payments-apps/latest/mutations/refundSessionResolve) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/payments-apps.graphql.js" tag="build-offsite-payments-app.graphql.reject" /> ### Reject a refund If the app can't process a refund, then it rejects it. You should only reject a refund in the case of final and irrecoverable errors. Otherwise, you can re-attempt to process the refund. The refund is rejected using the `refundSessionReject` mutation. As part of the rejection, a reason why the refund was rejected must be included as part of `RefundSessionRejectionReasonInput`. The `RefundSessionRejectionReasonInput.code` is a `RefundSessionStatusReasonRejectionCode`, which is an enum of standardized error codes. The `RefundSessionRejectionReasonInput.merchantMessage` argument is a localized error message presented to the merchant explaining why the refund was rejected. --- In the referenced code, `this.rejectMutation` corresponds to the `refundSessionReject` mutation. <Resources> [`refundSessionReject`](/docs/api/payments-apps/latest/mutations/refundSessionReject) [`RefundSessionRejectionReasonInput`](/docs/api/payments-apps/latest/input-objects/RefundSessionRejectionReasonInput) [`RefundSessionStatusReasonRejectionCode`](/docs/api/payments-apps/latest/enums/RefundSessionStatusReasonRejectionCode) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/routes/app.dashboard_simulator.%24paymentId.jsx" tag="build-offsite-payments-app.dashboard-simulator.process-session" /> ### Triggering resolve or reject for a refund in the template In the app template, the simulator built into the dashboard handles the resolution or rejection of all post-payment sessions, including refunds, asynchronously. This means that after a refund is created in a store's Shopify admin, it must be manually completed from the app template's dashboard. In a production-ready app, your app would process the refund itself once it receives the start refund session request. </Substep> </Step> <Step> ## Explore capture sessions (optional) A capture describes the process of how merchants capture funds for an authorized payment. A capture is the next step of the payment flow, and occurs after an authorized payment is finalized. Finalized payments have `kind` set to `authorization`. The app template is setup to resolve or reject when Shopify sends a capture request to a payments app after a merchant tries to capture the funds on an authorized transaction. <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/routes/app.capture_session.jsx" tag="build-offsite-payments-app.capture-session" /> ### Start the capture session A capture can only be performed when the payment initiated by Shopify has a `kind` property with a value of authorization. With an `authorization`, the app places a hold on funds and then reply to Shopify's capture request. The `captureSessionResolve` or `captureSessionReject` mutation is used to accept or reject the capture of funds respectively. The capture flow begins with an HTTP `POST` request sent from Shopify to the payments app's `capture session URL`. --- You configure the capture session URL for your app as part of the [app extension configuration](#configure-your-payments-app-extension). Shopify sends a capture request to the payments app after a merchant tries to capture the funds on an authorized transaction. When this occurs, the app template is set up to store a capture session. These sessions can then be resolved through the simulator for testing. In a production-ready app, this is when your app would process the capture request. <Resources> [captureSessionResolve](/docs/api/payments-apps/latest/mutations/captureSessionResolve [captureSessionReject](/docs/api/payments-apps/latest/mutations/captureSessionReject) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/payments-apps.schema.js" tag="build-offsite-payments-app.schema.capture-resolve" /> ### Resolve a capture session After the app successfully processed the capture request, it is resolved by using the `captureSessionResolve` mutation. --- In the referenced code, `this.resolveMutation` corresponds to the `captureSessionResolve` mutation. <Resources> [`captureSessionResolve`](/docs/api/payments-apps/latest/mutations/captureSessionResolve) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/payments-apps.schema.js" tag="build-offsite-payments-app.schema.capture-reject" /> ### Reject a capture If you don't want to process a capture request, then you should reject it. You might want to reject a capture if authorization has expired or if you suspect that the request is fraudulent or high risk. You should only reject a capture in the case of final and irrecoverable errors. Otherwise, you should re-attempt to resolve the capture. The app rejects a capture using the `captureSessionReject` mutation. As part of the rejection, you need to include a reason why the capture was rejected as part of `CaptureSessionRejectionReasonInput`. The `CaptureSessionRejectionReasonInput.code` is a `CaptureSessionStatusReasonRejectionCode`, which is an enum of standardized error codes. The `CaptureSessionRejectionReasonInput.merchantMessage` argument is a localized error message presented to the merchant explaining why the capture was rejected. --- <Resources> [captureSessionReject](/docs/api/payments-apps/latest/mutations/captureSessionReject) [CaptureSessionRejectionReasonInput](/docs/api/payments-apps/latest/input-objects/CaptureSessionRejectionReasonInput) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/routes/app.dashboard_simulator.%24paymentId.jsx" tag="build-offsite-payments-app.dashboard-simulator.process-session" /> ### Triggering resolve or reject for a capture in the template In the app template, the simulator built into the dashboard (`/app/dashboard`) handles the resolution or rejection of all post-payment sessions, including captures, asynchronously. This means that after a capture is created in a store's Shopify admin, it must be manually completed from the app template's dashboard. In a production-ready app, your app would process the capture itself after it receives the start capture session request. </Substep> </Step> <Step> ## Explore void sessions (optional) A void describes the process of how merchants void funds for an authorized payment. A void is the next step of the payment flow, and occurs after an authorized payment is finalized. Finalized payments have `kind` set to `authorization`. <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/routes/app.void_session.jsx" tag="build-offsite-payments-app.void-session" /> ### Start the void session A void can only be performed when the payment initiated by Shopify has a `kind` property with a value of `authorization`. With an authorization, you place a hold on funds and then reply to Shopify's void request with the `voidSessionResolve` or `voidSessionReject` mutation to accept or reject the voiding of funds respectively. The void flow begins with an HTTP `POST` request sent from Shopify to the payments app's `void session URL`. --- You configure the void session URL for your app as part of the [app extension configuration](#configure-your-payments-app-extension). The app template stores the void session when Shopify sends a void request to a payments app after a merchant tries to cancel the order for an authorized transaction. These sessions can then be resolved through the simulator for testing. In a production-ready app, this is when your app would process the void request. <Resources> [voidSessionResolve](/docs/api/payments-apps/latest/mutations/voidSessionResolve) [voidSessionReject](/docs/api/payments-apps/latest/mutations/voidSessionReject) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/payments-apps.schema.js" tag="build-offsite-payments-app.schema.void-resolve" /> ### Resolve a void session After the app successfully processed the void request, it is resolved by using the `voidSessionResolve` mutation. --- <Resources> [voidSessionResolve](/docs/api/payments-apps/latest/mutations/voidSessionResolve) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/payments-apps.schema.js" tag="build-offsite-payments-app.schema.void-reject" /> ### Reject a void If you can't process a void request, then you should reject it. You should only reject a void in the case of final and irrecoverable errors. Otherwise, you can re-attempt to resolve the void. You can reject a void using the `voidSessionReject` mutation. As part of the rejection, you need to include a reason why the void was rejected as part of `VoidSessionRejectionReasonInput`. The `VoidSessionRejectionReasonInput.code` is a `VoidSessionStatusReasonRejectionCode`, which is an enum of standardized error codes. The `VoidSessionRejectionReasonInput.merchantMessage` argument is a localized error message presented to the merchant explaining why the void was rejected. --- <Resources> [`voidSessionReject`](/docs/api/payments-apps/latest/mutations/voidSessionReject) [`VoidSessionRejectionReasonInput`](/docs/api/payments-apps/latest/input-objects/VoidSessionRejectionReasonInput) [`VoidSessionStatusReasonRejectionCode`](/docs/api/payments-apps/latest/enums/VoidSessionStatusReasonRejectionCode) </Resources> </Substep> <Substep> <CodeRef framework="remix" href="https://github.com/Shopify/example-app--payments-app-template--remix/blob/docs/app/routes/app.dashboard_simulator.%24paymentId.jsx" tag="build-offsite-payments-app.dashboard-simulator.process-session" /> ### Triggering resolve or reject for a void in the template In the app template, the simulator built into the dashboard handles the resolution or rejection of all post-payment sessions, including voids, asynchronously. This means that after a void is created in a store's Shopify admin, it must be manually completed from the app template's dashboard. In a production-ready app, your app would process the void itself after it receives the start void session request. </Substep> </Step> <Step> ## Explore confirm sessions (Closed Beta) <Notice type="beta"> Confirmation for offsite payments is currently in Closed Beta. Shopify is adding the ability for third-party payment providers offering offsite payments to confirm that inventory is still available and that all discount codes and business logic are still valid, before completing a payment. This feature is only available to merchants with access to one page checkout and/or who have upgraded to checkout extensibility. </Notice> If your app supports Inventory Confirmation you must use the [`paymentSessionConfirm`](/docs/api/payments-apps/latest/mutations/paymentSessionConfirm) mutation to confirm with Shopify whether to proceed with the payment request, according to Shopify's business logic. We enforce payment apps supporting this feature to have a `Refund session URL` in their [payment extension configuration](/docs/apps/build/payments#build-options). This is required for the situation when 3 minutes elapse between confirmation and resolution. Once this length of time has passed we have to re-run the confirmation process which could fail, at which point Shopify will issue a refund request on the payment. If you support capture/void we will look at the payment to decide upon if we should call void instead of refund. <Substep> ### Confirm a payment You must use the `paymentSessionConfirm` mutation to confirm with Shopify whether to proceed with the payment request, according to Shopify's business logic. For example, Shopify checks that inventory is still available and that discount codes are still valid. Call this mutation when the customer has completed the offsite steps of the payment, and you are ready to process the payment. The `id` argument corresponds to the global identifier (`gid`) of the payment. Shopify will return a `Null` `nextAction` in the response, not expecting the payments app to redirect the buyer back to Shopify at this point. Your app should indicate activity to the user and must wait for Shopify to confirm whether the payment request can proceed. <Resources> [`paymentSessionConfirm`](/docs/api/payments-apps/latest/mutations/paymentSessionConfirm) [`nextAction`](/docs/api/payments-apps/latest/objects/PaymentSessionNextAction) </Resources> </Substep> <Substep> ### Process a confirm session When Shopify determines that the payment request can proceed, Shopify sends a POST [request](/docs/apps/build/payments/request-reference#confirm-a-payment-3-d-secure-and-inventory-confirmation) to the confirm session URL of the [offsite payments app extension](/docs/apps/build/payments#build-options), delivering the confirmation result: Shopify must receive an HTTP `2xx` response for the payment session confirmation to be successful. 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. </Substep> <Substep> ### Complete a payment After the confirmation callback has been received by your application, we expect you to either [resolve](/docs/apps/build/payments/offsite/use-the-cli#resolve-a-payment), [reject](/docs/apps/build/payments/offsite/use-the-cli#reject-a-payment) or [pend](/docs/apps/build/payments/offsite/use-the-cli#mark-the-payment-as-pending) the payment. When Shopify indicates that the payment request can't proceed, the payments app must invoke the `paymentSessionReject` mutation using the `CONFIRMATION_REJECTED` reason code. Shopify expects the payment to be resolved/rejected within 3 minutes of the successful confirmation callback being sent to the payments app. If the call takes longer than 3 minutes we will attempt to re-run the confirmation process on resolve. As we no longer guarantee the confirmation result, after resolving the payment Shopify may issue a refund/void request. <Resources> [`paymentSessionResolve`](/docs/api/payments-apps/latest/mutations/paymentSessionResolve) [`paymentSessionPending`](/docs/api/payments-apps/latest/mutations/paymentSessionPending) [`paymentSessionReject`](/docs/api/payments-apps/latest/mutations/paymentSessionReject) [`CONFIRMATION_REJECTED`](/docs/api/payments-apps/latest/enums/PaymentSessionStateRejectedReason#value-confirmationrejected-confirmationrejected) </Resources> </Substep> </Step> <Step> ## Test your payments extension locally Before submitting your extension for review, you should test that your various endpoints work as expected locally. <Substep> ### Submit a request to your local server With the dev server you started [previously](#start-your-development-server), go through the relevant requests from our [reference](/docs/apps/build/payments/request-reference), and submit a request to your app with `cURL` or an API platform like Postman or Insomnia. </Substep> <Substep> ### Test a negative confirmation result with the confirm sessions (Closed Beta) To test a negative confirmation result (`confirmation_result=false`), do the following: - Configure a product to [track inventory](https://help.shopify.com/manual/products/inventory/managing-inventory-quantities/track_inventory) - Initiate a checkout with this product - Proceed with a payment - When the consumer is redirected offsite from Shopify, reset the inventory to 0 - Proceed with the payment The `paymentSessionConfirm` mutation should be called by your payments app and Shopify should then send a negative confirmation result (`confirmation_result=false`) to the app's `confirm session URL`. </Substep> </Step> <Step> ## Submit your payments extension for review After you've finished your draft, you can submit your payments extension for review. You can use this same process to submit new versions of your payments extension. Any changes that are made after publishing need to be approved by Shopify as a new version of the payments extension. <Substep> #### Deploy and release your extension To get your app ready for review, create and release an app version. 1. Navigate to your app directory. 2. Run the following command. Optionally, you can provide a name or message for the version using the `--version` and `--message` flags. <Codeblock terminal> ```bash shopify app deploy ``` </Codeblock> --- An app version created using Shopify CLI contains the following: - The app configuration from the local [configuration file](/docs/apps/build/app-configuration). If the `include_config_on_deploy` [flag](/docs/apps/build/app-configuration#build) is not set or `false`, the configuration from the active app version will be used instead. - The local version of the app's CLI-managed extensions. If you have an extension in your deployed app, but the extension code doesn't exist locally, then the extension isn't included in your app version. - The latest drafts of dashboard-managed extensions. Releasing an app version replaces the current active version that's served to stores with your app installed. It might take several minutes for app users to be upgraded to the new version. <Notice type="tip"> If you want to create a version, but want to avoid releasing it to users, then run the `deploy` command with a `--no-release` flag. You can release the unreleased app version using Shopify CLI's [`release`](/docs/api/shopify-cli/app/app-release) command, or through the Partner Dashboard. </Notice> </Substep> <Substep> ### Submit the app version for review Payments apps are [reviewed by Shopify](/docs/apps/build/payments/payments-extension-review) to ensure that they provide great merchant experience. Follow these steps to submit your app version for review: 1. From the Partner Dashboard, go to [**Apps**](https://partners.shopify.com/current/apps). 1. Select your app from the list. 1. Click **Versions**. 1. Select the version that you want to release. 1. Click **Submit for review**. </Substep> <Substep> ### Release your app version After Shopify has reviewed and approved the app version you can release it to merchants. 1. From the Partner Dashboard, go to [**Apps**](https://partners.shopify.com/current/apps). 1. Click **Release** to release the new app version to users. </Substep> </Step> <Step> ## Test your payments app with a Shop Preview your app to make sure that it works as expected with Shopify. <Notice type="info"> The testing steps outlined in this section are specific to apps built with the template. The template provides a basic UI that lets you test the payment flows, but your app might have a UI stored outside of the admin. </Notice> <Substep> ### Start your server If you're using a permanent tunnel with your app extension, you can use the Shopify CLI `dev` command to build your app and preview it on your development store. Otherwise, deploy your app to your server, and move to the next step. 1. In a terminal, navigate to your app directory. 1. Either start or restart your server to build and preview your app: <Codeblock terminal> ```bash shopify app dev --tunnel-url <tunnel> ``` </Codeblock> 1. Press `p` to open the developer console. 1. In the developer console page, click on the preview link for the app. </Substep> <Substep> ### Install and test the payments app Follow these steps to test the payments app flows: 1. From the app splash page, enter an account name. 2. Select **Ready** > **Unstable** and click **Submit**. 3. In the banner, click **Return to Shopify**. 5. Enable test mode. 5. Click **Activate**. 6. You can select `Resolve` to complete the payment, or `Reject` to cancel and go back. </Substep> <Substep> ### Set up your payments app to accept test payments Onboard your app onto your development store. 1. In the Shopify admin for your development store, go to **Settings** > [**Apps and sales channels**](https://admin.shopify.com/admin/settings/apps). 1. Select your payments app, then click **Open app**. The app home opens in a new window. 1. This step is applicable only to the template, if you've implemented the app yourself, complete your onboarding steps, and skip to the next step. From the app home, enter an account name, select **Ready?** and your `Payments Apps API` **API Version**, and then click **Submit**. In the banner, click **Return to Shopify**. You'll return to admin, where you can review the app's details prior to activation. <Troubleshooting> ##### An error ocurred while onboarding your app Your app extension may not be set up properly. Ensure the URLs provided are accurate, and that the app extension is released. After this, you might have to uninstall and reinstall your payments app to successfully onboard. You can uninstall from your app's admin under **Settings** > [**Apps and sales channels**](https://admin.shopify.com/admin/settings/apps), and reinstall from your app's page in the Partner dashboard, under **Test your app**. </Troubleshooting> 1. Enable test mode. 1. Click `Activate`. Now that your app is installed, you can test payments, refunds, captures, voids, and 3-D Secure, if enabled. --- <Resources> [`Payments Apps API`](/docs/api/payments-apps) </Resources> </Substep> <Substep> ### Test payments Make a payment, and create an order. 1. In your development store, add a product to your cart, and then begin a checkout. 1. Complete the checkout as usual, until the **Payment** section. At this point, your payments app should be available under the **Payment** section. 1. Enter some test payments details, and then select **Pay now**. Shopify sends a request to the `payment session URL` specified in your [app extension configuration](#configure-your-payments-apps-extension). Your app should then begin, and complete processing the payment. 1. Verify the payment is complete by finding the order under [**Orders**](https://shopify.com/admin/orders) in your shop's admin. </Substep> <Substep> ### Test refunds Make a refund on an order. 1. In the Shopify admin for your development store, go to [**Orders**](https://shopify.com/admin/orders). Select an order with a completed payment. 1. In the top right corner, click **Refund**. 1. Select the item to refund, and then click **Refund \<amount\>**. Shopify sends a request to the `refund session URL` specified in your [app extension configuration](#configure-your-payments-extension). If you've customized your app, then the refund process should trigger. If you're testing the app template, then your app receives this request, and saves a record of it. Perform the following additional steps: 1. Navigate to `/app/dashboard` in your app to find the relevant payment session. From the app home, you can click **Dashboard**. 1. Click **Simulate**, and then scroll down to **Refunds**. On the relevant refund session, click **Open**. 1. Select **Resolve** or **Reject** to complete the refund. 1. Verify that the refund has completed by returning to the order under [**Orders**](https://shopify.com/admin/orders) in your store's admin. You should see that the order is now marked as **Refunded**. </Substep> <Substep> ### Test captures Capture funds from an authorized payment. 1. In your development store, [enable manual payment capture](https://help.shopify.com/en/manual/payments/payment-authorization#set-up-manual-payment-capture) to test captures. 1. Submit another [test payment](#test-payments). The order appears in the Shopify admin under [**Orders**](https://shopify.com/admin/orders). 1. Open the new order. In the top right corner, click **Capture payment**. 1. In the page that opens, click **Accept \<amount\>**. Shopify sends a request to the `capture session URL` specified in your [app extension configuration](#configure-your-payments-apps-extension). If you've customized your app, then the capture process should trigger. If you're testing the app template, then your app receives this request, and saves a record of it. Perform the following additional steps: 1. Navigate to `/app/dashboard` in your app to find the relevant payment session. From the app home, you can click **Dashboard**. 1. Click **Simulate**, and then scroll down to **Captures**. On the relevant capture session, click **Open**. 1. Select **Resolve** or **Reject** to complete the capture. 1. Verify that the capture has completed by returning to the order under [**Orders**](https://shopify.com/admin/orders) in your store's admin. You should see that the order is now marked as **Paid**. </Substep> <Substep> ### Test voids Void an authorized payment. 1. In your development store, [enable manual payment capture](https://help.shopify.com/en/manual/payments/payment-authorization#set-up-manual-payment-capture) to test voids. 1. Submit another [test payment](#test-payments). The order appears in the Shopify admin under [**Orders**](https://shopify.com/admin/orders). 1. Open the new order. In the top right, click **More actions**, then **Cancel order**. In the modal that opens, click **Cancel order**. Shopify sends a request to the `void session URL` specified in your [app extension configuration](#configure-your-payments-apps-extension). If you've customized your app, then the void process should trigger. If you're testing the app template, then your app receives this request, and saves a record of it. Perform the following additional steps: 1. Navigate to `/app/dashboard` in your app to find the relevant payment session. From the app home, you can click **Dashboard**. 1. Click **Simulate**, and then scroll down to **Void**. Click **Open** on the void session. 1. Select **Resolve** or **Reject** to complete the void. 1. Verify that the void has completed by returning to the order under [**Orders**](https://shopify.com/admin/orders) in your store's admin. You should see that the order is now marked as **Voided**. </Substep> <Substep> ### Test error scenarios If you want to test out an error scenario in the template, then set the last name in a checkout to any `PaymentSessionStateRejectedReason`, and then complete the checkout as normal. The app template receives this code and automatically rejects the payment with it. --- <Resources> [`PaymentSessionStateRejectedReason`](/docs/api/payments-apps/latest/enums/PaymentSessionStateRejectedReason#top) </Resources> </Substep> </Step> </StepSection> <NextSteps> ## Tutorial Complete! Congratulations! You set up an offsite payments extension. ### Next steps <CardGrid> <LinkCard href="/docs/apps/build/payments/onboard-a-merchant-payments-extension"> #### Onboard a merchant Before a merchant can use your payments extension, they need to go through an onboarding experience. This guide describes how a merchant discovers, installs, authorizes, and activates a payments extension. </LinkCard> <LinkCard href="/docs/api/payments-apps"> #### Payments Apps API After you've completed this tutorial to understand how Payments apps work, you can use the Payments Apps API to programmatically access your payments app's configuration data. You can also use the Payments Apps API to resolve, pend, or reject payments sessions. </LinkCard> </CardGrid> </NextSteps>