Shopify Embedded Cards

Last updated: October 30, 2026

Overview

Our Shopify Embedded Cards Payment Plugin enables merchants to deliver a fully native, secure, and frictionless card‑payment experience directly inside Shopify Checkout.
Built on a server‑to‑server architecture, the solution eliminates redirects, hosted payment pages, and WestpayAPI widgets, ensuring customers complete their card payments entirely within the Shopify environment.

This architecture enables:

  • A seamless, embedded checkout journey
    Customers remain in Shopify Checkout, boosting trust and reducing abandonment.

  • Secure, compliant handling of card data
    Card details are encrypted within Shopify and securely decrypted on the platform side, minimizing PCI exposure for merchants.

  • Support for 3D Secure and advanced card flows
    Authentication and issuer‑required steps are orchestrated server‑side for reliability and control.

  • Deep integration with the Payments Orchestration Platform
    Access routing, tokenization, notifications, fraud services, and payment lifecycle controls from a unified platform.

For merchants upgrading from redirect‑based flows or adopting embedded checkout for the first time, the Embedded Cards Plugin offers a faster, more secure, and conversion‑optimized way to accept major card brands in a fully native Shopify experience.

Looking for the step-by-step journey (prepare, install, configure, test, go live)? See the Shopify Embedded Cards overview on the Shop Plugins page. This page contains the detailed reference.

↑ Back to top

Compatibility

Our plugin supports the following versions:

  • Node 18
  • Remix 2.7.1
  • React 18.2
  • Prisma 5.12

↑ Back to top

Before you start

Create/confirm your Merchant Portal account & access

  • Ensure you have access to the Payments 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
  • Enable Shop plugins for your entity via support channel
  • Enable Automatic brand detection from Merchant Portal - Processing->Settings->Activate automatic Brand Detection

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).

↑ Back to top

Install

Marketplace listing: open in the Shopify App Store.

Option A — Shopify App installation

  1. Shopify Admin → Apps
  2. Locate ACI Worldwide Card Payments
  3. Click Install
  4. Approve permissions

Option B — Private/Custom distribution

  1. Use the installation link/package provided by us
  2. Install via Shopify Admin → Apps
  3. Verify the plugin appears in your payment settings

↑ Back to top

Configure

Configuration in Shopify Admin

  1. Go to Apps on the left navigation.
  2. Find ACI Worldwide Card Payments in the list of installed Apps to be redirected to the Payment Configuration page.
  3. 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)
    • Any additional required fields (OPP params, locale, etc.)
    • Webhook decryption Key (you will get the same when you configure webhooks/notifications in merchant portal)
  4. Save
  5. On successfully saving the configuration, you will see a “Return to Shopify” button on the top of the page. Click it.
  6. You will be redirected to the Payment settings page of Shopify. Enable Test mode (if required) and click on the Activate button.
  7. Please note that while activating the App, as default, all payment logos will be enabled. Please select only those you plan to process and disable the rest. You can further change it in APP - Shopify Admin → Settings → Payments (ACI Payment app enabled), Click Manage under ‘Credit Card Payments by ACI Worldwide"

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 Open Payment 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 Open Payment 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
Webhook Decryption Key Mandatory Configure webhook decryption key obtained while setting up the webhook. Follow Webhook section.
Use Store Locale NA Optional
Store URL Recommended Enter a fully qualified store URL. It is required as part of the scheme mandates if it is not configured, or cannot be configured, in the Merchant Portal's account configuration.
Card Settings - Enable 3DS NA Optional Enable 3DS for transaction processing; prior 3DS configuration in the Merchant portal is required.
System Settings NA Optional Enable 3DS for transaction processing with new enhanced 3DS flow implemented in the Shopify app (Recommended); prior 3DS configuration in the Merchant portal is required.
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)
Test Card Details NA NA

This is available for testing purposes only, enabling merchants to test various card numbers. Provide the required card details for the selected test scenario.

