# Shopify onsite payments app Follow this guide to get started with Checkout.com's onsite payments app for Shopify, from installing the app to performing your first test payment. > **Note** > > - This page is for the current version of the Shopify onsite payments app. If Shopify has extended your migration deadline due to a compatibility issue with Shopify's [checkout extensibility](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations/checkout-extensibility), see [Shopify onsite plugin - previous](https://www.checkout.com/docs/payments/accept-payments/connect-to-our-integration-partners/shopify-onsite-plugin-previous.md). > - As per Shopify’s requirements, the new Shopify onsite payments app is not compatible with any `checkout.liquid` customizations you may have. If you've customized your `checkout.liquid` template, upgrade to [checkout extensibility](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations/checkout-extensibility). > - To use Checkout.com’s onsite payments app, you must upgrade to the new [Shopify checkout](https://help.shopify.com/en/manual/checkout-settings) version. Shopify does not support the classic checkout version. --- ## Supported payment methods The Shopify onsite payments app supports the following payment methods: - Apple Pay - Google Pay - Card payments - American Express - Cartes Bancaires - Diners Club International - Discover - JCB - Mada - Mastercard - UnionPay - Visa --- ## Set up your Shopify integration > **Information** > > Before you integrate with Shopify, make sure that you are successfully onboarded to Checkout.com's platform. You need access to both the Shopify Admin Portal and the Checkout.com [Dashboard](https://dashboard.checkout.com). 1. Sign in to your Checkout.com sandbox [Dashboard](https://dashboard.checkout.com). 2. Create an [OAuth 2.0 key pair](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/oauth-2-0-client-credentials.md) and ensure you select the following scopes: - _Default_ scope - _sessions:browser_ under _Managed scopes_ - One or more processing channels that you want to use for this integration. If you select more than one processing channel, you must provide the processing channel ID in the configuration page of your app. ![Default scopes screen showing recommended and managed scopes](https://www.checkout.com/docs/Payments/Ecom/1-scopes.png) 3. Select _Create key_. 4. Store the _client ID_ and _client secret_ values securely. You cannot view them again after they're generated. > **Information** > > If you create an API Key with the _Allow any processing channel_ option enabled, you must provide the processing channel ID in the configuration page of your app to prevent payments from failing. --- ## Install the payments app 1. Browse to the [Checkout.com Onsite Payments App](https://apps.shopify.com/checkout-com-onsite-payments) listing on the [Shopify app store](https://apps.shopify.com/), and then select _Add app_. 2. Shopify redirects you to your store and prompts you to install the _Checkout.com Onsite Payments App_. Select _Install app_. --- ## Configure the payments app After installing the app, you must configure its settings before activation. ![Account Settings screen showing Getting Started, Account Credentials, Sandbox mode, and 3DS Mode sections](https://www.checkout.com/docs/Payments/Ecom/2-configure.png) 1. In Shopify, select _Manage_ and enter the following: - Your API credentials - Your 3DS settings preferences - Your billing descriptor details 2. Select _Save_. 3. Go to _Webhooks_. 4. Select _Register Webhook_ and ensure the webhook is created successfully. ![Webhooks configuration screen](https://www.checkout.com/docs/Payments/Ecom/7-QA-webhooks.png) 5. In the _Account Settings_ section, check that the _Account Not Ready_ tag has changed to _Account Ready_. ![Account Settings screen showing Getting Started section](https://www.checkout.com/docs/Payments/Ecom/3-credentials.png) 6. Select _Back to Payments Settings_. You are redirected to the _Alternative providers_ page in your Shopify store. 7. Optionally, select _Enable test mode_ if testing your integration using the sandbox mode. 8. Select _Activate Checkout.com Onsite Payments_. ![Account Settings screen showing list of alternative providers in your Shopify store](https://www.checkout.com/docs/Payments/Ecom/6-Active-App.png) > **Information** > > Only configure webhooks within Shopify. You do not need to configure them in your Checkout.com account once they're configured in Shopify. --- ## Test your sandbox integration > **Information** > > When testing in the sandbox environment, ensure you are using sandbox API keys and not production API keys. 1. In the Shopify Admin Portal, go to _Settings > Payments_. 2. Under _Checkout.com Onsite Payments_, select _Manage_. 3. In the _Test mode_ section, select _Enable test mode_. 4. In the app’s settings page, ensure _Sandbox mode_ is enabled. 5. Browse to your storefront and add a product to your cart. 6. Select your cart, and then proceed to checkout. 7. Enter the required billing details. We recommend using a real email address so you can receive the order confirmation. 8. Select _Continue to shipping_, and then _Continue to payment_. 9. Enter the following card details: - Number – `4242 4242 4242 4242` - Expiry date – `Any date in the future` - CVV – `100` 10. Select _Pay_. After completing the 3DS authentication simulator, you're redirected to the order confirmation page. If you entered a real email address in the billing details, you also receive an order confirmation email. 11. In the _Shopify store admin_, browse to _Orders_ to confirm that the order has gone through. 12. Sign in to your Checkout.com sandbox [Dashboard](https://dashboard.checkout.com). 13. Go to _Payments_ > _Processing_ > _All Payments_. The order payment is displayed along with the status. For example, _Captured_. --- ## Go live After you have finished testing, follow these steps to go live. ### Checkout.com configuration > **Information** > > When creating API credentials for your production environment, ensure that you select the same scopes and processing channel as you did for your sandbox API credentials. 1. Sign in to your Checkout.com live [Dashboard](https://dashboard.checkout.com). 2. Create an [OAuth 2.0 key pair](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/oauth-2-0-client-credentials.md). 3. Ensure the following are selected: - _Default_ scope - _sessions:browser_ under _Managed scopes_ - Only one processing channel 4. Select _Create key_. 5. Store the _client ID_ and _client secret_ values securely. You cannot view them again after they're generated. 6. For production, you must have Full Card API enabled for your processing channel. To enable full card processing on your account, contact your solution engineer or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). 7. If you need 3DS, you must enable the _sessions:browser_ scope for your OAuth key pair. To enable 3DS, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). Provide your account name as it appears in the Checkout.com [Dashboard](https://dashboard.checkout.com) and the ID of your production API key. ### Shopify configuration 1. In your Shopify store's back office, go to _Settings_, _Payments_, and then select _Manage_ next to _Checkout.com Onsite Payments_. ![Payments screen with the message 'Development stores can only process test payments'](https://www.checkout.com/docs/Payments/Ecom/4-channels.png) 2. Select _Manage_ in the _Account Status_ section. ![Settings screen with the message ‘Test mode is on’](https://www.checkout.com/docs/Payments/Ecom/8-Manage.png) 3. On the app's configuration page, replace the API credentials with the production credentials you generated. 4. Select _Disabled_ to disable sandbox mode, and then select _Save_. 5. Check that the app’s status tag is now _Account Not Ready_. 6. Go to _Webhooks_. 7. Select _Register Webhook_ and ensure the webhook was created successfully. ![Webhooks configuration screen](https://www.checkout.com/docs/Payments/Ecom/7-webhooks.png) 8. In the _Account Settings_ section, ensure that the _Account Not Ready_ tag has changed to _Account Ready_. 9. Select _Back to Payments Settings_ to return to your store’s _Payments_ page. 10. Deselect _Enable Test mode_. ![Test mode selection screen](https://www.checkout.com/docs/Payments/Ecom/9-testmode.png) 11. Select _Save_. You are now live with the Checkout.com onsite payments app. ## Enable Apple Pay and Google Pay To enable Apple Pay or Google Pay in your Shopify onsite payments app: 1. Sign in to your Shopify admin's back office. 2. Go to the _Settings > Payments_ page, and select _Manage_. 3. Scroll down the page to view the available payment options and select _Apple Pay_ and _Google Pay_. 4. Select _Save_. > **Note** > > To offer Apple Pay as a payment option for your customers, you must follow Apple's [Acceptable Use Guidelines](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/). --- ## Post go live payment refunds, captures, or voids > **Note** > > Do not process refunds using the Checkout.com Dashboard or API. You must process refunds using the Shopify Order Management interface in your store’s back office. > This maintains end-to-end order integrity on the Shopify platform. After migrating to the new integration, orders from your original integration are still available for post-authorization actions within Shopify's Order Management interface. You can refund, capture, and void payments that were processed using the original integration using the Shopify Order Management interface in your store’s back office.