These payment transactions will be executed sequentially and automatically in the order in which they were represented in the X-LIST request. This means the processing of one transaction starts only after the previous one finished. This is mostly due to the fact that a 3DS Secure Customer Authentication (SCA) could be required after each step. With the "frictionless flow" introduced by 3DS 2.0 it should be unlikely that it's required for each step, but ultimately the issuing bank will decide upon this.
From a UX perspective your marketplace should provide transparency to the user by breaking down the purchase into the individual payment transactions that will occur on the so-called Status Page. After each transaction the user should be able to see the current status of the transactions there, to understand the progress and especially why they may be redirected another time, in case that happens.
A typical API sequence is shown in the following diagram, along with the user flow. The example is a single purchase which is made up of products from 2 merchants, M1 and M2. It assumes that the Hosted Payment Page is being used by the marketplace and shows the worst case of 2 consecutive SCA redirects. In case no SCA is required the redirect URL provided by optile will point to the marketplace's Status Page instead of the SCA page.
Note that status updates on the individual transactions will arrive in an asynchronous fashion at the marketplace system, in the form of status notifications. The frontend may therefore resort to active polling on the Status Page in order to proceed and lead the user through any potential SCA steps.
For a detailed specification of the API endpoints please see our Mixed Cart API Reference.
Note that once your system issued the X-CHARGE, the redirects required by the providers (typically due to 3D Secure) will be in the attributes list
payments[*].redirectToProvider of the X-LIST object. When initializing a HOSTED payment page in the very beginning the corresponding URL (typically to integrate within an iFrame) will be in the top-level attribute
Status notifications will be sent to the given callback URL of your system in analogy to classic notifications for the resulting payment transactions.
- They only notify about status changes of individual payment transactions (which correspond to classic CHARGEs). For X-LIST status changes there will be no notifications. This goes hand in hand with our recommendation to GET the X-LIST object on arrival of a notification to retrieve its latest status.
- Notifications in the marketplace context will have 2 additional query parameters:
merchant: the code of the merchant of this payment transaction as registered at the optile system.
sessionId: the ID of the X-LIST. Note that
shortId refer to the payment transaction, not the X-LIST.
- Your system may disregard any notifications with the parameter
entity=session. These are low-level sessions which have no actual relevance for the marketplace.
Since the queue of payment requests will be processed automatically once the X-CHARGE is invoked (for example from the hosted payment page), your marketplace does not trigger them one by one. The processing will continue until the queue was fully processed or an "interrupting error" occurs. This would stop automatic processing of the queue and put the X-LIST into the
Interrupting errors are:
- Explicit abort of the customer, for example on a SCA page
- Invalid card
- Lost or stolen card
- Risk checks
- Failed 3DS challenge (SCA)
Note, however, that this means that there are some cases when a payment was declined by a payment provider, but the processing of the queue will still continue. Insufficient funds, for example, will not halt the processing of the next payment transaction, in order to fulfill the purchase as far as possible, which could consist of unrelated items, such as a TV set and a perfume.
However, in certain situations this could lead to unfavorable results for the user. For example, the payment for an HDMI cable from one merchant could be approved, while the payment for a TV set from another merchant is declined. In this case probably the user wouldn't be happy with just the HDMI cable.
There are several approaches to avoid or mitigate such scenarios:
- Re-render the payment page from the same X-LIST object in order to allow the user to provide a new payment account. If another X-CHARGE is issued through that payment page on an existing X-LIST which contains failed or unprocessed transactions, the processing will be repeated / resumed with the new payment account.
- Order the payment transactions in the X-LIST according to their dependencies. If the first one gets rejected for risk reasons, the following ones won't be processed either.
- Ideally use deferred charges where you capture the funds at a later stage. Give the user the opportunity to cancel successfully preauthorized transactions of partially failed purchase in hindsight. You can then cancel the corresponding preauthorizations accordingly. Both, capturing and canceling are done through the classic OPG API of deferred charges (using the
longIds of the payment transactions, not the ID of the X-LIST).
- Cancel an X-LIST that came to a
stopped state by issuing an authenticated HTTP DELETE request on the X-LIST's URL such as
This does not trigger refunds but it makes sure that no X-CHARGE can be issued anymore and thus no further payment processing takes place.
- Be prepared to issue refunds when needed (using the
longIds of the payment transactions, not the ID of the X-LIST).
In any case your marketplace system will receive status notifications for each payment transaction individually to have full transparency. Also, it can always issue a GET on the X-LIST object, in order to receive the current status of all payment transactions contained in the purchase. The X-LIST itself also offers an aggregated status, see diagram below.
The status model of the X-LIST gives a good understanding of the course of actions and events that can occur while optile processes the queue of individual transactions. Please have a look at the following diagram to learn about the X-LIST statuses and the general mixed cart flow.
Note that this diagram is slightly simplified to represent the typical cases, while other status transitions may still be possible in certain edge cases. For your reference there is also a list of X-LIST statuses at the end of this page.