Possible values for the brand field are:

  • visa
  • visaelectron
  • maestro
  • mastercard
  • amex
  • dinersclub
  • discover
  • unionpay
  • jcb
  • elo
  • dankort
  • cartes_bancaires
  • forbrugsforeningen
  • hipercard
  • laser
  • bancontact
  • girocard

↑ Back to top

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 Open Payment Platform.

Steps to configure webhooks

  1. Log in to the Open Payment Platform
  2. Select your division (e.g., OPP_Division)
  3. Navigate to Administration → Webhooks
  4. Click Add New Webhook
  5. Configure as follows:
FieldValue
URLhttps://<your-domain>/acipayment/process/notification
Notification TypesSelect as required for your business
Fields to IncludeSelect as needed
Secret for EncryptionCopy this value and paste in Shopify under Webhook Decryption Key
Wrapper for Encrypted NotificationJSON
EmailsAdd email addresses for notification alerts

Figure 1: Webhooks overview (Administration → Webhooks)

Shopify Embedded Cards: Webhooks overview (Administration → Webhooks)

Figure 2: Add Webhook dialog

Shopify Embedded Cards: Add Webhook dialog

Important: If you have access to the onboarding APIs for the Merchant Portal, you can set up webhooks via API in the portal and configure the Shopify app with the obtained decryption key.

Follow the documentation for the onboarding API for Webhooks.

↑ Back to top

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

  1. Disable Test mode in Shopify Payment setting
  2. Replace UAT credentials with Production credentials
  3. Run a low-value live transaction to validate end-to-end
  4. 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).

↑ Back to top

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

↑ Back to top

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: Shopify Payments settings – app in test mode

Shopify Embedded Cards: Shopify Payments settings – app in test mode

Figure 4: Test mode setting in Shopify

Shopify Embedded Cards: Test mode setting in Shopify
  • Payment app configuration screen (credentials/environment)

Figure 5: App configuration – General, Card, System and OPP parameter settings

Shopify Embedded Cards: App configuration – General, Card, System and OPP parameter settings
  • On Shopify Checkout 

Figure 6: Shopify checkout – credit card payment

Shopify Embedded Cards: Shopify checkout – credit card payment

↑ Back to top

Features

Payment types

Payment TypeSupportedComments 
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 integration to present payment options to your shoppers 

FeatureSupportedComments
Supported Brands✔

VISA, VISAELECTRON, MASTER, MAESTRO, AMEX, DINERS, DISCOVER, UNIONPAY, JCB, CARTEBANCAIRE, DANKORT, ELO, FORBRUGSFORENINGEN, HIPERCARD, LASER, BANCONTACT, GIROCARD

Note: Availability of these brands is subject to availability on the respective connector.

Supported Payment Methods✔

CC

Countries✔
All Shopify‑supported countries
Authorization Currencies✔ALL supported by Shopify
Late Notification✔

Payment Facilitator

–Can be supported if the connector has its own configuration for PayFac
Recurring/Subscription –
Reference ID✔
Timeout Autoreversal–

Supported based on the connector functionality

TLS 1.2✔
Server-Server Integration✔
Shopify Embedded Experience✔
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. 

WestpayAPI OneClick Checkout (Save Card)–
WestpayAPI widget or full-page redirect–
Customization through standard WestpayAPI JS–using wpwlOptions
Customization through standard WestpayAPI CSS–using wpwlOptions
PayByLink–
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✔

↑ Back to top

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 the ones that 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.

Note: If you want to send additional fields as custom parameters or static values, see the Configure section on how to configure custom parameters and additional OPP fields.

