Order approval touchpoint

The order approval touchpoint feature enables a merchant to manually accept or reject an order in the Order Management System (OMS). This validation check is very useful when there are required external validations that have to be fulfilled to continue with the normal flow of the order.

For example, a manual fraud review department, or a governmental organization, demands that all ecommerce transactions have to be reviewed by them. If this feature is enabled, it allows the merchant to request an external approval by this department to continue the normal order flow.

As you can see in the Order flow topic, this validation occurs when the order status is ON_HOLD.

You can only enable the order approval touchpoint functionality at the order level. When the validation is enabled, the order remains in an ON_HOLD order status with a PENDING_EXTERNAL_VALIDATION order status reason. When the external system approval is completed the system will place the order back in the flow to complete the order process.

Enable order approval touchpoint functionality

To enable the order approval touchpoint functionality activate the Enables Order External Validation option in your System Integrator (SI) Portal, in Config > Sales Channel > Order > Order Flow Configurations.

These definitions are enabled and configured in your System Integrator (SI) Portal, which is not yet accessible externally. Contact Magento Support for assistance.

Validate an order

The ability to implement an external validation in your order flow allows the OMS to hold back an order until an integration, based on the merchant’s order flow configuration , approves or rejects the order.

You can configure this in your SI Portal, defined at the sales channel level, to provide flexibility to release orders into the order flow when external approvals are not needed. The OMS will hold back any order and send a magento.external.validation_management.validate message to the integration responsible for handling the order approvals.

Example of a validate message

{
    "validationPoint": "OrderValidation",
    "sales_channel_id": "000001",
    "order_id": "67898765456"
}

When this validation is enabled, the order remains in an ON_HOLD order status with a PENDING_EXTERNAL_VALIDATION order status reason. When the external system approval is completed the system will place the order back into the flow to complete the order process.

Add custom attributes

It is recommended that the OMS approves applicable custom attributes to continue with the normal order flow. The confirmation of the magento.sales.order_management.update_custom_attributes message should contain the applicable attributes set to TRUE.

Example of an update_custom_attributes message

{
    "custom_attributes_modification": {
        "custom_attributes": [
            {
                "name": "approval_stage_b2b",
                "value": "true"
            }
        ],
        "order_id": "67898765456",
        "sales_channel_id": "000001",
        "user": "automatic_approval_extension"
    }
}

To modify any custom attributes set the Update Custom Attributes configuration option to TRUE in your System Integrator (SI) Portal, located in Sales Channel > Postsales > Order Modifications .

This step is not mandatory, but it is a recommended best practice. Normally, the validate command can function as a standalone step, but adding specific custom attributes that need to be validated, or set to TRUE, provides an added value and quality to this feature. As mentioned earlier, contact Magento Support for assistance.

The merchant that integrates this validation for the order, has to send either an accept or reject message so the order can continue its normal flow.

Example of a validation_management.accept message

{
    "validationPoint": "OrderValidation",
    "sales_channel_id": "000001",
    "order_id": "67898765456",
    "comment": "Governmental document that approves this sale is : KBF78787666"
}

Example of a validation_management.reject message

{
    "validationPoint": "OrderValidation",
    "sales_channel_id": "000001",
    "order_id": "67898765456",
    "comment": "Governmental document that rejects this sale is : KBF78787666"
}

When all of the approval_stage attributes are set to TRUE, the order continues on with the flow. For more information, see Validation flow.

Add traceability

You can add traceability to these orders so that customer service agents can enable the ability to add comments or messages to a specific order with the magento.sales.order_management.create_comment message.

Example of the create_comment message

{
    "order_comment": {
        "comment": "The order manual check due to the huge order total has been assigned to the customer service agent XXXXX. This process takes between 24-48 hours",
        "created_date": "2018-03-07T06:33:59-08:00",
        "order_id": "67898765456",
        "sales_channel_id": "000001",
        "user": "CSRXXX"
    }
}