Web Content Display

Payment Ecosystems

The purpose of Payment Ecosystems is to enable conversion-optimized cross-selling between its Sellers or Partner Merchants. There are different types of Ecosystems and in addition to that different "Provider Tokenization" types. This document aims to give a comprehensive overview about the resulting scenarios from a technical perspective.

However, as a Seller / Partner Merchant you often only have an interest in one particular scenario, which is provided by the Ecosystem you want to join. Therefore we want to make your life easier by providing high-level descriptions for some typical scenarios in the first section. So if you are a Seller / Partner Merchant you may continue with the following Seller / Partner Merchant Information.

If you would like to get a more comprehensive view on Ecosystem scenarios you could start reading further down with the Ecosystem Types.

Web Content Display

Seller / Partner Merchant Information

To become part of a Payment Ecosystem as a Seller / Partner Merchant technically you integrate to the Ecosystem Backend and/or to optile, the Payment Orchestration platform. This depends on 2 factors:

This is determined, or at least limited, by the Ecosystem you want to join, or more precisely, by the capabilities of its Ecosystem Backend. In this section we want to provide high-level descriptions for typical scenarios as an easy starting point for you. They link to more details further down in the documentation.

This documentation describes the end-to-end flows across all parties conceptually, and the optile APIs in detail, where needed.

For details on the API of the Ecosystem Backend please refer to the technical documentation of your Ecosystem Operator.

 

Web Content Display

Redirect Ecosystem with white-label Tokenization

As a Partner Merchant in a Redirect Ecosystem you profit from its conversion-optimized cross-selling capabilities as follows. After the customers made their first purchase, for example at an airline, your complementary offer can be presented to them. If they choose it, they get redirected to your site and then can opt-in to pay with the same payment data they have been using with the first merchant. So there is no need to enter their credit card details again and therefore optimizes user experience and conversion.

Together with a Pure Ecosystem Backend Integration and Provider Tokenization your implementation work is minimal, because you only integrate one simple API (of the Ecosystem Backend). You don't need a full PCI compliance (no plain card data goes through your systems) and you can keep using your existing Payment Provider (PSP or card acquirer). You don't even need to change your integration with them if you are using their APIs with tokenized cards already.

This scenario is for you, if:

  • You have an existing direct integration with Payment Providers you want to keep
  • You use Provider Tokens in these existing integrations

This is how it works technically:

  1. After the customer has clicked on your offer, they get redirected to your landing page. This redirect includes a customer reference, which your system keeps throughout the customer's shopping session that starts now.
  2. The customer shops and finally proceeds to checkout on your site.
  3. At this point your system calls the Ecosystem Backend with the customer reference it received earlier. As a response your system will get a URL which you integrate as an iFrame into your checkout page.
  4. In this iFrame the customers see a masked representation of their payment card and can opt-in to use this for the purchase at your site. Potentially they also have to type in their CVC for security reasons.
  5. After the customers submitted this information (all inside the iFrame, no implementation on your side) they get redirected to your finalization page. Potentially they also get redirected to a SCA page where they complete a 3D Secure challenge first, and then to your finalization page.
  6. When the finalization page is requested, your system uses the Operation ID that is contained in the redirect to contact the Ecosystem Backend and retrieve the card token issued by your own PSP or card acquirer and some meta data.
  7. Your system feeds this card token into your existing payment process, where it gets sent to your Payment Provider's API, and a feedback is presented to the customer as usual.

For further details please read about the integration of a Redirect Ecosystem in general, and the Provider Tokenization approach of a Pure Ecosystem Backend Integration.

Web Content Display

Ecosystem Types

A Payment Ecosystem is any pool of legally independent merchants that share resources to facilitate the payment process with respect to the end customer or their own implementation efforts while keeping the payment processing with the payment providers of their choice.

