Split payment POC: testing and verification guide

This guide walks you through verifying that every component works correctly, in the order they should be tested. Start from the bottom (Commerce module) and work up (App Builder).

Step 1 — Verify Commerce Module Installation

After running bin/magento setup:upgrade and bin/magento setup:di:compile:

# Confirm module is enabled
bin/magento module:status Client_SplitPayment

# Confirm db_schema columns were added
bin/magento doctrine:schema:validate
# or check directly:
mysql -u <user> -p <dbname> -e "DESCRIBE sales_order;" | grep split

Expected output: four columns starting with split_ visible in sales_order.

Step 2 — Verify Commerce Admin Configuration

In Commerce Admin:

Step 3 — Verify REST Endpoints Are Accessible

Use curl to confirm the endpoints respond (they will reject unauthorized requests, but a 401 confirms they’re routed correctly):

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

# Should return 200 or session-based response — anonymous endpoint
curl -X POST https://your-store.example.com/rest/V1/split-payment/set \
  -H "Content-Type: application/json" \
  -d '{"storeCreditAmount": 0, "cashAmount": 0}'

Step 4 — Test the Checkout UI

Test validation:

Step 5 — Test Threshold Guard

Step 6 — Place a Test Split Payment Order

After order placement, verify in Commerce Admin:

If no App Builder comments appear: Check App Builder action logs with aio app logs. The event may not have fired or the action may have an error.

Step 7 — Test Accept via Simulation Script

The simulation script is the fastest way to test the accept/decline flow without the full operator UI.

cd commerce-checkout-starter-kit
cp commerce-backend-ui-1/.env.simulation.example commerce-backend-ui-1/.env.simulation
# Edit .env.simulation with your credentials

# List recent orders (find your test order entity_id)
node commerce-backend-ui-1/scripts/simulate-split-payment.mjs list

# Show split payment fields for a specific order
node commerce-backend-ui-1/scripts/simulate-split-payment.mjs show 42

# Accept the cash payment
node commerce-backend-ui-1/scripts/simulate-split-payment.mjs accept 42

After accept, verify in Commerce Admin order view:

Step 8 — Test Decline via Simulation Script

Place another test order (same setup as Step 6), then:

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

After decline, verify in Commerce Admin:

Step 9 — Test the Demo Dashboard

After deploying the split-payment-orchestrator, aio app deploy prints the action URLs.

Open the demo-dashboard URL in a browser:

https://[runtime-host]/api/v1/web/split_payment_orchestrator/demo-dashboard

If DEMO_UI_SECRET is set:

https://[runtime-host]/api/v1/web/split_payment_orchestrator/demo-dashboard?secret=<your-secret>

With a pending order:

Step 10 — Test App Builder Action Logs

# Follow logs in real-time
aio app logs --tail

# Or view last invocations
aio runtime activation list --limit 10
aio runtime activation logs <activation-id>

For the payment-orchestrator, look for:

[INFO] Split payment orchestration finished { orderId: '42' }

For payment-accept or payment-decline:

[INFO] Cash payment accepted on Commerce via REST { orderId: '42' }

Common Issues and Fixes

“The signature is invalid” from Commerce OAuth

Cause: Clock skew between App Builder runtime and Commerce, or an OAuth signing bug.

Fix:

Split payment fields not appearing in checkout

Cause: LayoutProcessorPlugin injection paths don’t match your checkout layout.

Fix:

Store credit not applying / “Payment could not be processed” at place order

Cause: Usually one of the edge case plugins not working correctly.

Check:

App Builder action receives event but orderId is missing

Cause: The io_events.xml field list doesn’t include entity_id, or the event payload shape changed.

Fix:

Orders don’t show in demo dashboard

Cause: Commerce REST orders search criteria not returning orders, or split_cash_status field not in the REST response.

Fix:

Verification Checklist

All resources in this series

Reference resources