OPP Field NameShopify Field
entityIdDerived from Admin
amountamount
currencycurrency
paymentTypekind
paymentBrandWill derive from payment_method object
testModeAdmin derived
merchantTransactionIdid
customer.merchantCustomerIdNot available
customer.givenNamebilling_address.given_name
customer.surnamebilling_address.family_name
customer.phonecustomer.phone_number
customer.mobilecustomer.phone_number
customer.emailcustomer.email
customer.birthDateNot available
customer.ipNot available
billing.street1billing_address.line1
billing.street2billing_address.line2
billing.citybilling_address.city
billing.statebilling_address.province
billing.postcodebilling_address.postal_code
billing.countrybilling_address.country_code
billing.houseNumber1Not available
shipping.street1shipping_address.line1
shipping.street2shipping_address.line2
shipping.cityshipping_address.city
shipping.stateshipping_address.province
shipping.postcodeshipping_address.postal_code
shipping.countryshipping_address.country_code
shipping.phoneshipping_address.phone_number
shipping.companyNameshipping_address.company
cart.items[0].nameitem name
cart.items[0].merchantItemIdNot available
cart.items[0].quantity1
cart.items[0].skusku
cart.items[0].priceCart Total
cart.items[0].currencyActual Currency should be mapped
cart.items[0].descriptionnull
cart.items[0].taxNot available
cart.items[0].totalAmountCart Total
cart.items[0].originalPriceNot available
customParameters[SystemName]Derive the values
customParameters[SystemVersion]Derive the values
customParameters[moduleName]Derive the values
customParameters[moduleVersion]Derive the values
shopperResultUrlDerive the values
AuthorizationGenerated through API
localemerchant_locale
encryptedTokenDerived
customParameters[3DS2_enrolled]Derived from Admin

↑ Back to top

FAQ

Installation

  • How do I install the credit card app?
    Shopify Admin → Apps → ACI Worldwide Card Payments → Install → Approve permissions.

  • Can I use private installation?
    Yes, via an installation link provided by us.

  • How do I confirm installation?
    The app should be visible under Apps and in Payment Settings.

  • Do cards and APMs use the same app?
    No, separate apps are required for credit cards and APMs.

Configuration

  • What credentials are required?

    • Entity ID (Client ID)
    • API Key / Client Secret
    • Webhook decryption key
    • Optional OPP parameters

  • Where is configuration completed?

    • Shopify Admin
    • Merchant Portal

  • How do I activate card payments?
    Save configuration → Return to Shopify → Activate payment method.

  • Is plugin enablement required?
    Yes. Transactions will not be processed unless plugin functionality is enabled.

  • What should always be validated before go-live?
    Always confirm:

    • Required brands are configured in the merchant portal
    • Merchant account is correctly attached
    • Credentials match the correct environment

  • Do connectors require additional fields?
    Yes. Some connectors require additional parameters.
    Merchants must verify Shopify supports and provides these fields.

  • Are recurring or instalment payments supported?
    No, recurring and instalment payments are not supported.

  • Are logos configurable?
    Yes. Displayed logos depend on Shopify settings and enabled payment methods.

Testing Behaviour (Important)

  • Why do I see static card and customer data during testing?
    Shopify may use static card and customer data during testing due to shopify platform limitations for credit card apps.

  • What is the recommended testing approach?
    Always validate flows in production (with controlled rollout) before full launch.

Troubleshooting

  • Card payments not visible in checkout

    • App not activated
    • Plugin not enabled
    • Configuration incomplete

  • Transactions not processed

    • Plugin functionality not enabled
    • Incorrect brand configuration
    • Merchant account not attached

  • Transaction fails or not authorised

    • Invalid credentials
    • Missing required parameters
    • Incorrect Open Payment Platform setup

  • Connector requires additional fields

    • Required parameters not passed from Shopify
    • Connector-specific fields missing

  • Transactions stuck in pending

    • Webhook not configured
    • Notification endpoint issue

  • Webhook not received

    • Missing Open Payment Platform webhook configuration
    • Invalid endpoint or decryption key

  • Test vs Live issues

    • Environment mismatch (credentials, accounts, configuration)

  • Refund / capture / reversal not working

    • Must be triggered from Shopify order flow
    • Supported only if connector allows these operations

↑ Back to top

Resources

After installing the plugin:

  • Configure the plugin inside Shopify
  • Configure merchant accounts, Credit Card Brands, and Merchant Account attachment in Open Payment Platform
  • Ensure all connector‑specific setups  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

↑ Back to top

See also