We can distinguish the following 5 types of ecosystems. You will find more detailed descriptions about the technical integration of each under Ecosystem Integrations below.

  • Common shop platform (optile M only): Multiple Merchants use the shop platform of a whitelabel provider (Client) to offer their goods and services independent from each other (they do not share end customer data, for example). The platform of the whitelabel provider is connected to optile OPG, using an optile M setup, so that they can offer their Merchants the use of their individual payment providers through the optile abstraction. The optile analytics and orchestration portal could be adjusted to the corporate design of the whitelabel provider, or the provider provides their own frontend which uses optile's widgets or APIs in order to provide configuration options and reporting to their Merchants.
     
  • Marketplace (with mixed carts): Multiple Merchants use a single marketplace platform where they offer their goods and services at the same time. The end customer can therefore place goods from multiple merchants into their virtual shopping cart. The Marketplace platform is connected to optile's special Mixed Cart API. When the customer submits the payment data, optile will split the transansaction into individual payments for the Merchants that are part of this purchase. The payment data, which was only entered once, is being sent to the Payment Provider of each respective Merchant. As a result the customer experiences a single purchase, while they will see individual payments on their account statement later (of course this has to be made transparent). A collection model by a central entity with delayed disbursements to the Merchants is therefore not required. The Marketplace model is a typical use case for retailers of physical goods.
     
  • Merchant Aggregator platform: Similar to the Marketplace a central platform contains offers from multiple Merchants. However, there is no need for a "mixed cart" scenario, because the customer purchases services of one merchant at a time. This is a typical use case for sellers of services such as hotels or digital services (as opposed to retailers of physical goods). It also simplifies the integration, because optile's OPG Payment API can be used directly. In contrast to the simple optile M scenario, however, customer data can be re-used by all Merchants of that ecosystem in order to facilitate conversion-optimized cross-selling. This means that the customer does not have to enter their payment data repeatedly for separate purchases, but can opt-in to re-use the data they have already used on the platform earlier.
     
  • Redirect Ecosystem: Each Merchant has their own, technically independent online shop, meaning they do not run on a central marketplace or aggregator frontend. The customers can move between them. A typical use case is that after the purchase at one Merchant they would see complementary offers of other Merchants. An example would be offers for a hotel or car rental after the purchase of an airline ticket. When clicking out the user gets "redirected" to the other shop. The Merchants can now share a reference to this customer and their payment data (via the so-called Ecosystem Registration IDs, short ESCRID, which are embedded in Ecosystem JSON Web Tokens, short ESJWT). This way the other Merchant(s) can offer the customer to make the purchase with their previously used payment / customer data -- given the consent of the user of course. As a result the customer does not have to enter their data again and can check out on different partner shops with just a few clicks.
     
  • X-Provider: In some cases Merchants have no way of being coupled to each other, which means they cannot exchange registration data (the ESJWT) between each other. In this case they can offer the user to log-in at a central instance, the so-called X-Provider who keeps the customer data. From a customer's point of view this is a similar checkout experience as with PayPal Express or Amazon Pay. Instead of entering their data at the Merchant they log in at a third party, who provides that data to the Merchant then. An important difference to the aforementioned PayPal or Amazon is that the X-Provider does not collect money itself. Instead they issue an ESJWT for the Merchant, so that the Merchant can request a payment with the data stored at optile, using their own payment provider.

While the X-Provider scenario is naturally based on a permanent storage of customer data, the other scenarios are not. They can be combined with a permanent customer identity, which could be provided centrally for the whole ecosystem, or "local registrations" for individual Merchants. But they can also exchange the neccessary data only in the context of one shoppping session of a customer.

Web Content Display

Tokenization Architecture

Redirect Ecosystems and X-Provider scenarios allow a Provider Tokenization architecture, because the Merchants run distinct shops and would in theory need their individual integrations with optile. However, many Merchants already have existing integrations into Payment Providers which they would like to keep, instead of replacing it with an integration into optile. (This does not apply to scenarios with a central shop platform, because this integrates centrally into optile).

For these cases optile offers Provider Tokenization architectures. Instead of processing the payments through optile, the Merchants can retrieve an authorization token issued by their payment provider for the card of the respective customer, which they can use in their existing integration with the payment provider to trigger the actual payment. If the ecosystem provides some central infrastructure, an Ecosystem Backend, which facilitates the information exchange between Merchants anyway, it can also implement the optile integration. In that case, the individual Merchants are completely de-coupled from optile, meaning they are only integrated with the Ecosystem Backend.

In total we can distiguish between two Provider Tokenization architectures (one without an optile integration called "white-label", one with a light-weight integration by the Merchants), and one full optile integration which is not based on Provider Tokens, as visualized below. The fourth variant (grey) will be added to our documentation at a later stage.

Prerequisites for Provider Tokenization

There are important prerequisites for the two Provider Tokenization scenarios, because optile does not manage the payments directly:

  • An existing direct integration of the Merchants with their Payment Providers
  • A usage of Provider Tokens in these existing integrations
  • An overlapping set of accepted ecosystem payment methods between all Merchants (and the Ecosystem Backend if it also offers payments or registrations), for example Visa and Master Card.
In Provider Tokenization scenarios optile is not involved in payment transactions and will naturally not have reporting data about them.

The following sections describe the differences between these scenarios in terms of technical integration.

Web Content Display

White-label Tokenization

This scenario is suited for Merchants which have existing Payment Provider integrations (using Provider Tokens) already, and an Ecosystem Operator who can provide the neccessary functions in a central Ecosystem Backend. The individual merchants are then only connected to that Ecosystem Backend, and don't require any integration with optile. The Ecosystem Operator often acts as a Merchant itself, too, but doesn't have to.

