Cash on Delivery in IBM Sterling OMS: From Order Creation to Payment Settlement

Supporting Cash on Delivery in IBM Sterling OMS

Cash on Delivery (COD) remains one of the most widely used payment methods in many e-commerce markets. While IBM Sterling OMS provides a flexible payment framework, implementing an end-to-end COD payment lifecycle requires additional integration across multiple systems.

This article demonstrates how we implemented a complete COD workflow across IBM Sterling OMS, a Warehouse Management System (WMS), and a Transport Management System (TMS)—from order creation to payment recording after the driver collects the cash.

Solution Architecture

Four systems, connected through a stateless Java middleware:

• IBM Sterling OMS— order management, payment configuration, payment recording
• WMS — pick, pack, ship
• TMS — delivery routing, driver app, cash collection confirmation
• Java Middleware — the integration hub: detects COD, creates delivery orders, records payments

The middleware runs on IBM Cloud Code Engine (stateless, scale-to-zero) — all state lives in the external systems, never in memory.

The End-to-End Flow

• Order is created with COD payment
• OMS schedules and releases it
• WMS picks, packs, and completes fulfillment
• Once the WMS operation completes, the middleware detects the COD payment type and creates a TMS delivery order with the COD amount and configuration
• The driver delivers, collects cash, and marks "COD Collected" in the app
• A TMS webhook hits the middleware, which pulls the amount from TMS and the PaymentKey from OMS, then calls recordExternalCharges followed by requestCollection
• OMS payment status flips to PAID
  

Step 1: OMS Payment Configuration

Configure the Payment Rule with Authorization Required disabled, since Cash on Delivery payments do not require payment authorization. Enable Settlement Required so OMS can complete the payment settlement after the cash is collected.

The Publish Invoice setting can be configured as either At Creation or At Collection.

Payment Type. Three settings matter here:

• Processing Not Required — checked. This is the one that matters most: it tells the Payment Collection Agent to skip gateway calls for cash.
• Charge Instead Of Authorize — unchecked. If checked, the agent auto-charges on invoice generation, marking the order "paid" before the driver has actually collected anything.
• Charge Consolidation Allowed — checked, for one charge transaction per order instead of per shipment.

Step 2: Handling Existing Payment User Exits

If your implementation already includes a custom YFSCollectionOthersUE Payment Interface for an existing payment gateway, it may intercept all "Other" payment transactions—including Cash on Delivery (COD).

To avoid this, add a payment type check. Card payments continue through the existing gateway flow, while COD payments simply return null, allowing OMS to bypass the custom payment interface. The payment is then recorded later using recordExternalCharges.

Step 3: Order Creation

When creating a COD order using the createOrder API, ensure that PaymentReference1 is not empty. If this field is left blank, OMS silently sets IncompletePaymentType="Y", which prevents all downstream payment operations—including recordExternalCharges.

The payment progresses through the following lifecycle:

AWAIT_PAY_INFO
        ↓
AUTHORIZED
        ↓
(Shipment & Invoice)
        ↓
Cash Collected
(recordExternalCharges + requestCollection)
        ↓
PAID

Step 4: Detecting COD Orders After Fulfillment

The middleware identifies COD orders once the WMS operation completes. A webhook fires to the middleware, which queries IBM Sterling OMS to determine the order's payment type.

The detection flow is straightforward:

Using the getOrderDetails API, the middleware retrieves the PaymentType to determine whether the order is COD or prepaid.

If the order is a COD order, the middleware creates a delivery order in the TMS using a COD-specific configuration. This includes the collection amount and a collect_cod activity that enables the driver to record the cash collection during delivery. For prepaid orders, the middleware creates a standard delivery order, with no payment collection required.

Step 5: Payment Recording

When the driver marks the delivery complete, a webhook fires and the middleware records the payment.

COD amount. The middleware retrieves the COD amount from the TMS.

PaymentKey. The middleware retrieves the corresponding PaymentKey from IBM Sterling OMS using the getOrderDetails API.

Recording and finalizing. Two API calls in sequence:

• recordExternalCharges records the charge.

• requestCollection then triggers the Payment Collection Agent to reconcile the charge with the invoice and finalize the payment status to PAID.

Final Outcome

The final result is a fully automated Cash on Delivery payment workflow. Once the driver collects the cash, IBM Sterling OMS records the payment and updates the payment status to Paid. The Order Hub reflects a completed payment with the collected amount matching the invoiced amount and a complete payment audit trail.

This approach keeps the solution aligned with the standard IBM Sterling OMS payment APIs while avoiding changes to the OMS core.

How have you implemented Cash on Delivery in IBM Sterling OMS? Have you leveraged the standard recordExternalCharges API, or did your use case require a custom Payment Type Interface? Share your experience and lessons learned in the comments.