Omni-channel
1. Introduction
| This guide must be read alongside our DirectLink guide. |
Hereafter we guide you through the features of the online part of the Worldline Omni-channel offer.
The following key elements to benefit from the online Omni-channel offer are covered:
- How to become an Omni-channel merchant?
- How to benefit from Omni-channel features such as the single back office (e-Portal), online refunding of in-store transactions and the tokenization?
- How to make transactions in an Omni-channel context?
- What are the new fields to handle via the various integration modes?
2. Activation: how to be Omni-channel
Please contact your sales representative to request activation of your Omni-channel features.
During the activation phase, you will define and submit to Worldline a hierarchical list of users and entities by which the transactions will be generated. Hereunder we've summarized how you can describe the different webshops and users.
For more details, please contact your sales representative for guidance on the activation process.
3. Access to the back-office e-Portal
One of the key benefits of the Omni-channel offer is a common back office to review and manage your transactions and your configuration. This web-based portal is called e-Portal.
Using e-Portal, you can perform refunds on your transactions, whether they were done online or in-store.
The Ogone online payments section is directly available in e-Portal, using your e-Portal credentials.
You can access e-Portal here: https://eportal.services.ingenico.com
For more details on how to use e-Portal, please refer to relevant e-Portal User Guide.
4. Group of Groups
Prior to the Omni-channel offer, you were able to define users (lowest level PSPID) and to order them into groups, by placing common users under one Merchant Group or MGID.
A concept has been added, where several groups can be grouped under a top MGID. During the activation process, you will provide a list of users list representing your shop structure and their users. Here is an example:
The maximum number of layers (levels) is 3 (e.g., country - region - store).
For more details, please contact your sales representative or refer to the relevant e-Portal User Guide.
5. User management
In order to simplify the user management, its configuration has been centralized within e-Portal. Please refer to e-Portal User Guide - User Management module for more details.
Note that API users on the Ogone platform must still be managed via the user management section in the "Online" tab of e-Portal.
6. API General information
XDL is a new API that allows Omni-channel merchants to access all of the features of Ogone DirectLink (new orders, maintenance and query) with the same interface as DirectLink, but with Omni-channel features included.
This means that the merchant will be able to act on his transactions, whether they come from Card Present (CP) or Card Not Present (CNP) world. Payment terminals at POS are CP, and payment online at a web shop is CNP.
This includes use cases like refund CP and/or CNP payment, deferred payment, etc. Please refer to your sales representative for more information about our proposed Omni-channel use cases.
6.1 Concept
In the context of Omni-channel we have a few new concepts to introduce:
| Concept | Description | Platform |
|---|---|---|
| Omni-channel Order |
A set of transactions that belong together from the point of view of the merchant. All of the transactions in the Omni-channel order have the same ORDERID. The order is identified by the combination of merchant and his sales reference. |
n/a |
| Payment |
Treatment of a payment. Starts with the authorization or the direct sale. Consists of multiple transactions. |
Ogone: Order, identified by PAYID |
| Transaction |
Lowest level of interaction. There are several types of transactions like capture, refund, credit, cancellation etc. |
Ogone: Payment History, identified by PAYID + PAYIDSUB |
6.2 URLs
| Test | Production | |
|---|---|---|
| New order | https://ogone.test.v-psp.com/dl/neworder |
https://secure.ogone.com/dl/neworder |
| Maintenance | https://ogone.test.v-psp.com/dl/maintenance |
https://secure.ogone.com/dl/maintenance |
| Query | https://ogone.test.v-psp.com/dl/query |
https://secure.ogone.com/dl/query |
6.3 Integration with Omni-channel
6.3.1 Parameters
With the new Omni-channel features, additional items or artefacts have been made available. Here is a summary of each new item added for each solution.
| Parameter | Description |
|---|---|
| OPERATORID |
While calling XDL, the merchant can, for the sake of reporting and auditing, indicate which human user of his enterprise requested the action. Optional |
| ORDERID |
The merchant’s reference to the sale between the merchant and the merchant’s customer in the context of Omni-channel. The merchant has to guarantee the uniqueness of this field within the merchant’s realm. Mandatory |
| REQUESTID |
In order to identify different requests / payments for the same ORDERID / SalesReference, the merchant must send a unique request identifier for each individual request. In case a first call fails, and there is no response from our server, all subsequent retries must use the same REQUESTID. Mandatory |
| TRANSACTIONID |
Transaction identifier. In order to transfer the Omni-channel transaction to act upon (for instance during maintenance). Each operation on the Worldline platform by an Omni-channel merchant will return both the PAYID and the TRANSACTIONID. The Omni-channel merchant is advised to store the TRANSACTIONID in his records. If the Omni-channel merchant sends TRANSACTIONID and PAYID (and/or PAYIDSUB) parameters together in one request, the consistency between both is verified, and if they do not refer to the same transaction, the request is rejected with an error. Mandatory for maintenance on Card Present transactions. In all other cases it is advised to use TRANSACTIONID, but optional as the merchant can also use the PAYID + PAYIDSUB instead. Mandatory |
| XCORDERAMOUNT |
The Omni-channel Order has an order amount attribute that the merchant can use to report on the planned value of the order. This information will be used in KPI reports regarding upselling. The parameter is expressed in the same currency as the first transaction in the order (x 100, so there are no decimals). The amount of the order does not influence transaction handling in any way. Optional |
| XCORDERSTATUS |
Omni-channel orders can be marked as Open or Closed. The closed status indicates that the normal sales process has been executed. This information can be used in the click-and-collect case, whereas open orders will be available for collecting. Optional |
| CRMTOKEN and XCDIGEST (Tokenization fields) |
|
6.3.2 Operation codes
A few new operations were added to the DirectLink specification, for the purpose of supporting the deferred use case.
| Operation code* | Parameters |
|---|---|
|
PAL Maintenance operation that requests the system to issue a second, third, etc. payment, starting from an original payment transaction identified by TRANSACTIONID, with the same payment method details. The amount to be paid is mandatory, as well as the ORDERID. |
Mandatory PSPID=ECOMRDSPSPID11 Recommended REQUESTID=UMDoperation001 Optional REFKIND=MGID URL TEST: https://ogone.test.v-psp.com/dl/Maintenance |
|
PES Same as PAL, but only gets an authorisation. This operation does not capture the payment. This is an alternative to RES (request for authorisation). |
Mandatory PSPID=ECOMRDSPSPID11 Recommended REQUESTID=PESoperation001 Optional URL TEST: |
|
UMD Maintenance operation that allows updating the metadata fields of an Omni-channel Order without a financial transaction. |
Mandatory PSPID=ECOMRDSPSPID11 Recommended REQUESTID=UMDoperation001 Optional REFID=ECOMRDS.MGP00 URL TEST: |
|
CRD Pure credit operation that works the same as a refund (RFD) but without verification of the amount. Double credit check: If for the same order two concurrent credits are attempted, the second attempt will be blocked. In that way "double-credit fraud", which is a risk when working with multiple channels, is avoided. This system is supported for all ePayments API’s, with Axis terminals and with e-Terminal (MOTO). |
Mandatory PSPID=QAINTC01PSPID01 Optional REFID=QAINTC01PSPID01 URL TEST: |
| RES |
Mandatory PSPID=PSPIDRESTY02 Optional REFID=MG_RESTY_01 URL TEST: |
| REN |
Mandatory PSPID=ECOMRDSPSPID11 Optional REFID=ECOMRDS.MGP00 REFKIND=MGID URL TEST: |
| SAL |
Mandatory PSPID=ECOMRDSPSPID11 Recommended REQUESTID=SALOperation01 Optional REFKIND=MGID URL TEST: |
| SAS |
Mandatory PSPID=ECOMRDSPSPID11 Recommended REFKIND=MGID Optional REQUESTID=SASOperation01 URL TEST: |
| DEL |
Mandatory PSPID=ECOMRDSPSPID11 Recommended REQUESTID=DELOperation001 Optional REFKIND=MGID amount=1000 URL TEST: |
| DES |
Mandatory PSPID=ECOMRDSPSPID11 Recommended REQUESTID=DESOperation001 Optional REFKIND=MGID URL TEST: |
|
RFD
|
Mandatory PSPID=ECOMRDSPSPID11 Optional REFID=ECOMRDS.MGP00 URL TEST: |
| RFS |
Mandatory PSPID=ECOMRDSPSPID11 Optional REFID=ECOMRDS.MGP00 URL TEST: |
| QUERY |
Mandatory PSPID=ECOMRDSPSPID11 Optional REFID=ECOMRDS.MGP00 URL TEST: |
6.3.3 Metadata
XDL features a generic metadata system for transaction and order metadata. This will allow the merchant to bring additional information elements about the transaction and the order. This information does not influence the transaction processing, but will be used in the Unified Journal reporting. The fields are ANNEXNAMEx and ANNEXVALUEx. X is the sequence number and the fields should always come in pairs having the same sequence number. After processing, the sequence number is not relevant anymore, and you should not expect the metadata to be returned in the same sequence order.
You can send metadata with any of the transactions. The metadata already in the system is updated with the new values. Metadata that is not updated in a subsequent request will remain in the system. In order to clear a value, the name and value pair have to be sent, with the value set to nothing, like in &ANNEXNAME2=ORDER-USERDATA1&ANNEXVALUE2=
Although the merchant can send any type of metadata, only some annex names are recognized by Omni-channel for the purpose of KPI reporting:
- ORDER-USERDATA1
ANNEXNAME1=ORDER-USERDATA1
ANNEXVALUE1=DEFERRED
6.3.4 Output
The output returned to the merchant can always be tuned to the merchant's expectations by changing the options in the Ogone back office. This section explains the availability of new output parameters. Whether they are returned to you depends on your settings.
PAYID and TRANSACTIONID
Upon each request from the merchant, the platform will respond with the reference of the executed transaction, commonly known as PAYID and PAYIDSUB.
When the merchant has been configured for Omni-channel, the platform will return the TRANSACTIONID together with the PAYID (if configured accordingly in the list of dynamic parameters).
More details about the TRANSACTIONID can be found earlier in this document, under Parameters.
CRMTOKEN and XCDIGEST (Offline token)
For each transaction request by the merchant that involves card details, the platform will return the CRM tokens that are available for Omni-channel merchants. The returned tokens are specific to the merchant and can only be used to track the cardholder, both online and in-store.
These two card identifiers are:
- CRM Token: a “mask” for the card number, keeping the format of a card number
- Offline token: a non-format preserving identifier for the card used for the payment, at the merchant level.
| Field | Format |
|---|---|
| CRMTOKEN |
Numeric – 16 digits Example: 0246777044912837 |
| XCDIGEST (=Offline token) |
Hexa - 64 digits Example: 05E9… |
Which type of token to choose is entirely up to the merchant, based on the requirements and/or possibilities of his own system.
In case of the XCDIGEST/Offline token, the merchant's system must be able to process long digests.
Note: if the CRM token/Offline token couldn’t be generated, the transaction will still go through but no token will be returned. Contact our Support team.
Add Omni-channel fields to transaction feedback
Log on to e-Portal and go to the Online payments tab > Configuration > Technical information > Transaction feedback:
- Under DirectLink: Dynamic parameters, select the relevant fields (CRMTOKEN, XCDIGEST, TRANSACTIONID, ORDERID, PAYID) in the "Available" dropdown list, and set as “Selected”.
- Under e-Commerce: Dynamic e-Commerce parameters, select the relevant fields (CRMTOKEN, XCDIGEST, TRANSACTIONID, ORDERID, PAYID) in the "Available" dropdown list, and set as “Selected”.
Add Omni-channel fields to electronic reports
Log on to e-Portal and go to the Online payments tab: Operations > View Transactions (note: you need to select one of your PSPIDs to have the menu item displayed):
- Click on “File format”
- Under "Structure", select "Dynamic". Confirm this change directly by clicking "Submit" at the bottom of the page, to show the list of available fields.
- Select "Available fields", add [CRMTOKEN], [XCDIGEST] and [TRANSACTIONID] and click "Submit" at the bottom
- "Selected fields" should show [CRMTOKEN], [XCDIGEST] and [TRANSACTIONID]
When this is done, the transaction reports will show these two fields.
Download reports including Omni-channel fields
Log on to e-Portal and go to the Online payments tab: Operations > Financial history (note: you need to select one of your PSPIDs to have the menu item displayed):
- Check the “detailed list” box
- Select all type of transactions needed
- Click “Download list”.
The list will contain in the header CRMTOKEN; XCDIGEST; TRANSACTIONID. The values will be shown with each transaction.
6.3.5 SHA signature
List of additional Omni-channel parameters to be included in SHA-IN and/or SHA-OUT calculation. *XX* is the placeholder for sequence numbers:
ANNEXNAME*XX*ANNEXVALUE*XX*
CRMTOKEN
OPERATORID
REQUESTID
TRANSACTIONID
XCDIGEST
XCORDERAMOUNT
XCORDERSTATUS
Please refer to our documentation about SHA-OUT.
6.4 Refunds
6.4.1 Cross-payment refunds
You can refund up to the full amount that is calculated as the sum of all payments (Card Present and Card Not Present) done for the whole order.
Example: If within one and the same order there was a CNP payment of €10 and a CP payment of €890, after capturing only the €10 (CP) it is still possible to refund the full €900.
6.4.2 Double refunds check
If for the same order two concurrent refunds are attempted, the second attempt will receive an error “Cannot refund - Order is already locked”.
In that way "double-refund fraud", which is a risk when working with multiple channels, is avoided.
This system is supported for all ePayments API’s, with Axis terminals and with e-Terminal (MOTO).
The order is unlocked shortly after the refund action has been completed.
7. Tokenization
A key pillar of the Omni-channel offer is the tokenization service allowing you to replace sensitive data (e.g. a card number) with non-sensitive data (i.e. a token).
Go to the CRM Token and Offline token chapter for detailed integration info.
For more details about the tokenization service, please refer to the Tokenization Overview document.
8. Error codes
In case the requested refund amount is higher than what is available on the balance, the following error info is returned:
- NCERROR="50001129"
- NCERRORPLUS="Overflow in refunds requests/"MaxRefund amount"/"balance amount"
Häufig gestellte Fragen
Auf der Support-Website finden Sie alle Anleitungen für unsere Produkte. Diese Dokumente können Sie sich gern in Ruhe ansehen.
Mit der Aktivierung Ihres Kontos steht Ihnen unser Abstimmungs-Tool automatisch zur Verfügung, sofern Sie ein Full Service Konto oder die Akzeptanz durch Collect haben. Auf diese Weise können Sie die Zahlungen, die auf Ihrem Bankkonto eingehen, problemlos mit den Bestellungen/Transaktionen auf Ihrem Ingenico ePayments-Konto abstimmen. Wenn Sie mehr über das Abstimmungs-Tool erfahren möchten, klicken Sie bitte hier.
Worldline bietet geeignete, sichere, intelligente und nahtlose Zahlungslösungen für jeden Kanal: im Geschäft, online und Mobil. Worldline bietet Händlern eine umfassende und innovative Palette an Dienstleistungen und Lösungen, die die Komplexität von Zahlungen reduzieren und den Einkauf für verschiedene Vertriebskanäle und Zahlungsmethoden schnell, nahtlos und sicher gestalten.
Worldline besteht aus drei Geschäftsbereichen: Worldline Smart Terminals, Worldline Payment Services und Worldline . Mit unserem umfassenden Angebot an intelligenten Terminals, Zahlungsdienstleistungen und mobilen Lösungen erleichtern wir Händlern die Annahme von Zahlungen im Geschäft und online.
Um das bedeutende Vermächtnis und den Namen von Ogone zu würdigen, wird der Begriff Ogone heute für die Ingenico ePayments-Plattform verwendet, zu der Ingenico Collect gehört. Diese One-Stop-Zahlungslösung ermöglicht es Händlern, bevorzugte Zahlungsmethoden in vielen verschiedenen Ländern anzubieten, ohne dass sie dafür mehrere Bankkonten eröffnen oder neue juristische Personen gründen müssen.
Mit seiner Ogone-Plattform und anderen Angeboten geht Ingenico ePayments über den Zahlungsverkehr hinaus und bietet globale Beratungsleistungen zu Themen wie inländische Rechtsvorschriften, regionale Zahlungsgewohnheiten und Vorlieben sowie Betrugsbekämpfung und Compliance an.
Weitere Informationen finden Sie unter „Transaktionen Ansehen“ einsehen.
Standardmäßig können Sie Waren abschicken oder Dienstleistungen erbringen, sobald eine Transaktion den Status „5 – Authorised“ (Autorisiert) oder „9 – Payment requested“ (Zahlung angefordert) erreicht hat. Auch wenn Status 5 eine Erfolgsmeldung darstellt, meldet er nur die vorübergehende Reservierung eines Geldbetrags auf der Karte des Kunden. Eine Transaktion mit Status 5 muss noch bestätigt werden (manuell oder automatisch), um in den Status 9 zu gelangen, der für die meisten Zahlungsverfahren der finale Erfolgsstatus ist.
Unter Status der Transaktionen finden Sie weitergehende Informationen.
Mit der Schaltfläche „Rückerstattung“ in der Auftragsübersicht einer Transaktion (unter „Transaktionsansicht“) können Sie eine Zahlung ganz einfach rückerstatten. Wenn Ihr Konto es unterstützt, können Sie auch Rückerstattungen mit einer DirectLink-Anfrage oder durch Hochladen einer Batchdatei (für mehrere Transaktionen)) durchführen. .
Bitte beachten Sie, dass die Option „Rückerstattungen“ in Ihrem Konto aktiviert sein muss.
Weitere Informationen finden Sie unter Ihre Transaktionen verwalten.
Ein grüner Daumen bedeutet, die Transaktion ist mit einer 3-D Secure Authentifizierungsmethode wie Digipass oder Kartenleser vollzogen worden. Das bedeutet aber nicht notwendigerweise, dass die Zahlung selbst erfolgreich verarbeitet worden ist. Sie sollten darum immer den Transaktionsstatus prüfen, wenn Sie wissen möchten, ob Sie Ihr Geld auch erhalten werden.
Weitere Informationen finden Sie unter Status der Transaktionen.
Worldline bietet ein komplettes Sortiment mit flexiblen Produkten, ausgereiften Technologien und spezialisiertem Know-how, um Sie bei der Verwaltung und Optimierung Ihrer Online-Betrugsprävention zu unterstützen. Unsere Tools zur Betrugserkennung sind führend in unserer Branche und unsere Experten verfügen über mehr als 20 Jahre Branchen- und Regionalerfahrung. Wir arbeiten eng mit Ihnen zusammen, um eine ganzheitliche Lösung zur Betrugsbekämpfung, welche die Prävention, Erkennung und Management umfasst, zu entwickeln, zu implementieren und zu verwalten. Wir bieten auch umfassende Lösungen für das Rückbelastungs- und Streitfallmanagement an.
Durch Zusammenarbeit mit Worldline können Sie die Lösungen auswählen, die Ihrem Bedarf am besten gerecht werden, und unsere Dienstleistungen so anpassen, dass Funktionen für das Betrugsmanagement auslagert oder mit unserem laufenden Support bei Ihnen intern organisiert werden.
Falls Sie bestimmte Details eines Auftrags bzw. einer Transaktion überprüfen oder Transaktionen verwalten möchten, sollten Sie „Transaktionsansicht“ verwenden. Mit Hilfe von „Finanzielle Historie“ lassen sich ein- und ausgehende Gelder am bequemsten regelmäßig überprüfen.
Weitere Informationen finden Sie unter Transaktionsansicht vs- Finanzielle Historie
Rückerstattungen können Sie nur für Transaktionen durchführen, bei denen Sie den Status 9 seit mindestens 24 Stunden haben. Eine Stornierung oder Löschung kann innerhalb ca. 24 Stunden erfolgen nachdem die Transaktion den Status 5 oder 9 hat.
Wenn Sie den Annahmeschluss des Akzeptanzpartner erfahren möchten, empfehlen wir Ihnen, dass Sie sich direkt an unseren Kundendienst wenden.