The technical sequence of this tokenization scenario can be divided into 3 segments, as also visualized in the diagram below:

  • a) Initializing the payment: After the customer (yellow) has been redirected to the partner Merchant they want to place and pay an order (3.1). The Merchant's system (black) connects to the Ecosystem Backend (red) to request the "Selection Page" where the customer can see their masked payment account data as provided by the ecosystem, consent to use it for this Merchant, potentially select between different cards, and enter the CVC if required by the Payment Provider (3.2). The Ecosystem Backend needs to be able to identify the end customer at this point (this has to be implemented between the Merchants and the Ecosystem backend). It already knows the corresponding Ecosystem Customer Registration ID (ESCRID) from a previous customer registration in the ecosystem, will encapsulate it into an Ecosystem JSON Web Token (ESJWT-2, which gets issued specifically for this Merchant), and send it to optile's OPG (green) (3.3).
    As a result optile will generate a simple, CSS-customizable hosted page, and return its URL all the way back to the Merchant, who can integrate it within an iFrame into its website. Also other means of integration may be possible in the future, but since the content of the Selection Page is limited, a hosted solution seems sufficient for most cases. At this point the customer has the possibility to trigger the payment for this Merchant with their previously registered payment account.
     
  • b) Provider Tokenization: Once the customer has given consent to use a certain card for this purchase, and potentially entered the CVC on the Selection Page, the data is directly transmitted from the iFrame to optile for PCI reasons (3.7). This way neither the Merchant nor the Ecosystem Backend get in touch with sensitive card data such as the CVC and need only minimal PCI compliance. optile will now request the Provider Token from the Payment Provider of that Merchant (gray) (3.8), using the stored card data together with the given CVC (which is not allowed to be stored).
    If successful, the ID of this tokenization Operation ID will be delivered to the Ecosystem Backend via Status Notification (3.10). At the same time a redirect URL will be returned to the customer (3.12). This URL typically points to a page on the Merchant side (as provided by the Merchant), which will finalize the payment, or potentially to a Secure Customer Authentication page (SCA) in the course of a 3D Secure (3DS) flow (3.13). In this case the customer will be redirected to the 3D Secure challenge first and the Merchant's payment finalization page directly afterwards (3.14).
  • c) Payment with Provider Token: With the user following the final redirect (3.14), the Merchant now requests the Provider Token from the Ecosystem Backend (3.15). There the Operation ID will be used again to communicate with optile (3.16) and receive the Provider Token and context data. This is supplied to the Merchant (3.18) that can use it in their existing Payment Provider integration to trigger the actual payment (3.19). In the happy path this leads to an immediate success (3.20). Please note, however, that in theory an issuer can require a 3DS SCA at this point, so potentially the customer could also be redirected to a 3DS Challenge page at this point. Keeping the idea of "frictionless flows" of 3D Secure 2 in mind, it should be unlikely that a customer gets redirected 2 times in one session (in 3.13 and after 3.20). It could happen in either places, though, so Merchants should forsee both possibilities.
     

"White-label Tokenization": Visualized API interaction sequence between...

Customer agent, e.g. browser (yellow), Merchant server (black), Ecosystem Backend (red), optile OPG (green), Payment Provider (gray)

As noted above also this scenario assumes an existing direct integration of the Merchant with their Payment Provider using Provider Tokens, and an overlapping set of accepted payment methods between all Merchants (and potentially the Ecosystem Backend).

White-label Tokenization

This scenario is suited for Merchants which have existing Payment Provider integrations (using Provider Tokens) already, and an Ecosystem Operator who can provide the neccessary functions in a central Ecosystem Backend. The individual merchants are then only connected to that Ecosystem Backend, and don't require any integration with optile. The Ecosystem Operator often acts as a Merchant itself, too, but doesn't have to.

The technical sequence of this tokenization scenario can be divided into 3 segments, as also visualized in the diagram below:

Please sign in to view further details of this article. Login

Web Content Display

Light optile Integration

As opposed to the Pure Ecosystem Backend integration of a Merchant, this scenario requires a simple connection of the Merchant to optile, but not a full-fledged integration that would enable also payment processing through optile. The difference is that the LIST request to optile is now issued by the Merchant, not the Ecosystem Backend, but the Ecosystem Backend is still the central entity to manage ESCRIDs and issue ESJWTs for Merchants.

Technically this affects segments a) and c) of the tokenization process: In the "Light optile Integration" the Merchant does not request the Selection Page from the Ecosystem Backend (3.2 in the Pure Ecosystem Backend integration diagram above), but only asks for a corresponding ESJWT from there (3.2a in below diagram). After having received this (3.2c), the Merchant will submit it now to optile directly, in the form of a LIST for TOKENIZATION request (3.3).

The user interaction (segment b) is the same as in the Pure Ecosystem Backend integration. The Merchant can integrate the returned URL of the Selection Page (3.4 in both, the above and below diagram), typically in the form of an iFrame. Then the flow proceeds with the customer consent / selection /CVV entry.

To retrieve the Provider Token (segment c), the Merchant would now, however, ask the Ecosystem Backend for the Operation ID and then use the previous ESJWT to contact optile directly. Then the token response comes back and the actual payment can be triggered with the Provider Token in the usual way, as described in the Pure Ecosystem Backend integration, and also here the merchant should forsee a potential 3D Secure redirect / SCA in step 3.19.

"optile Light integration": Visualized API interaction sequence between...

