Shopify Embedded Multi-APMs
Last updated: October 19, 2026
Overview
With our new Shopify Embedded Payment Plugin, merchants can enable and manage multiple Alternative Payment Methods (APMs) through a single application.
This solution is built on a server‑to‑server integration model, providing a fully embedded checkout experience without relying on COPYandPAY or hosted payment widgets.
This architecture ensures:
- A seamless, native Shopify checkout experience
- Greater control over payment flows
- Flexibility to support APMs requiring server‑side processing
- Direct orchestration through the Payments Orchestration Platform
Whether you are setting up a new Shopify store or expanding globally with additional payment options, the Embedded Multi‑APMs plugin allows you to activate and manage APMs quickly, securely, and efficiently.
Built on the Payments Orchestration Platform, the plugin provides payment routing flexibility, orchestration intelligence, and advanced analytics — all through one unified integration.
How it works
Compatibility
Our plugin supports the following versions:
- Node 18
- Remix 2.7.1
- React 18.2
- Prisma 5.12
Before you start
Create/confirm your Merchant Portal account & access
- Ensure you have access to the ACIPayment Orchestration Platform portal (UAT/Sandbox for testing, Production for live).
- Ensure you have the correct merchant/PSP credentials and permissions to configure payment settings.
- Configure your merchant account and the connector
Obtain app credentials
- Generate or retrieve the required credentials from the platform tooling (e.g., Client ID/Secret, API keys, merchant identifier).
- Store credentials securely.
Confirm required data & processing setup
- Confirm which card schemes you will enable.
- Confirm required shopper/order fields needed by your downstream connector/acquirer setup.
- Confirm callback/webhook endpoints and allowed domains (if applicable).
Install
Marketplace listing: open in the Shopify App Store.
Option A — Shopify App installation
- Shopify Admin →Apps
- Locate APMs by ACI Worldwide
- Click Install
- Approve permissions
Option B — Private/Custom distribution
- Use the installation link/package provided by us
- Install via Shopify Admin → Apps
- Verify the plugin appears in your payment settings
Configure
Configuration in Shopify Admin
- Go to Apps on the left navigation.
- Find APMs by ACI Worldwide in the list of installed Apps to be redirected to the Payment Configuration page.
- Enter: (Refer to Onboarding configuration)
- Client ID in the Entity ID field (Test/Live)
- Client Secret / API Key in the API key field (Test/Live)
- Add and configure the required payment methods in the “Dynamic Alternative Payment Methods Settings”
- Any additional required fields (OPP params, locale, etc.)
- Webhook decryption Key (you will get the same when you configure webhooks/notifications in merchant portal)
- Save
- On successfully saving the configuration, you will see a “Return to Shopify” button on the top of the page. Click it.
- You will be redirected to the Payment settings page of Shopify. Enable Test mode (if required) and click on the Activate button.
Onboarding configuration
| Field Name in Shopify Configuration | Merchant Portal Field Name | Mandatory/Optional | Comments |
|---|---|---|---|
| Entity ID | EntityId | Mandatory | From the Merchant Portal at the Merchant or Channel level, according to the Merchant Portal configuration setting of the Merchant accounts In Payments Orchestration Platform - Administration→ Account data |
| API Key | Access Token | Mandatory | From the Merchant Portal at the Merchant or Channel level, according to the Merchant Portal configuration setting of the Merchant accounts In Payments Orchestration Platform - Administration→ Account data → Merchant Info/Channel Info |
| Test Mode | NA | Mandatory | Applicable only for test environment, INTERNAL is to test with the simulator, EXTERNAL for the external test simulator. |
| Webhook URL | Prepopulated to configure Webhooks in the Merchant Portal | ||
| Use Store Locale | NA | Optional | |
| Dynamic Alternative Payment Methods Setting | NA | Mandatory | Configure Payment Methods with Valid Payment Key |
| OPP Parameter Settings- Manual Entry | NA | Optional | Configure Additional Parameter to be sent in request (Valid OPP parameter is required) |
| OPP Parameter Settings- Drop Down Entry | NA | Optional | Configure Additional Parameter to be sent in request from the available list of Shopify parameters (Valid OPP parameter is required) |
Webhooks
Webhooks send real‑time updates from the Payment Orchestrator Platform to the plugin platform. They notify the plugin about:
- Payment state updates
- Token events
- Payment schedules
- Risk events
- Any transaction‑related changes
Webhooks must be configured for transaction updates to work correctly.
Merchant/PSP responsibilities
You must configure the webhooks and generate the Webhook Decryption Key in the Payments Orchestration Platform.
Steps to configure webhooks
- Log in to thePayments Orchestration Platform
- Select your division (e.g.,OPP_Division)
- Navigate to Administration → Webhooks
- Click Add New Webhook
- Configure as follows:
| URL | https://<your-domain>/acipayment/process/notification |
|---|---|
| Notification Types | Select as required for your business |
| Fields to Include | Select as needed |
| Secret for Encryption | Copy this value and paste in Shopify under Webhook Decryption Key |
| Wrapper for Encrypted Notification | JSON |
| Emails | Add email addresses for notification alerts |
Figure 1: Steps to configure webhooks
Figure 2: Steps to configure webhooks (continued)
Test & go live
Step 3: Test a transaction
Recommended test checklist:
- Test successful payment
- Test decline scenario (insufficient funds / invalid card)
- Confirm Shopify order status reflects payment result correctly
- Confirm reporting/transaction logs show expected references
Step 4: Go live
- Disable Test mode in Shopify Payment setting
- Replace UAT credentials with Production credentials
- Run a low-value live transaction to validate end-to-end
- Monitor first transactions in reporting
Step 5: Set your store currency
Ensure the Shopify store currency matches the settlement/processing currency configured in Merchant Portal (and supported by your acquiring setup).
Upgrading the app
- Shopify apps are automatically updated. If there are any change in required permissions in your store, you will be prompted to provide the same on accessing the App Payment configuration page.
- After upgrade, re-validate:
- Checkout rendering
- Order status updates
- Reporting/settlement behaviour
Screenshots
- Navigate to APP - Shopify Admin → Settings → Payments (ACI Payment app enabled), you will find‘Credit Card Payments by ACI Worldwide"
- When App is in Production, you should not see test mode as visible in the screen below.
Figure 3: Screenshots
Figure 4: Screenshots (continued)
- Payment app configuration screen (credentials/environment)
Figure 5: Screenshots (continued)
Figure 6: Screenshots (continued)
Figure 7: Screenshots (continued)
Note - Configure the above fields only when required
Figure 8: Screenshots (continued)
- On Shopify Checkout
Figure 9: Screenshots (continued)
Features
Payment types
| Payment Type | Supported | Comments | |
|---|---|---|---|
| Authorization (PA) | ✔ | ||
| Debit (DB) | ✔ | ||
| Credit (CD) | – | ||
Capture (CP) | Full | ✔ | |
| Partial | ✔ | ||
| Multiple | ✔ | ||
Refund (RF) | Full | ✔ | |
| Partial | ✔ | ||
| Multiple | ✔ | ||
Reversal (RV) | Full | ✔ | |
| Partial | ✔ | ||
| Multiple | ✔ | ||
| Receipt (RC) | – | ||
| Rebill (RB) | – | ||
Important Note:
The plugin supports all payment types listed above, but the actual availability depends on the payment brand and the connector configured to process the payment.
To use a specific payment type (e.g., Partial Capture, Multiple Refunds), the payment brand must support that operation, and the connector integration for that brand must also support it.
Please refer to the respective connector integration sheet for brand‑level support.
Features
We have standard plugin integration with Shopify using our Open Payment Platform Integration option, which gives you access to all the features and uses the Server-to-Server to present payment options to your shoppers
| Feature | Supported | Comments | |
|---|---|---|---|
| Supported Brands | ✔ | All payment brands are supported with Virtual Account methods; any existing customization for the widget or additional fields is not supported. Please check the supported fields before the integration. | |
| Supported Payment Methods | ✔ | Virtual Account | |
| Countries | ✔ | All Shopify‑supported countries | |
| Authorization Currencies | ✔ | ALL | |
| Late Notification | ✔ | ||
Payment Facilitator | – | Can be supported if the connector has its own configuration for PayFac | |
| Recurring/Subscription | – | ||
| Reference ID | ✔ | ||
| Timeout Autoreversal | ✔ | ||
| TLS 1.2 | ✔ | ||
| Server-Server Integration | ✔ | ||
| Shopify Embadded Experiance | ✔ | ||
| Internal Tokenization | – | ||
| Omni Tokenization | – | ||
| External Tokenization | – | ||
| Zero Authorization/ Account Verification | – | ||
| Digital Wallet | – | Apple Pay/Google Pay | |
| 3D Secure | – | Using our MPI | |
| Airline Data | – | ||
| Settlement Reporting | – | Settlement reporting as per the specific brand connector in use. | |
| COPYandPAY OneClick Checkout (Save Card) | – | ||
| COPYandPAY widget or full-page redirect | – | ||
| Customization through standard COPYandPAY JS | – | using wpwlOptions | |
| Customization through standard COPYandPAY CSS | – | using wpwlOptions | |
| PayByLink | – | PayByLink configuration is needed in the Payments Orchestration Platform to configure the Shopify Plugin, and it is not supported as a standalone checkout option or to generate and distribute the link | |
| Manage Saved Card in User Profile | – | ||
| Download Audit Log | ✔ | Enable this through Shopify Support | |
| Guest Checkout | ✔ | ||
| Transaction identifier | ✔ | merchantTransactionID | |
| Fast Checkout | – | ||
| Fraud with Payment | ✔ | ||
| Standalone Fraud | – | ||
| PCI DSS 4 | ✔ | ||
Supported fields
These fields are automatically handled by the plugin through Shopify’s data model. No manual implementation by merchants is needed.
Important Note:
The fields listed below are integrated through Shopify and passed by default to the payment platform. However, some payment brands may require additional fields that are not included in this standard integration.
Please review the payment brand’s connector documentation before starting the integration. If the connector requires additional static fields, the plugin provides a feature to pass such fields. Please refer to the “Additional Static Fields” configuration section for details.
| OPP Field Name | Shopify Field |
|---|---|
| entityId | Derived from Admin |
| amount | amount |
| currency | currency |
| paymentType | kind |
| paymentBrand | Will derive from payment_method object |
| testMode | Admin derived |
| merchantTransactionId | id |
| customer.merchantCustomerId | Not available |
| customer.givenName | billing_address.given_name |
| customer.surname | billing_address.family_name |
| customer.phone | customer.phone_number |
| customer.mobile | customer.phone_number |
| customer.email | customer.email |
| customer.birthDate | Not available |
| customer.ip | Not available |
| billing.street1 | billing_address.line1 |
| billing.street2 | billing_address.line2 |
| billing.city | billing_address.city |
| billing.state | billing_address.province |
| billing.postcode | billing_address.postal_code |
| billing.country | billing_address.country_code |
| billing.houseNumber1 | Not available |
| shipping.street1 | shipping_address.line1 |
| shipping.street2 | shipping_address.line2 |
| shipping.city | shipping_address.city |
| shipping.state | shipping_address.province |
| shipping.postcode | shipping_address.postal_code |
| shipping.country | shipping_address.country_code |
| shipping.phone | shipping_address.phone_number |
| shipping.companyName | shipping_address.company |
| cart.items[0].name | item name |
| cart.items[0].merchantItemId | Not available |
| cart.items[0].quantity | 1 |
| cart.items[0].sku | sku |
| cart.items[0].price | Cart Total |
| cart.items[0].currency | Actual Currency should be mapped |
| cart.items[0].description | null |
| cart.items[0].tax | Not available |
| cart.items[0].totalAmount | Cart Total |
| cart.items[0].originalPrice | Not available |
| customParameters[SystemName] | Derive the values |
| customParameters[SystemVersion] | Derive the values |
| customParameters[moduleName] | Derive the values |
| customParameters[moduleVersion] | Derive the values |
| shopperResultUrl | Derive the values |
| Authorization | Generated through API |
| locale | merchant_locale |
FAQ
Installation
How do I install the APM app?
Install via Shopify App Store or using a private/custom installation link provided by us.How do I verify installation?
The app should appear under Shopify Admin → Apps and within payment settings.Can I install multiple APMs?
Yes:- Use a multi-APM app to enable multiple payment methods
- Or install individual APM apps for specific payment methods
Configuration
What credentials are required?
- Client ID (Entity ID)
- API Key / Client Secret
- Webhook configuration values (Payments Orchestration Platform)
Where is configuration completed?
- Shopify Admin (App settings)
- Merchant Portal (APM enablement and routing)
How do I enable APMs?
Configure payment methods under Dynamic Alternative Payment Methods settings in the app.Why is correct platform brand configuration important?
Incorrect brand values will prevent transactions from being processed.Do APMs require redirection?
Yes, customers are redirected to the payment provider and returned after payment completion.Are payment logos configurable?
Yes. Logos shown in Shopify checkout are controlled via Shopify settings.
By default, multiple logos may be displayed—merchants should only enable supported payment methods.Are recurring or instalment payments supported?
No, recurring and instalment payments are not supported.
Troubleshooting
APMs not visible in checkout
- APMs not enabled in app or Payments Orchestration Platform
- Incorrect platform brand configuration
- App setup incomplete
Transactions not created or rejected
- Plugin functionality not enabled
- Missing or incorrect credentials
- Required fields not configured in Shopify
Connector requires additional fields
- Some connectors require additional parameters (e.g., region, customer data)
- Missing fields will cause transaction failures
- Merchants should verify Shopify supports required fields before setup
Redirection not working
- APM configuration incomplete
- Provider or Payments Orchestration Platform setup missing
Payment fails after redirect
- Invalid provider credentials
- Region/currency mismatch
Webhook not updating transaction status
- Webhook not configured in Payments Orchestration Platform
- Incorrect decryption key
- Endpoint not reachable
APM visible but disabled
- Unsupported region/currency
- Not enabled in Payments Orchestration Platform
Refund / capture / reversal not working
- Must be triggered from Shopify order flow
- Available only if supported by the connector
Resources
- Installation guide (PDF): Shopify installation/user guide
- Marketplace listing: APMs by ACI Worldwide
- Demo storefront (test environment): https://aciembedded.myshopify.com/ (access details available from your account manager)
After installing the plugin:
- Configure the plugin inside Shopify
- Configure merchant accounts, brands, and APMs in Merchant Portal
- Ensure all connector‑specific setups (e.g., APM parameters) are completed
Get support
If you need help with installation, configuration, or troubleshooting, contact H24 with:
- Shopify store domain
- Environment (UAT/Production)
- Timestamp and transaction reference (Order ID + payment reference)
- Steps to reproduce + screenshots