Understanding and Configuring Order Payment References for Stripe
When a sales order is retrieved from an eCommerce platform, CSM creates a record in Business Central called a “CSM order” that contains the raw data for that order. A CSM order may have one or more “order documents” that represent the different types of information that may be retrieved or sent between Business Central and the eCommerce platform for that order. As part of the order retrieval process, a CSM order document for that order’s payment information will be created. Included in this information is a “credit card external reference” number:
The entry in this field is the unique identification number that was assigned to the payment on the external platform.
This field is critical to the CSM-CPM Connector because it is used to associate a CSM order to a corresponding Stripe transaction. The CSM-CPM Connector will compare the value in this field to the CPM payment requests that have been retrieved from Stripe to determine which CPM record should be linked to the related sales order.
The value in this field is determined by a metadata key mapping in the related sales channel’s CSM API function for order retrieval. By default, this value is set to _payment_intent_id, and for most scenarios, this default value will properly link a retrieved CPM payment to a CSM order. In some situations, however, it may be that a different metadata key mapping is used:
- An unknown payment plug-in is installed on the eCommerce platform.
- Payment reference changes are made to an already-installed payment plug-in, resulting in breaking functionality.
In such a scenario, you must identify the proper payment reference metadata key and instruct CSM to use this key when determining an order’s external reference number:
- Retrieve an eCommerce order into Business Central via CSM.
- Choose the icon, enter CSM API Messages, and then choose the related link.
- Open the API message that was just created for the order retrieval.
Note: some platforms may execute multiple API functions as part of the order retrieval process. You may need to review more than one API message in order to obtain the necessary data.
- Choose the Related ribbon, then choose the Message Data Buffer
- On the CSM API Data Buffers page, locate a value beginning with pi_. This is the Stripe payment intent and represents the external payment number.
- Copy the value in the row that immediately precedes the payment intent. This syntax is used to identify Stripe payment intents.
- Choose the icon, enter CSM Sales Channels, and then choose the related link.
- Open the sales channel for which you are retrieving sales orders.
- On the Order Management FastTab, paste the value you copied into the Payment Reference No. Metadata Key
Note: you may need to choose the Show More action on the Order Management FastTab in order to see this field.
When CSM retrieves orders for the sales channel, it will use the value in this field to identify Stripe payment intents.
For example, in the screenshot below, we have opened the data buffer for an order retrieval API message and located a line with a pi_ value. Directly above this is a line with the syntax _stripe_intent_id. We would copy this value and then paste it into the Payment Reference No. Metadata Key field on the related sales channel card.