Customer agent, e.g. browser (yellow), Merchant server (black), Ecosystem Backend (red), optile OPG (green), Payment Provider (gray)

Diagram to be updated (code 960)...

Light optile Integration

As opposed to the Pure Ecosystem Backend integration of a Merchant, this scenario requires a simple connection of the Merchant to optile, but not a full-fledged integration that would enable also payment processing through optile. The difference is that the LIST request to optile is now issued by the Merchant, not the Ecosystem Backend, but the Ecosystem Backend is still the central entity to manage ESCRIDs and issue ESJWTs for Merchants.

Please sign in to view further details of this article. Login

Web Content Display

Full optile Integration

In this scenario the Merchant uses optile for payment processing instead of a direct connection to their Payment Provider. This is an interesting option for Merchants that want to create a new internal payment process or replace an existing one with a Payment Orchestration Platform such as optile.

Similar to the Light optile Integration option this scenario starts with the Merchant requesting an ESJWT from the Ecosystem Backend, which contains the ESCRID of the current customer. Upon receival, the Merchant now submits the ESJWT inside a LIST request to optile and proceeds with the consecutive standard flow. This means that optile's Selection Page can be integrated the same way as a classic Payment Page. The customer's submission it will automatically result in a CHARGE request to optile, where it will be translated and forwarded to the respective Payment Provider of this Merchant.

Web Content Display

Ecosystem Integrations

The following sections will detail how the different types of ecosystems would be technically integrated by the Merchants and the Ecosystem Backends with regards to the payment processing.

Clients that operate a Payment Ecosystem which also exposes optile's analytics and/or orchestration services to their Merchants can also read the optile M documentation about:

  • Merchant Management, especially the setup of Merchant groups
  • Whitelabel services using optile's portal or configuration / analytics APIs

 

Web Content Display

Common Shop Platforms

Clients / whitelabel providers that run a common shop platform for multiple Merchants, without sharing customer data between them, can just integrate their platform with optile's classic OPG. They only need to manage and use the separate Merchant's API credentials accordingly.

Web Content Display

Marketplaces / Mixed Cart

In a Marketplace scenario there is a central shop platform that incorporates products from multiple Merchants. This requires a dedicated integration of the Merchants with the Marketplace system. optile is typically only integrated by the central Marketplace, not the Merchants individually.

The payment flow is similar to a standard optile integration, starting with a request for optile's dynamic payment page. This corresponds to optile's classic LIST request but with an important difference: In this scenario the request needs to represent how the shopping cart and the payment amount is divided between multiple Merchants.

For this purpose optile provides a dedicated Mixed Cart API which contains X-LIST and X-CHARGE endpoints. These work similar to the classic endpoints while enabling the representation of multiple Merchants.

As a result a customer's purchase will be split into several payment transactions, one for each Merchant with their respective payment provider.

Processing Queue

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. 

User experience

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.

API sequence

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.

API specification

For a detailed specification of the API endpoints please see our Mixed Cart API Reference.

Status Notifications

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. 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.
  • 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 longId and 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.

Failure handling

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 stopped state.

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
    DELETE https://api.oscato.com/api/lists/5cab5c292d2211017c61do
    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.

Status flow

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.

Marketplaces / Mixed Cart

In a Marketplace scenario there is a central shop platform that incorporates products from multiple Merchants. This requires a dedicated integration of the Merchants with the Marketplace system. optile is typically only integrated by the central Marketplace, not the Merchants individually.

The payment flow is similar to a standard optile integration, starting with a request for optile's dynamic payment page. This corresponds to optile's classic LIST request but with an important difference: In this scenario the request needs to represent how the shopping cart and the payment amount is divided between multiple Merchants.

For this purpose optile provides a dedicated Mixed Cart API which contains X-LIST and X-CHARGE endpoints. These work similar to the classic endpoints while enabling the representation of multiple Merchants.

As a result a customer's purchase will be split into several payment transactions, one for each Merchant with their respective payment provider.

Please sign in to view further details of this article. Login

Web Content Display

Merchant Aggregators

Merchant Aggregators work in a very similar fashion as the Redirect Ecosystems described below. But since they run on a central infrastructure, not individual store frontends of different Merchants, the requests for Selection Pages for the customer are not triggered by the Merchants themselves but directly from the aggregator platform. In this way it (also) takes the role of the central Ecosystem Backend as explained below. More descriptions will be provided soon.

Web Content Display

Redirect Ecosystems

The following is an illustration of a typical API flow that can be employed in a Redirect Ecosystem, from the first customer registration in the ecosystem to the purchase at a partner merchant. Other variations are possible, too, especially with regards to the comminucation between the Merchants and the Ecosystem backend, but are ultimately centered around the same principles and endpoints of the optile API shown below.

Part 1: Registration of the customer at the ecosystem.

For the purpose of the first registration an Ecosystem Customer Registration ID (ESCRID) is generated by the Ecosystem Backend which will represent the customer in the ecosystem from now on. It can be persisted in a user database. It's wrapped into a temporary ESJWT which gets submitted to optile via the LIST request with ESJWT (1.2). As a result the customer can enter their card data and submit it for registration (1.5).

