Shopify onsite payments app
Last updated: July 31, 2024
From installing the onsite payments app to performing your first test payment, learn how to get started with the Checkout.com onsite payments app for Shopify.
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, please see the Shopify onsite plugin - previous page.
- As per Shopify’s requirements, the new Shopify onsite payments app is not compatible with any
checkout.liquidcustomizations you may have. If you've customized yourcheckout.liquidtemplate, you'll need to upgrade to checkout extensibility. - In order to use Checkout.com’s onsite payments app, you must upgrade to the new Shopify checkout version. Shopify does not support the Classic checkout version.
Information
Before you attempt to integrate with Shopify, make sure that you are successfully onboarded onto the Checkout.com platform.
You will need to access both the Shopify Admin Portal and the Checkout.com Dashboard during these steps.
- Sign in to your Checkout.com Test Dashboard.
- Create an OAuth 2.0 key pair.
- Ensure the Default scope is selected and that sessions:browser under Managed scopes is selected.
- Ensure that only one processing channel is selected then select Create key.
- Store the client ID and client secret values securely, you will not be able to view them after they have been generated.
Note
Creating an API Key with the Allow any processing channel option enabled will cause payments to fail.
- Browse to the Checkout.com Onsite Payments App listing on the Shopify app store then select Add app.
- You'll be redirected to your Shopify store where you'll be prompted to install the Checkout.com Onsite Payments App. Select Install app.
After installing the app you will need to configure it before it can be activated. In Shopify, select Manage to configure the applications settings.
- Enter your API credentials.
- Enter your 3DS settings preferences.
- Enter the billing descriptor details.
- Select Save.
- After configuring the Account Settings section, navigate to Webhooks.
- Select Register Webhook and ensure the webhook is created successfully.
- In the Account Settings section, validate that the Account Not Ready tag has changed to Account Ready.
- Select Back to Payments Settings. You will be redirected to the alternative providers page in your Shopify store.
- Optionally, select Enable test mode if testing your integration using the Sandbox mode.
- Select Activate Checkout.com Onsite Payments.
Information
Webhooks should only be configured from within Shopify. There is no need to configure Webhooks in your Checkout.com account once they are configured in Shopify.
Information
When testing in sandbox, ensure you are using sandbox API keys and not production API keys.
- In the Shopify Admin Portal, browse to Settings > Payments.
- Under Checkout.com Onsite Payments, select Manage.
- In the Test mode section, select Enable test mode.
- In the app’s settings page, ensure Sandbox mode is enabled.
- Browse to your storefront and add a product to your cart.
- Select your cart then proceed to checkout.
- Enter the required billing details. We recommend using a real email address so you can receive the order confirmation.
- Select Continue to shipping, then Continue to payment.
- Enter the following card details:
- Number –
4242 4242 4242 4242 - Expiry date –
any date in the future - CVV –
100
- Number –
- Select Pay. After completing the 3DS authentication simulator, you'll be redirected to the order confirmation page. If you entered a genuine email address in the billing details, you'll also receive an order confirmation email.
- In the Shopify store admin, browse to Orders to confirm that the order has gone through.
- Sign in to your Checkout.com Test Dashboard.
- Browse to Payments > Processing > All Payments. The order payment will be displayed with a status indication, such as Captured.
If you're happy with the outcome of your testing and are ready to start accepting live payments, follow these steps to go live.
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.
- Sign in to your Checkout.com Live Dashboard.
- Create an OAuth 2.0 key pair.
- Ensure the Default scope is selected and that sessions:browser under Managed scopes is selected.
- Ensure that only one processing channel is selected then select Create key.
- Store the client ID and client secret values securely, you will not be able to view them after they have been generated.
- For production, you need to have Full Card API enabled for your processing channel. To enable full card processing on your account, contact your Solution Engineer or [email protected].
- If you need 3DS, you will need sessions:browser scope enabled for your OAuth key pair. To enable 3DS contact your Account Manager or email [email protected] your account name as it appears in the Checkout.com Dashboard and the ID of your production API key.
- In your Shopify store's back office, browse to Settings, Payments, then select Manage next to Checkout.com Onsite Payments.
- Select Manage in the Account Status section.
- On the App's configuration page, replace the API credentials with the production credentials you generated.
- Select Disabled to disable Sandbox mode, then select Save.
- Verify that the app’s status tag is now Account Not Ready.
- Navigate to Webhooks.
- Select Register Webhook and ensure the webhook was created successfully.
- In the Account Settings section, ensure that the Account Not Ready tag has changed to Account Ready.
- Select Back to Payments Settings to return to your store’s Payments page.
- Deselect Enable Test mode.
- Select Save.
You are now live with the Checkout.com Onsite Payments App.
Information
Apple Pay is only available when using the current version of the Checkout.com Onsite Payments App.
To enable Apple Pay in your Shopify Onsite Payments App, sign in to your Shopify admin's back office and go to the Settings > Payments page:
- Select Manage.
- Scroll down the page to view the available payment options and select Apple Pay.
- Select Save.
Note
If you plan to offer Apple Pay as a payment option for your customers, you must adhere to Apple's Acceptable Use Guidelines.
Note
Do not process refunds using the Checkout.com Dashboard or API. Refunds must be processed using the Shopify Order Management interface in your store’s back office. This is to maintain end-to-end order integrity on the Shopify platform.
After migrating to the new integration, orders from your original integration will still be available for post-authorization actions within Shopify's Order Management interface.
Payments that were processed using the original integration can be refunded, captured, and voided using the Shopify Order Management interface in your store’s back office.