Split payment POC step-by-step implementation guide

This page is your implementation checklist. It assumes you have already watched the overview and the full demo, and that your Commerce site and App Builder project are both ready. The individual tutorial pages contain full detail for every topic below — use this page to know what to do and in what order.

Before you start

Confirm all of the following before running any prompt or command. The prerequisites and setup page covers each item in detail.

Commerce side

App Builder side

If anything above is missing, stop here and complete it first.

Phase 1 — Build the Commerce module

What this does: Generates the Client_SplitPayment PHP module that handles the checkout UI, store credit application, REST endpoints, and the I/O event subscription. This is the thin in-Commerce adapter — all operator workflow stays in App Builder.

Step 1.1 — Customize the prompt for your project

Open the Commerce module AI prompt page and note the following before you copy the prompt:

Step 1.2 — Run the prompt

Copy the full prompt from PROMPT START to End of prompt and paste it into Cursor (with Claude) or directly into Claude. Run it from the root of your Commerce project so the AI can create files under app/code/.

Step 1.3 — Enable and install the module

Run these commands from your Commerce project root:

bin/magento module:enable Client_SplitPayment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Step 1.4 — Verify the module installed correctly

# Confirm the module is active
bin/magento module:status Client_SplitPayment

# Confirm the split_ columns were added to sales_order
mysql -u <user> -p <dbname> -e "DESCRIBE sales_order;" | grep split

You should see five columns: split_store_credit_amount, split_cash_amount, split_cash_status, split_sc_invoice_id, and split_cash_invoice_id.

Then confirm in a browser that the split payment fields appear at checkout when a logged-in customer with store credit selects Cash as the payment method.

Phase 2 — Configure environment variables

What this does: Prepares the credential files used by the App Builder orchestrator, the simulation script, and (optionally) the Experience Cloud UI extension. The same four OAuth values from your Commerce integration are used in every .env file.

Refer to the environment variables reference for the complete list of variables per component.

Step 2.1 — Create the orchestrator .env

In your split-payment-orchestrator/ directory:

cp .env.example .env

Fill in every value:

Step 2.2 — Create the simulation script .env

cp commerce-backend-ui-1/.env.simulation.example commerce-backend-ui-1/.env.simulation

Fill in COMMERCE_BASE_URL and the four OAuth values (same credentials as above).

Phase 3 — Build the App Builder orchestrator

What this does: Generates the split-payment-orchestrator App Builder project: the payment-orchestrator I/O Event consumer, the payment-accept and payment-decline web actions, and the demo-dashboard operator UI.

Step 3.1 — Run the orchestrator prompt

Open the App Builder orchestrator AI prompt page. Copy the full prompt and run it from the split-payment-orchestrator/ directory.

Step 3.2 — Install dependencies and deploy

cd split-payment-orchestrator
npm install
# Confirm .env is filled in (from Phase 2, Step 2.1)
aio app deploy

After deployment, aio app deploy prints the action URLs. Note the demo-dashboard URL — you need it in Phase 4.

Step 3.3 — Confirm the event registration

In Adobe Developer Console, open your App Builder project workspace. Under Events, confirm that the Split payment — sales order place before registration exists and is bound to the payment-orchestrator action.

Phase 4 — Test the complete flow

Work through the verification steps in order. The testing and verification guide has the full curl commands, simulation script usage, and troubleshooting reference for each step below.

Step 4.1 — Verify REST endpoints are routable

# Expect 401, not 404 — the endpoint exists but requires auth
curl -X POST https://your-store.example.com/rest/V1/split-payment/orders/1/cash-received

Step 4.2 — Test the checkout UI

Step 4.3 — Test the threshold guard

Add products totaling more than $100, proceed to checkout, select Cash, and attempt to place the order. The error "Payment could not be processed. Please try again or contact support." must appear.

Step 4.4 — Place a test split payment order

Build a cart under $100, enter a cash/store credit split, and place the order. In Commerce Admin, confirm:

If no App Builder comments appear, check logs with aio app logs before continuing.

Step 4.5 — Test accept via simulation script

# Find your order's entity_id
node commerce-backend-ui-1/scripts/simulate-split-payment.mjs list

# Accept the payment
node commerce-backend-ui-1/scripts/simulate-split-payment.mjs accept <entity_id>

In Commerce Admin, confirm:

Step 4.6 — Test decline via simulation script

Place another test order, then:

node commerce-backend-ui-1/scripts/simulate-split-payment.mjs decline <entity_id>

Confirm order status is canceled and split_cash_status is declined.

Step 4.7 — Test the demo dashboard

Open the dashboard URL from Step 3.2. With a pending order in the system:

Phase 5 (optional) — Add the Experience Cloud UI extension

This phase embeds the operator dashboard into the Commerce Admin shell instead of using the standalone demo-dashboard. Skip this phase if the standalone dashboard meets your needs.

Step 5.1 — Review the prerequisites

The Experience Cloud UI extension requires IMS credentials in addition to the OAuth integration values. Read the Experience Cloud UI extension AI prompt page before running the prompt, paying attention to the OAUTH_CLIENT_ID and related IMS variables.

Step 5.2 — Run the UI extension prompt

Copy the full prompt from PROMPT START to End of prompt and run it from the commerce-checkout-starter-kit/ directory.

Step 5.3 — Deploy

cd commerce-checkout-starter-kit
npm install
cp .env.dist .env
# Fill in IMS credentials and COMMERCE_INTEGRATION_* credentials
aio app deploy

Quick troubleshooting reference

For full troubleshooting details, see the testing and verification guide.

All resources in this series

Reference resources