In the representation above the data is sent directly to optile as a registration only. Alternatively this could also be combined with a purchase from the Ecosystem Operator, thereby exchanging the registration mechanics with a CHARGE request. The card data could also go the Ecosystem Backend first (utilizing a Pure Native integration or Standalone Charge). This would require a full PCI compliance of the Ecosystem Backend and would allow, for example, to register the data at optile, and at the same time submit it for payment directly to a Payment Provider, if that integration existed already.

Finally the the registration could also happen on a Merchant side. the Merchant would then connect to the Ecosystem Backend, which would relay the corresponding call in analogy to calls 3.1 - 3.3 below.

Part 2: Redirect to Partner Merchant

This is communication entirely between the Ecosystem backend and the Merchant chosen by the customer, or a first and a second Merchant. Typically the customer is being presented with a complementary offer to the purchase that they just made, coming from a different Merchant (for example a hotel or car rental deal). An important aspect here is to track the click outs, authenticate against the Ecosystem Backend, and share a customer reference between the parties, which can be a proprietary solution.

Part 3: Tokenization and Payment

The API flow to finalize the payment on the Merchant side depends on the Provider Tokenization scenario. Please find a detailed description there. The diagram above is just an illustration of one possibility.

Part 4: Reporting

In Provider Tokenization scenarios optile will not be involved in the payment processing and can therefore not reliably report on payments made. Therefore an optional reporting API could be established on either the Ecosystem Backend or optile where the Merchant can report successfully executed payments that came through means of the ecosystem.

Redirect Ecosystems

The following is an illustration of a typical API flow that can be employed in a Redirect Ecosystem, from the first customer registration in the ecosystem to the purchase at a partner merchant. Other variations are possible, too, especially with regards to the comminucation between the Merchants and the Ecosystem backend, but are ultimately centered around the same principles and endpoints of the optile API shown below.

Please sign in to view further details of this article. Login

Web Content Display

API Data formats

Web Content Display

ESJWT Generation

An "Ecosystem JSON Web Token" (ESJWT) is issued by the Ecosystem Backend for one or multiple Merchants within the ecosystem. Most notably it contains the "Ecosystem Customer Registration ID" (ESCRID) which identifies a customer within the ecosystem. A client that can present a valid ESJWT will be able to trigger payments or provider tokenizations with the respectively stored customer payment data. Therefore it's the central means to share customer data between different Merchants of the ecosystem.

ESJWTs follow the conventions of regular JSON Web Tokens and make use of both, JSON Web Signature and JSON Web Encryption standards to authenticate and secure the payload.

Specifically the ESJWT creation follows 3 steps which we will spell out in the following sections.

  1. Create the payload which identifies the end customer, eligible merchant(s) and expiration (using JWT standard claims).
  2. Sign it with the private key of the ecosystem (using JWS standard).
  3. Encrypt it with the public key of optile (using JWE standard).

Now it's ready to send, typically as an attribute within a LIST request.

Putting everything together you can think of the final ESJWT as layers that wrap around the original payload, as shown on the right.

Let's see the details of how you create these layers in the following sections.

1. The Payload

The payload is a simple JSON object containing some common claims of the JWT standard. An online tool to quickly build JWTs is the Online JWT Builder. You can find an example JSON payload on the right.

The meanings of the claims attributes are:

  • iss - optile's identifier of the the ecosystem issuing this ESJWT
  • iat - Issued at (in Unix time)
  • exp - Expires at (in Unix time)
  • aud - Intended audience of the token (just set to "optile")
  • sub - Merchant ID(s) as assigned by optile (can be more than one for a Mixed Cart with registration case)
  • escrid - Ecosystem customer registration ID, as generated by the ecosystem
  • escrpwd - Ecosystem customer registration password, as generated by the ecosystem
JSON Payload
{
  "iss": "ecosystem_id",
  "iat": 1579884344,
  "exp": 1611422144,
  "aud": "optile",
  "sub": [
    "merchant_id1",
    "merchant_id2"
  ],
  "escrid": "48e8d389-dd1a-476d-b912-03d387fb5642",
  "escrpwd": "d5468820-d975-4154-81b3-99b219611e43"
}

2. The Signature (JWS)

The payload should be signed with the Ecosystem Operator's private key. There are probably libraries in your programming language that do this for you.

As an input you need the payload, of course, plus the following attributes which will form the JWS header:

  • kid - Identifies the key pair used for signing. It was generated by optile when you submitted your key beforehand.
  • alg - Set the algorithm value to RS512

As a result you get a long string which consists of 3 base64url-encoded content parts separated by dots, for example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

These parts are:

  • Header: JSON representation of the JWS header attributes kid and alg.
  • Payload as created earlier. Note that this is not encrypted content, only an easy-to-decode base64url representation.
  • Signature: The resulting signature of the payload, used to validate that the content was issued by you.

