Split payment POC: prerequisites and environment setup

Complete every step in this tutorial before you run any of the build prompts. Missing a single step is the most common reason the flow breaks mid-tutorial.

1. Adobe Commerce requirements

Commerce Cloud only: enable I/O eventing

Add the following to .magento.env.yaml and deploy before you add the module:

stage:
  global:
    ENABLE_EVENTING: true

Warning: This deploy must finish successfully before the I/O Event module dependency can resolve.

2. Commerce Admin configuration

Do these steps before anything else. The checkout JavaScript depends on exact string matches.

2a. Enable Cash on Delivery with the exact title

Stores > Configuration > Sales > Payment Methods > Cash On Delivery Payment

Note: If your store uses a different cash-on-delivery (COD) implementation or title, adjust payment-method-helper.js in the Commerce module.

2b. Enable store credit

Stores > Configuration > Customers > Customer Configuration > Store Credit Options

2c. Add store credit to your test customer

Customers > All Customers > [your test customer] > Store Credit > Update Balance

Add at least $50 in store credit. You will test with an order under $100 total.

2d. Create the Commerce integration

System > Integrations > Add New Integration

Select Save, then Activate.

Copy all four values; they are only shown once:

Store these values securely. You need them in every App Builder .env file.

3. Adobe Developer Console and App Builder

The event code used in the proof of concept is: com.adobe.commerce.observer.sales_order_place_before

If you have not connected Commerce as an event provider, see Configure Commerce to emit events to Adobe I/O in the Commerce Extensibility guide.

4. Local development environment

# Required versions
node --version    # 18.x or later
npm --version     # any recent version

# Adobe I/O CLI
npm install -g @adobe/aio-cli

# Authenticate
aio login

# Select your project and workspace
aio app use
# Confirm the org, project, and workspace shown are correct

5. Two project directories to know

This tutorial uses two separate directory roots. Keep them separate.

Commerce project root (your Magento git repository):

<commerce-root>/
└── app/code/Client/SplitPayment/   ← Module goes here

App Builder project root (the split-payment-orchestrator folder from the source package, or a new project you create):

split-payment-orchestrator/
├── app.config.yaml
├── package.json
├── .env                            ← Copy from .env.example, then fill in
└── actions/

6. entity_id compared to increment_id

Always use entity_id (the numeric database ID), not increment_id (for example 000000042), in REST calls.

Find entity_id from the Commerce Admin order URL:

/admin/sales/order/view/order_id/42/   →   entity_id = 42

Or from the simulation script:

node scripts/simulate-split-payment.mjs show 42

7. The $100 threshold

The split payment UI and threshold guard target orders $100.00 or less. The flow behaves as follows:

To test, build a cart whose subtotal, shipping, and tax are less than or equal to $100 (for example, a product under $90 so shipping and tax still fit under the cap).

The threshold is stored in:

8. Fastly (Commerce Cloud only)

App Builder actions call Commerce over REST (/rest/V1/split-payment/orders/...). If your Commerce Cloud project uses Fastly with IP allowlisting, the App Builder runtime egress IP addresses must be allowlisted.

How to check: Run the simulation script first (direct curl with OAuth signing). If that works but the App Builder action returns 403, Fastly is likely blocking the request.

Use Adobe’s current documentation for App Builder egress IP ranges and add them to your Fastly configuration as needed.

Verification checklist

Before you start the build prompts, confirm the following:

All resources in this series

Reference resources