When you develop with the Montonio API to create Orders, you will encounter the required merchantReference parameter.
For each Order that you create in Montonio, you must provide a unique value for the merchantReference parameter. This uniqueness is enforced in the scope of one Store.
The value is supposed to be your Order ID. As a merchant, you likely keep track of your orders with some unique reference number. In many e-commerce platforms (like WooCommerce, PrestaShop, and Magento), this is the Order ID. You should simply pass your Order ID to Montonio in the merchantReference parameter of the POST /orders request.
Here are some examples of how Order IDs can look like:
123456
ORD-EE1234
RHJSWIKDL
907f07f9-5cd9-43f9-98ca-f79e2b274726
It doesn't have to be called Order ID in your system. It can also be Cart ID, Session ID, Invoice Number, or any other unique value identifying the payment session.
When we notify you about successful payments via webhook notifications, we also send you back the merchantReference you provided. This helps you further match and validate which order was paid for. merchantReference is used in addition to the Montonio Order UUID, which we give you as a response to the POST /orders call.
⚠️ What if I provide the same merchantReference for two different orders?
You should send us a unique merchantReference for each order. If you send us the same merchantReference, we will reuse an existing order.
If the order has not yet been paid for, we will replace the details of the order (including the amount) and give you a new payment URL, allowing the customer to pay for the same order with new details.
If you change the amount (grandTotal) of the order, please create a new order, instead of reusing an existing one. Reusing orders while changing the amount may allow your customers to complete orders by paying a smaller amount than intended.
However, if an order with this merchantReference has already been paid for, the API will throw an error.
🔍 But I don't have Order IDs
If you don't have a unique ID for the current user's payment session or order, you should create one. You will need a unique ID to identify the customer's payment session regardless of which payment gateway you use.
If you truly don't want to create IDs for your sessions, you may pass us a freshly generated v4 UUID with each order. However, in this case, you need to save that UUID to your database, to later match our webhook notifications to sessions. Alternatively, for matching orders later, you may use our Order UUID which we give you in the response of the POST /orders endpoint.
❓ Why do I need to pass my Order ID to Montonio?
We require you to send us your Order ID mostly to provide a good user experience to you and your customers.
For merchants, we display the merchantReference or Order ID in our Partner System and in the order exports you get from the Partner System. This makes it easier for you to search for orders in Montonio and for your accountants to match incoming payments to orders in the exports.
For customers, we display the merchantReference in the payment gateway, in the payment descriptions, and in other relevant places. This makes it easier for your customers to see which orders they are paying for, and look the payments up later in their bank account statements.