Since the content contains sensitive data such as the escrpwd and is only base64url-encoded, we still need to encrypt it properly, see next step.

3. The Encryption (JWE)

At this point you have a signed JWS which you now encrypt with an optile public key in order to come up with the final JWE. Again you will probably find libraries that do the JWE encryption for you.

This time the payload to be encrypted is the whole JWS string from the previous step. And again you need some additional input which is also represented in the resulting JWE header:

  • kid - Identifies the optile key used for encryption. Can be retrieved via API, see below.
  • alg - Algorithm value must be RSA-OAEP-256
  • enc - Encryption method value must be A128CBC-HS256
  • cty - Set to JWT for a nested JWT like this

And voilà. The resulting string is the final ESJWT representation (the form of an encrypted JWE). You can include this into the respective attribute of your LIST requests. Only optile can decrypt it, and then verify its authenticity through the signature of your system. Now the designated end customer can re-use their payment data stored in the name of the ecosystem.

On the right hand side you find a code example that demonstrates all 3 steps in Java.

Full Java example (using the jose4j library)


public String createEsJWT() {
  final JwtClaims claims = new JwtClaims();
  claims.setClaim("sub", merchants);
  claims.setClaim("escrid", exridId);
  claims.setClaim("escrpwd", escridPwd);
  claims.setExpirationTime(NumericDate.fromMilliseconds(expirationDate.getTime()));
  claims.setIssuedAt(NumericDate.now());
  claims.setIssuer("TEST_ECOSYSTEM");

  PrivateKey pk = ...; //Private Key used by Ecosystem to sign JWT
  PublicKey pb = ...; //Public Key (Encryption Key) provided by Optile to Ecosystem for Encryption
  String verificationKeyId = ...; //Identifier (assigned by Optile) of the Public Key to verify the signature
  String decryptionKeyId = "TEST_ECOSYSTEM@1"; //Identifier (assigned by Optile) of the Encryption Key used to encrypt this JWT

  final String jws = createJWS(claims, pk, verificationKeyId); //Signed JWT (JWS) which must be encrypted
  final String jwe = createJWEfromJWT(jws, pb, decryptionKeyId); //Ready to be send Encrypted JWT (JWE) which containts JWS
}

private String createJWS(final JwtClaims claims, final PrivateKey privateKey, final String verificationKeyId) throws Exception {
  JsonWebSignature jws = new JsonWebSignature();
  // The payload of the JWS is JSON content of the JWT Claims
  jws.setPayload(claims.toJson());
  // The JWT is signed using the sender's private key
  jws.setKey(privateKey);
  // Set the signature algorithm on the JWT/JWS that will integrity protect the claims
  jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA512);
  // Added key identifier for EcosystemKey
  jws.setKeyIdHeaderValue(verificationKeyId);
  // Sign the JWS and produce the compact serialization, which will be the inner JWT/JWS
  // representation, which is a string consisting of three dot ('.') separated
  // base64url-encoded parts in the form Header.Payload.Signature
  return jws.getCompactSerialization();
}

private String createJWEfromJWT(final String jwt, final PublicKey publicKey, final String decryptionKeyId) throws Exception {
  // The outer JWT is a JWE
  JsonWebEncryption jwe = new JsonWebEncryption();
  jwe.setAlgorithmHeaderValue(KeyManagementAlgorithmIdentifiers.RSA_OAEP_256);
  // The content encryption key is  used to encrypt the payload
  jwe.setEncryptionMethodHeaderParameter(ContentEncryptionAlgorithmIdentifiers.AES_128_CBC_HMAC_SHA_256);
  // We encrypt to the receiver using their public key
  jwe.setKey(publicKey);
  // A nested JWT requires that the cty (Content Type) header be set to "JWT" in the outer JWT
  jwe.setContentTypeHeaderValue("JWT");
  // The inner JWT is the payload of the outer JWT
  jwe.setPayload(jwt);
  // Added key identifier to header
  jwe.setKeyIdHeaderValue(decryptionKeyId);
  // Produce the JWE compact serialization, which is the complete JWT/JWE representation
  return jwe.getCompactSerialization();
}

ESJWT Generation

An "Ecosystem JSON Web Token" (ESJWT) is issued by the Ecosystem Backend for one or multiple Merchants within the ecosystem. Most notably it contains the "Ecosystem Customer Registration ID" (ESCRID) which identifies a customer within the ecosystem. A client that can present a valid ESJWT will be able to trigger payments or provider tokenizations with the respectively stored customer payment data. Therefore it's the central means to share customer data between different Merchants of the ecosystem.

ESJWTs follow the conventions of regular JSON Web Tokens and make use of both, JSON Web Signature and JSON Web Encryption standards to authenticate and secure the payload.

Please sign in to view further details of this article. Login

Web Content Display

Key Management

In order to effectively sign and encrypt your ESJWTs you can upload (or update) your public key (for signature validation) and retrieve the optile public key (for encryption).

Uploading your public key (for signature validation)

