Setting Up Quantum ePay Hosted Checkout for Shopify
Share article
This guide covers the end-to-end process for setting up Quantum ePay with Shopify, testing the checkout experience, activating live payments, and managing common payment workflows after launch.
Setting up Quantum ePay is a shared process between your team and Quantum. Your team provides access to the Shopify store and approves the setup before launch. Quantum handles the Shopify app installation, checkout configuration, testing, and final activation.
You may also see both Quantum ePay and Qoin referenced throughout this guide.
- Quantum ePay is the checkout experience connected to your Shopify store.
- Qoin is the payment gateway that securely processes the payment in real time.
When a customer submits a payment through the Quantum ePay Hosted Checkout, Qoin processes the transaction and returns the payment result so the Shopify order can continue.
On This Page
- Opening Quantum ePay in Shopify
- Roles and Responsibilities
- Merchant Onboarding and Installation Process
- Shopify App Navigation
- Test and Live Modes
- Theme Installation and Button Placement
- How Standard Storefront Checkout Works
- Draft Order Invoices
- Refunds and Voids
- Checkout Customization
- Test and Demo Checklist
- Go-Live Checklist
- Common Issues and Troubleshooting
- Need Help?
- Appendix A - Demo Walkthrough
Opening Quantum ePay in Shopify
Always open Quantum ePay from inside Shopify Admin.
If you try to open the app directly outside of Shopify, you may see a message asking you to access it through Shopify Admin instead. This is expected and does not mean something is wrong with your account.
Roles and Responsibilities
| Role | Primary Responsibility | Provides / Performs |
|---|---|---|
| Merchant / Client | Provides access and approves go-live |
|
| Quantum Implementation Owner | Owns implementation and store setup |
|
| Quantum Development Team | Generates merchant-specific Live Qoin API credentials and supports technical escalation | Merchant-specific Live Qoin Client ID and Client Secret. |
| Quantum Support / Qoin Gateway | Supports gateway provisioning | Live X-Terminal Key generated in the Qoin gateway (by Support or Merchant, depending on process). |
Merchant Onboarding and Installation Process
1. Receive the Shopify Collaborator Code
The merchant/client provides the Shopify collaborator request code for the store. This allows Quantum to request the access needed to complete the setup.
The access request should include permission to work with the areas required for:
- App installation
- Theme updates
- Draft Orders and Orders
- Testing
2. Obtain Collaborator Access
After Quantum submits the collaborator request, the merchant/client approves the request in Shopify. Once access is approved, Quantum confirms that the correct Shopify store is connected before making any changes.
3. Request Live Qoin Gateway Credentials
Submit an internal Development ticket to request the merchant-specific Live Qoin Client ID and Client Secret. These credentials are unique to each merchant/client and should never be reused for another account.
Separately, obtain the merchant/client’s Live X-Terminal Key, which is generated in the Qoin gateway.
4. Install the Quantum Checkout app for Shopify
Install/open the custom Quantum Checkout for Shopify for the merchant. Verify that the app loads inside Shopify Admin and that the dashboard reports the store connection correctly.
5. Configure Merchant Settings
Keep the merchant/client in Test mode while setup is being completed. In Merchant Settings, enter the merchant-specific Live Qoin Client ID, Live Client Secret, and Live X-Terminal Key.
Note: These credentials are encrypted when saved and will not be displayed again afterward.
6. Configure Checkout Appearance
Open the Customization section and add the merchant/client’s logo and preferred checkout colors. Review the hosted checkout to confirm the branding displays correctly before presenting it to the merchant/client.
7. Install Storefront Buttons
Enable the Quantum Checkout app embed in the merchant/client’s active Shopify theme. Then add the provided checkout button code to each location where the Quantum checkout button should appear.
8. Test the Checkout
While the merchant/client is still in Test mode, complete the following:
- Storefront test order
- Draft Order invoice test
- Refund or void test
Confirm that each order updates correctly in Shopify and that the matching transaction appears in Qoin.
9. Activate Live Payments
Once the merchant/client and internal team approve the setup, switch the store from Test mode to Live mode.
Live transactions will then be processed using the merchant/client’s saved Live Qoin credentials.
Shopify App Navigation
Dashboard
View the store’s connection and setup status, along with available quick actions.
Figure placeholder: Shopify app Dashboard.
Merchant
Manage Test and Live mode and enter the merchant/client’s Live Qoin credentials.
Figure placeholder: Shopify app Merchant Settings
Customization
Update the checkout branding, including the logo and available color settings.
Figure placeholder: Checkout Customization screen.
Installation
Access the instructions needed to enable the checkout and add Quantum checkout buttons to the storefront.
Figure placeholder: Installation screen with App Embed and placement instructions.
Support
View Quantum Support contact information or submit a support request through the app.
Figure placeholder: Installation screen with App Embed and placement instructions.
Test and Live Modes
How Credentials Work in Each Mode
Quantum ePay uses different Qoin credentials depending on whether the store is in Test mode or Live mode.
TEST
Used for setup and testing
- Uses shared Qoin Test credentials
- No merchant-specific Test credentials are required
- No live payments are processed
LIVE
Used to process live payments
- Uses credentials unique to each merchant/client
- Includes the Qoin Client ID, Client Secret, and X-Terminal Key
- Credentials are encrypted and securely stored for the merchant/client’s store
Important: Live credentials are merchant-specific and should never be reused for another store.
Merchant Settings
Use Merchant Settings to select Test or Live mode and enter the merchant/client’s Live Qoin credentials.
Live credentials can be entered while the store remains in Test mode, allowing setup and testing to be completed before live payments are activated.
Theme Installation and Button Placement
In the Shopify Theme Editor, enable the Quantum Checkout for Shopify. Then add the matching code below to each location where the Quantum checkout button should appear.
| Placement | Placeholder |
|---|---|
| Cart Drawer | <div data-qep-checkout-button data-qep-placement="cart-drawer" data-qep-customer-id="{% if customer %}{{ customer.id }}{% endif %}"></div> |
| Product Page | <div data-qep-checkout-button data-qep-placement="product-page" data-qep-customer-id="{% if customer %}{{ customer.id }}{% endif %}"></div> |
| Cart Page | <div data-qep-checkout-button data-qep-placement="cart-page" data-qep-customer-id="{% if customer %}{{ customer.id }}{% endif %}"></div> |
How the Checkout Button Works
Once installed, the Quantum checkout button automatically reloads when Shopify updates supported areas of the storefront, such as the cart drawer.
For logged-in customers, Shopify passes the customer information needed for checkout. Customers who are not logged in can still use Quantum checkout and will enter their contact and address information during checkout.
Storefront Placement Examples
Quantum Checkout button on the product page
Quantum Checkout button in the cart drawer / side cart.
How Standard Storefront Checkout Works
Customer Checkout Experience
Before payment is submitted, Shopify verifies the current product prices, discounts, taxes, currency, and order total. Available shipping options and rates are also verified through Shopify before the customer completes payment.
Once payment is submitted, the transaction is securely sent from the Quantum ePay checkout to Qoin for real-time processing.
Logged-In and Guest Checkout
Customers can complete checkout whether they are logged in to Shopify or checking out as a guest.
For logged-in customers, Shopify can carry the customer’s account information into the checkout. Guest customers enter their email, billing, and shipping information during checkout.
In both cases, Qoin processes the payment in real time. Once the payment is approved, the Shopify order is created or completed.
Payment Retry Protection
The checkout is designed to help prevent duplicate charges.
If Qoin declines the payment or returns a confirmed failure, the customer can correct the issue and try the payment again.
If the payment result is unclear, such as when a network interruption occurs after the payment is submitted, the checkout will prevent another payment attempt until the transaction can be reviewed. This helps protect the customer from being charged twice.
Draft Order Invoices
Quantum ePay can be used to send a secure payment link for a Shopify Draft Order. The customer completes payment through the Quantum ePay checkout, and the transaction is processed by Qoin in real time.
Once payment is approved, the existing Draft Order is completed as a Shopify Order.
Send a Draft Order Invoice
- Create and save the Draft Order in Shopify Admin.
- Select Send Invoice through Quantum.
- Review or update the recipient email, subject, and message.
- Send the invoice.
The customer receives an email with a secure Quantum ePay payment link. After payment is approved through Qoin, the existing Draft Order is completed as a Shopify Order.
Draft Order References
Quantum invoice composer before sending.
Quantum invoice composer before sending.
Quantum invoice composer final review before sending.
If a Draft Order Changes
If the items or quantities in a Draft Order are changed after an invoice has already been sent, resend the Quantum invoice. The existing payment link will remain the same, but the checkout will update to reflect the latest Draft Order information before the new invoice email is sent.
One Link, One Checkout:
Each invoice link connects to a single checkout session. If the same link is opened more than once, it will return to the existing checkout instead of creating a new one.
Each Invoice Link Uses the Same Checkout
Each invoice link is connected to one checkout session. If the link is opened again, it returns to the same checkout rather than creating a new one.
Refunds and Voids
Refunds and voids are started through Quantum ePay in Shopify. Qoin processes the payment action in real time.
1. Open the Shopify Order
Open the eligible Quantum ePay/Qoin-paid order in Shopify and start the refund or void action.
2. Check the Current Qoin Payment Status
Quantum checks Qoin for the latest payment status before determining the correct action.
3. Determine Refund or Void
Quantum automatically selects the appropriate action based on the payment status:
- Pending settlement: Void / reversal
- Settled: Refund
4. Process the Request in Qoin
The refund or void is submitted to Qoin for real-time processing.
5. Update the Shopify Order
Once Qoin successfully processes the request, the corresponding refund information is created or updated in Shopify.
6. Record the Result
The completed refund or void is recorded for future reference and support.
Partial Refunds: Partial refunds are supported up to the remaining refundable amount.
Refund and Void References
Use the Quantum refund/void action from an eligible Shopify order to begin the process.
Quantum refund/void action in Shopify Admin.
Quantum refund/void action in Shopify Admin.
Refunds can only be processed for orders that belong to the merchant/client’s Shopify store. The Quantum ePay Shopify app starts the refund or void request, and Qoin processes the payment action.
Before the request is submitted, the Quantum ePay Shopify app checks the latest payment status in Qoin to determine whether the transaction should be voided or refunded. This helps prevent the wrong action from being processed.
| Qoin Payment Status | Action |
|---|---|
| Pending settlement | Void / Reversal |
| Settled | Refund |
Partial refunds are supported up to the remaining refundable amount. Once Qoin successfully processes the refund or void, the Shopify refund information is updated accordingly.
Checkout Customization
Checkout customization is specific to each merchant/client’s Shopify store. Use the Customization section to update the logo and available color settings, then review the checkout before launch to confirm the branding displays correctly.
Test and Demo Checklist
- Open Quantum Checkout through Shopify Admin and confirm the Dashboard, Merchant, Customization, Installation, and Support tabs load correctly.
- Confirm the store is in Test mode.
- If Live credentials have already been added, confirm the Qoin Client ID, Client Secret, and X-Terminal Key show as configured. Do not expose saved credential values.
- Confirm the Quantum Checkout App Embed is enabled in the active Shopify theme.
- Confirm the Quantum checkout button appears in each intended location and continues to display after cart quantity updates.
- Complete a test payment as a logged-in customer. Confirm the transaction appears in Qoin and the Shopify Order is created.
- Complete a test payment as a guest customer. Confirm the transaction appears in Qoin and the Shopify Order is created.
- Create a Shopify Draft Order, send the Quantum invoice, complete payment, and confirm the same Draft Order is completed as a Shopify Order.
- Update an item or quantity on a Draft Order, resend the Quantum invoice, and confirm the checkout reflects the updated order details.
- Open the same invoice link more than once and confirm it returns to the same checkout session
- Complete a refund or void test and confirm the request is processed successfully in Qoin and reflected correctly in Shopify.
- Confirm that opening the app directly outside of Shopify Admin displays the Shopify Admin access message rather than an error page.
Go-Live Checklist
Before switching the merchant/client to Live mode, confirm the following:
- The merchant/client has approved the checkout appearance and workflow.
- Quantum Development has provided the correct merchant-specific Live Qoin Client ID and Client Secret.
- The correct Live Qoin X-Terminal Key is configured for the merchant/client.
- All Live Qoin credentials are saved in Merchant Settings and show as configured.
- All required Test mode workflows have been completed successfully.
- Internal check: Production debugging is disabled and HTTPS is enabled.
- The required Quantum checkout button code is added to the active Shopify theme and the Quantum Checkout App Embed is enabled.
- The store is switched from Test mode to Live mode only after final approval.
- Support contacts and the appropriate escalation process are confirmed before launch.
Common Issues and Troubleshooting
Checkout Button Missing After a Cart Update
Confirm the checkout button code is still in place and that the Quantum Checkout App Embed is enabled. The Quantum checkout button should reappear automatically after the cart is updated.
Payment Approved, but the Shopify Order Is Not Showing
Do not submit the payment again.
Check the payment and checkout status first. A payment may already be approved in Qoin while the Shopify order is still being completed. The checkout prevents another payment attempt to help avoid duplicate charges.
Draft Order Invoice Shows an Old Quantity
If the items or quantities in a Draft Order were changed after the invoice was sent, resend the Quantum invoice.
The existing checkout will update to reflect the latest Draft Order information.
Live Mode Cannot Connect to Qoin
Confirm that all three merchant-specific Live Qoin credentials are configured correctly:
- Client ID
- Client Secret
- X-Terminal Key
Test credentials cannot be used in Live mode.
Shopify Admin Access Message Appears
If the app is opened directly outside of Shopify Admin, an access message may appear. This is expected.
Open the Quantum Checkout app through Shopify Admin instead.
Refund or Void Is Rejected
Check the latest payment status in Qoin before retrying.
The Quantum Checkout app uses the current Qoin status to determine whether the transaction should be voided or refunded. Review the payment status and refund details before submitting the request again.
Need Help?
The Support tab in the Quantum ePay Shopify app includes current support contact information and an in-app form for submitting support requests.
| Channel | Details |
|---|---|
| support@quantumepay.com | |
| Phone | (888) 858-1678 ext. 100 |
| Hours | Monday-Friday, 8:00 AM-5:00 PM PT |
| Development escalation | Use an internal development ticket for merchant-specific Live Qoin Client ID/Client Secret generation and application-level issues. |
Appendix A - Demo Walkthrough
1. Open Shopify Admin
Open the Quantum ePay app and show the Dashboard. Confirm that the correct merchant/client store is connected.
2. Review Merchant Settings
Show the Test and Live mode settings. Explain that Test mode uses shared Qoin Test credentials, while Live mode uses credentials specific to the merchant/client.
3. Review Checkout Customization
Open Customization and show where the merchant/client’s checkout logo and colors can be updated.
4. Review Installation
Open Installation and show where to enable the Qoin Hosted Checkout App Embed and find the code used to add Quantum checkout buttons to the storefront.
5. Complete a Test Checkout
Add an item to the store, open the Quantum checkout from the product or cart page, and complete a Test mode payment. Explain that the payment is processed by Qoin in real time.
6. Confirm the Shopify Order
Return to Shopify Admin and show the completed order and corresponding Qoin payment details.
7. Send a Draft Order Invoice
Create a Draft Order and select Send Invoice through Quantum. Show how the customer receives a secure payment link and explain that, once payment is approved, the existing Draft Order is completed as a Shopify Order.
8. Demonstrate a Refund or Void
Open an eligible Qoin-processed order and start the Quantum refund/void action. Explain that the Quantum ePay Shopify app checks the current payment status in Qoin and automatically determines whether the transaction should be voided or refunded.
