1.Introduction

IBM Sterling Order Management System (OMS) allows integration with external payment processing system that handle charges and authorizations asynchronously. When an external system completes a charge or authorization outside of OMS, it sends the payment processing response data back asynchronously. However, this transactional information is not automatically recorded in the OMS database (YFS_CHARGE_TRANSACTION table). To capture and persist this data, IBM Sterling OMS provides the recordExternalCharges API. This API enables the system to explicitly log external charge and authorization details by inserting corresponding entries into the YFS_CHARGE_TRANSACTION table. These records are linked to the appropriate order payment requests, ensuring that OMS maintain accurate payment related information.

2. API Key Functionality

The recordExternalCharges API in IBM Sterling OMS enables the system to capture and log payment related transactions processed by external systems.

It supports the following charge types:

Authorization: This API can create authorization record in OMS DB which is received from external payment processing system.

Charges: This API can create charge entries for both sales and return orders.

For sales orders, the charge amount is recorded as a positive value, representing the amount collected from the customer.

For return orders, the charge entry is recorded as a negative value, indicating that the corresponding amount has been refunded to the customer.

3. Scenario

3.1 Scenario for Charge Record Type

A customer places a sales order through the website, and the order is successfully fulfilled, meaning the product is delivered to the customer. Later, the customer decides to return the product and visits the nearest physical store to initiate the return. At the store, the return is processed immediately, and the customer receives an instant refund at the point of return.

Following this, the store sends the return order details to IBM Sterling OMS. However, since the refund was handled directly by the store and not initiated through OMS, the system has no internal record confirming that the refund was issued.

IBM Sterling OMS should invoke the recordExternalCharges API to record a negative charge amount in the YFS_CHARGE_TRANSACTION table. By this, OMS can accurately reflect the refund activity, even though the REFUND occurred outside its direct control.

Order Flow

Sales order has been created and fulfilled successfully. Order has been delivered successfully to the customer.

Sales order charge transaction details (YFS_Charge_Transaction).

The customer visits the physical store and returns the product directly. The store processes the refund immediately. Afterwards, the store system transmits the return order details to the Order Management System (OMS). Upon receiving the return data, OMS generates a corresponding return order. The return order has been created successfully in OMS.

The return order status is updated to “Received” in the OMS since the store has already received the returned product.

Close receipt process is completed to update the inventory in OMS.

Create invoice for return order.

The createOrderInvoice API generates a RETURN charge type entry with a negative amount. Additionally, custom logic is implemented on the Invoice ON_SUCCESS event to invoke the recordExternalCharges API only for Store return orders, which creates a CHARGE entry with a negative amount.

Once the invoice is successfully created, both RETURN and CHARGE entries are recorded in the YFS_CHARGE_TRANSACTION table for the associated sales order. This action helps prevent over refunding to the customer.

The custom logic is implemented on the Invoice ON_SUCCESS event because, once the invoice is created, a RETURN record is automatically inserted into the charge transaction table. If the Payment Collection Agent is running at that time, it may immediately create a charge record to refund the customer based on the RETURN entry. Therefore, the recordExternalCharges API is invoked immediately to insert a corresponding CHARGE entry, ensuring the net refundable amount is accurate and avoiding any over-refund to the customer.

Input:

YFS_CHARGE_TRANSACTION Table:

Invoke the requestCollection API to move all records to Checked status. No new charge record will be created, as the charge record corresponding to the return order total has already been created and is already in Closed status.

4.Conclusion

In conclusion, the recordExternalCharges API supports asynchronous payment processing, enabling Sterling to handle delayed responses while maintaining consistency across financial operations and ensuring data integrity throughout the transaction lifecycle. By using this API, IBM Sterling OMS can accurately reflect charge activity even when the transaction occurs outside of OMS.