Generate a JSON object with:

  • publicKey: Your public key in PKCS#8 PEM format
  • createdAt: Creation time of the key
  • expiresAt (optional): Expiration time of the key
  • iat: Issuing time of this JWT

See example on the right.

Sign this JSON with the private key that corresponds to the public key you are submitting. This happens in analogy to the signature step under ESJWT Generation. Only this time there is no kid attribute that you set for the header, because you are sending this key for the first time.

Submit the resulting JWS string (three base64url-encoded content parts separated by dots) in the HTTP body to:

POST /ecosystems/{ecosystemCode}/keys/signing

In the response you will receive an ID for this key of yours, which you can use as the kid parameter for future ESJWT signing.

Public Key JSON Payload
{
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIICIjA[...]yW5F/UvGmXBH0QniU4ERO+\np6UMFELO+sxlT6cf86PG4+MCAwEAAQ==\n-----END PUBLIC KEY-----\n",
  "createdAt": 1586822400000,
  "expiresAt": 1767139200000,
  "iat": 1591277893
}

Updating expiration time of your public key

Generate a JSON object with only an expiresAt attribute which indicates the new expiration time. See example on the right.

Sign it in analogy to the signature step under ESJWT Generation with the same key which you are addressing in this request. Also here you will not need the kid attribute for the header.

Submit the resulting JWS string in the HTTP body to:

PUT /ecosystems/{ecosystemCode}/keys/signing/{keyId}

Of course keyId indicates the key you want to update.

Retrieving optile's encryption keys

You have read-only access to all public encryption keys for your Ecosystem:

  • GET /ecosystems/{ecosystemCode}/keys/encryption – lists the available encryption keys
  • GET /ecosystems/{ecosystemCode}/keys/encryption/{keyId} – returns a specific encryption key

Key Management

In order to effectively sign and encrypt your ESJWTs you can upload (or update) your public key (for signature validation) and retrieve the optile public key (for encryption).

Please sign in to view further details of this article. Login

Web Content Display

LIST with ESJWT

The LIST request enables one Merchant to display the Selection Page to the customer. There they can see a masked representation of payment account(s) they registered (possibly elsewhere) in the ecosystem. Ultimately they can now enter the corresponding CVV/CVC, if required, and confirm the payment.

The request as well as response is practically the same as the classic LIST request. Typically a LIST request is issued with the intention to make a payment or provider tokenization, but it can be used for a pure registration on optile side, too. To see the majority of the accepted data structures and returned responses please refer to the linked documentation articles and the LIST request of the Server Payment API in our API Reference (login required).

The only difference to the classic LIST request is that the ESJWT will now be passed within the customer.registration structure. This is reflected in our OPG API reference. Also note the example on the right. Read below how to generate ESJWTs for this purpose.

The response and the different integration scenarios are in analogy to the classic LIST request. Please note that in most API flow descriptions above a Hosted Integration (featuring an embedded iFrame) is used as example, but also other Integration Scenarios will be possible in the future.

LIST with ESJWT
...,
"customer": {
  "registration": {
    "esJwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3M[...]jExZTQzIn0._rKPAwjewEytZwk5nHSg_sUpNwaKzHnjiARqFGmgVnI",
  }, ...
}, ...

LIST with ESJWT

The LIST request enables one Merchant to display the Selection Page to the customer. There they can see a masked representation of payment account(s) they registered (possibly elsewhere) in the ecosystem. Ultimately they can now enter the corresponding CVV/CVC, if required, and confirm the payment.

The request as well as response is practically the same as the classic LIST request. Typically a LIST request is issued with the intention to make a payment or provider tokenization, but it can be used for a pure registration on optile side, too. To see the majority of the accepted data structures and returned responses please refer to the linked documentation articles and the LIST request of the Server Payment API in our API Reference (login required).

Please sign in to view further details of this article. Login

Web Content Display

GET Token

The response to a TOKENIZE request will not return the provider token itself but only its operation ID. This can be used in turn to fetch the provider token with an authenticated server-to-server call.

GET /tokens/{tokenizationOperationId}

See a simplified and shortened API response example on the right.

The provider token can be found under maskedAccount.providerTokens.token.

Please also note the attribute additionalData next to it, which is an array of name-value-pairs. Its contents are dependent on the payment provider and will require an individual assessment when you choose the provider(s) you want to work with. Please let us know in advance, in order to prepare for the requirements of this provider(s) tokenization system.

 

GET Token
{
  "links": {
    "self": "https://api.sandbox.oscato.com/api/tokens/59c117dfcb4396be3263erfr",
    "account": "https://api.sandbox.oscato.com/api/customers/59e0b954148bp4t1n6ds5u/accounts/59e0b92d80ce9a8cd7a",
    "customer": "https://api.sandbox.oscato.com/api/customers/59e0b954148bp4t1n6ds5u"
  },
  "timestamp": "2017-09-22T13:53:46.410+0000",
  "operation": "TOKENIZE",
  "network": "AMEX",
  "contract": {
    "id": "594405cfcf64921005fb1196",
  },
  "maskedAccount": {
    "registration": {
      "id": "59e07b240bd6e05fe60f063aa"
    },
    "providerTokens": [
      {
        "token": "391337D8AFED8AA31HA07BC8138E78D0",
        "registration": false,
        "recurrence": true,
        "additionalData": [
          {
            "name": "...",
            "value": "..."
          }
        ]
      }
    ],
    "displayLabel": "37 *** 0002    05 | 2021",
    "holderName": "Max Mustermann",
    "number": "37 *** 0002",
    "expiryMonth": 5,
    "expiryYear": 2021
  },
  "resultCode": "45000.HEIDELPAY.800.100.152",
  "pspCode": "HEIDELPAY",
  "institutionCode": "string",
  "status": {
    "code": "registered",
    "reason": "registered"
  },
  "interaction": {
    "code": "PROCEED",
    "reason": "OK",
    "retryAfter": "2020-04-29T13:48:13Z"
  },
  "identification": {
    "longId": "59e48b51018709cc7cc",
    "shortId": "03059-69977",
    "transactionId": "order-00008312",
    "pspId": "31HA07BC8138E78D0391337D8AFED8AA",
    "institutionId": "string",
    "systemId": "string"
  },
  "redirect": {
    "url": "http://example.com",
    "method": "GET",
    "parameters": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "suppressIFrame": true,
    "displayInPopup": true,
    "containsAccountPlaceholders": true,
    "type": "RETURN"
  },
  "customer": {
    "number": "UN-0010352",
    "email": "james.blond@example.com",
    "registration": {
      "id": "59e07b240bd6e05fe60f063au",
      "password": "sfqh52h442j..."
    }
  }
}

GET Token

The response to a TOKENIZE request will not return the provider token itself but only its operation ID. This can be used in turn to fetch the provider token with an authenticated server-to-server call.

Please sign in to view further details of this article. Login

Web Content Display

X-LIST statuses

An X-LIST represents an order of items from multiple merchants at the same time. It's used in a Marketplace / Mixed Cart scenario, and not to be confused with a regular LIST, representing an order from only one merchant. In case the user should have the possibility to register a payment account, or already registered accounts should be retrieved, the X-LIST should be initialized with an ESJWT containing the merchants that are part of this order.

All resulting payment transactions of the X-LIST have their own, regular status codes. The status of the X-LIST represents therefore an aggregated view on what has happened with the individual payments so far. Below you find a list of relevant statuses.

Status code / reason code Meaning Suggested reactions of marketplace
listed / listed After successful LISTX call Execute X-CHARGE
failed / list_failed X-LIST failed (all OPG lists failed or other technical issue) Involve technical specialists, contact optile's support if needed.
rejected / list_rejected No payment networks Fix merchants configurations
completed / completed all charges are successfully completed

n/a

Payouts through OPG for sub-transactions are possible if needed

stopped / interrupted

No transactions were completed successfully, interrupting (for the 1st transaction) error occurred.

or

non-interrupting error occurred for all transactions.

Possible options:

  1. Execute X-CHARGE with other payment data
  2. Cancel X-LIST
  3. do nothing (SessionX will be expired after timeout)
stopped / completed_partial

One or more charges were successful, one or more charges were with error. Charge can be repeated.

Possible options:

  1. Execute X-CHARGE with other payment data
  2. Cancel X-LIST
  3. do nothing (X-LIST will be expired after timeout)
in_progress / processing Charge was triggered, no further state (like Closed, or Pending) was reached. Basically this means that no actions is required from marketplace or customer. Wait for notification or response to previous request
in_progress / pending_on_redirect One of charges is waiting for redirect (like SCA) Wait for notification or response to previous request. Use redirect data to execute SCA.
in_progress / pending_on_provider Provider accepted payment data, but optile's still waiting for confirmation that payment is completed Wait for notification or response to previous request
expired / expired

Charge was never triggered OR

After SessionX reached 'Stopped' state, no actions were taken and the session expired.

n/a
completed_partial / canceled At least 1 payment is completed, one payment failed with interrupting error, after which marketplace sent a cancellation

n/a

Payouts through OPG for sub-transactions are possible if needed

completed_partial / expired At least 1 payment is completed, one payment failed with interrupting error,  which was nor resolved neither canceled, so transaction was expired.

n/a

Payouts through OPG for sub-transactions are possible if needed

canceled / canceled 1st charge had an interrupting error, marketplace sent cancellation n/a

X-LIST statuses

An X-LIST represents an order of items from multiple merchants at the same time. It's used in a Marketplace / Mixed Cart scenario, and not to be confused with a regular LIST, representing an order from only one merchant. In case the user should have the possibility to register a payment account, or already registered accounts should be retrieved, the X-LIST should be initialized with an ESJWT containing the merchants that are part of this order.

All resulting payment transactions of the X-LIST have their own, regular status codes. The status of the X-LIST represents therefore an aggregated view on what has happened with the individual payments so far. Below you find a list of relevant statuses.

Please sign in to view further details of this article. Login