1. Introduction

This guide must be read alongside our DirectLink guide.

Hereafter we guide you through the features of the online part of the Ingenico 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 Ingenico 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

Axis: Payment

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.



It is up to the merchant to make up a code to identify the employee, for instance, the userid of the employee logged on to the cash register. When not used, the field defaults to the Ogone user account. For e-Portal, the portal user account will be used.

Format: AN, 100

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.



In the context of Omni-channel, the ORDERID is mandatory for all new orders.

Format: AN, 35

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.



The caller is advised to generate a random number or string (like a new guid) to be used as REQUESTID.



e-Commerce: Not returned



DirectLink: Input only (optional)

Format: AN, 35

Mandatory

TRANSACTIONID



Transaction identifier. In order to transfer the Omni-channel transaction to act upon (for instance during maintenance).



Each operation on the Ingenico e-commerce 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.



The only acceptable values are: "Open" and "Closed".



The status of the order does not block transaction handling in any way.



The status is not to be confused with the difference in operation between SAL and SAS, which closes the payment against further capturing.

Format: "Open"/"Closed"

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.
The system will make sure that CVC and 3-D Secure will not be required, as the customer is not physically available at the time of the request. This is an alternative to the SAL direct sale/payment request, and follows the same capture rules, defined by the merchant's configuration.

Mandatory

PSPID=ECOMRDSPSPID11
USERID=Cust_12240_API_USER
OPERATION=PAL
amount=1000
currency=EUR
TRANSACTIONID=9000001001785380000

Recommended

REQUESTID=UMDoperation001

Optional

REFKIND=MGID
REFID=ECOMRDS.MGP00

URL

TEST: https://ogone.test.v-psp.com/dl/Maintenance
PROD: https://secure.ogone.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
USERID=Cust_12240_API_USERPSWD=xxxxxxxxxxxxxxx
OPERATION=PES
amount=1000
currency=USD
TRANSACTIONID=9000001001785380000

Recommended

REQUESTID=PESoperation001

Optional
REFKIND=MGID
REFID=ECOMRDS.MGP00

URL

TEST:
https://ogone.test.v-psp.com/dl/Maintenance
PROD:
https://secure.ogone.com/dl/Maintenance

UMD

Maintenance operation that allows updating the metadata fields of an Omni-channel Order without a financial transaction.
The request must contain ORDERID and can have the following additional parameters: XCORDERAMOUNT, XCORDERSTATUS, ANNEXNAME*XX*, ANNEXVALUE*XX*, OPERATORID, REQUESTID, TRANSACTIONID.

Mandatory

PSPID=ECOMRDSPSPID11
CURRENCY=EUR
USERID=Cust_12240_API_USER
PSWD=xxxxxxxxxxxxx
OPERATION=UMD
ORDERID=UMDOperation001

Recommended

REQUESTID=UMDoperation001

Optional

REFID=ECOMRDS.MGP00

REFKIND=MGID

XCORDERAMOUNT=200
XCORDERSTATUS=Open
ANNEXNAME1=ORDER-USERDATA1
ANNEXVALUE1=SalesPeriod
ANNEXNAME2=ORDER-USERDATA2
ANNEXVALUE2=53
ANNEXNAME3=ORDER-USERDATA3
ANNEXVALUE3=Something
ANNEXNAME4=ORDER-USERDATA4
ANNEXVALUE4=UMDoperation001
OPERATORID=testoperator
TRANSACTIONID=9000001001785380000

URL

TEST:
https://ogone.test.v-psp.com/dl/Maintenance
PROD:
https://secure.ogone.com/dl/Maintenance

CRD

Pure credit operation that works the same as a refund (RFD) but without verification of the amount.
You can use CRD if you want to give/return money to the cardholder, with an amount of your choice and no previously paid amount.
To be able to use CRD you need to specify the TRANSACTIONID, so that card details can be retrieved.

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
CURRENCY=EUR
USERID=QAINTC01PSPID01_API

PSWD=xxxxxxxxxxxxxx
amount=50000
OPERATION=CRD
TransactionId=1012732100000017628

Optional

REFID=QAINTC01PSPID01
REFKIND=PSPID

URL

TEST:
https://ogone.test.v-psp.com/dl/Maintenance
PROD:
https://secure.ogone.com/dl/Maintenance

Mandatory

PSPID=PSPIDRESTY02
USERID=RestyAPIUser01
PSWD=xxxxxxxxxxxxxxx
amount=1000
CURRENCY=EUR
ORDERID=RESOperation001
CARDNO=48xxxxxxxxxxxx67
ED=1216
CVC=123
OPERATION=RES

Optional

REFID=MG_RESTY_01
REFKIND=MGID

URL

TEST:
https://ogone.test.v-psp.com/dl/NewOrder
PROD:
https://secure.ogone.com/dl/NewOrder

REN

Mandatory

PSPID=ECOMRDSPSPID11
USERID=Cust_12240_API_USER

PSWD=xxxxxxxxxxxxxxx
OPERATION=REN
PAYID=3002492108

Optional

REFID=ECOMRDS.MGP00

REFKIND=MGID

URL

TEST:
https://ogone.test.v-psp.com/dl/Maintenance
PROD:
https://secure.ogone.com/dl/Maintenance

SAL

Mandatory

PSPID=ECOMRDSPSPID11
USERID=Cust_12240_API_USER
PSWD=xxxxxxxxxxxxxxxx
OPERATION=SAL
amount=1000
currency=EUR
ORDERID=MerchReffdhgf4hgf56
CARDNO=48XXXXXXXXXXXX67
ED=1216
CVC=123

Recommended

REQUESTID=SALOperation01

Optional

REFKIND=MGID
REFID=ECOMRDS.MGP00

URL

TEST:
https://ogone.test.v-psp.com/dl/NewOrder
PROD:
https://secure.ogone.com/dl/NewOrder

SAS

Mandatory

PSPID=ECOMRDSPSPID11
USERID=Cust_12240_API_USER
PSWD=xxxxxxxxxxxxxxx
OPERATION=SAS
amount=1000
currency=EUR
ORDERID=MerchReffdhgf4hgf55
CARDNO=48XXXXXXXXXXXX67
ED=1216
CVC=123

Recommended

REFKIND=MGID
REFID=ECOMRDS.MGP00

Optional

REQUESTID=SASOperation01

URL

TEST:
https://ogone.test.v-psp.com/dl/NewOrder
PROD:
https://secure.ogone.com/dl/NewOrder

DEL

Mandatory

PSPID=ECOMRDSPSPID11
USERID=Cust_12240_API_USER

PSWD=xxxxxxxxxxxxxxx
OPERATION=DEL
PAYID=3002492530

Recommended

REQUESTID=DELOperation001

Optional

REFKIND=MGID
REFID=ECOMRDS.MGP00

amount=1000
currency=EUR

URL

TEST:
https://ogone.test.v-psp.com/dl/Maintenance
PROD:
https://secure.ogone.com/dl/Maintenance

DES

Mandatory

PSPID=ECOMRDSPSPID11
USERID=Cust_12240_API_USER

PSWD=xxxxxxxxxxxxxxx
OPERATION=DES

PAYID=3002492530

Recommended

REQUESTID=DESOperation001

Optional

REFKIND=MGID
REFID=ECOMRDS.MGP00
amount=1000
currency=EUR

URL

TEST:
https://ogone.test.v-psp.com/dl/Maintenance
PROD:
https://secure.ogone.com/dl/Maintenance

RFD

Mandatory

PSPID=ECOMRDSPSPID11
CURRENCY=EUR
USERID=Cust_12240_API_USER
PSWD=xxxxxxxxxxxxxxx
amount=1
OPERATION=RFD
TransactionId=9000003002450295000

Optional

REFID=ECOMRDS.MGP00
REFKIND=MGID

URL

TEST:
https://ogone.test.v-psp.com/dl/Maintenance
PROD:
https://secure.ogone.com/dl/Maintenance

RFS

Mandatory

PSPID=ECOMRDSPSPID11
USERID=Cust_12240_API_USER
PSWD=xxxxxxxxxxxxxxx
amount=1
CURRENCY=EUR
OPERATION=RFS
TransactionId=9000003002450295000

Optional

REFID=ECOMRDS.MGP00
REFKIND=MGID

URL

TEST:
https://ogone.test.v-psp.com/dl/Maintenance
PROD:
https://secure.ogone.com/dl/Maintenance

QUERY

Mandatory

PSPID=ECOMRDSPSPID11
USERID=Cust_12240_API_USER
PSWD=xxxxxxxxxxxxxx
PAYID=3002492530

Optional

REFID=ECOMRDS.MGP00
REFKIND=MGID
PAYIDSUB=1

URL

TEST:
https://ogone.test.v-psp.com/dl/Query
PROD:
https://secure.ogone.com/dl/Query

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
Example:

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"

FAQs

On this support site you can find all manuals presenting our products. Feel free to browse these documents.

With the activation of your account, our Reconciliation tool is automatically available to you if you have a Full Service account or you benefit from Collect acquiring. This enables you to easily reconcile the payments you receive on your bank account with the orders/transactions in your Ingenico account. To read more about Reconciliation tool click here.

Ingenico Group offers right, secure, smart and seamless payment solutions whatever the channel: in-store, online and mobile. Ingenico Group provides merchants with a comprehensive and innovative range of services and solutions that eliminate payment complexity and make purchasing quick, seamless and secure for various sales channels and payment methods.  

Ingenico Group comprises of three divisions: Ingenico Smart Terminals, Ingenico Payment Services and Ingenico ePayments. Through our comprehensive range of smart terminals, payment services and mobile solutions, we facilitate merchants’ in-store and online payments acceptance.

Now known as Ingenico ePayments, Ogone was a leading pan-European online payment services provider, which was acquired by Ingenico Group in 2013 and merged with GlobalCollect in 2015 to become Ingenico ePayments.

To honor Ogone’s significant legacy and its name, the term Ogone is now used to describe Ingenico ePayments platform, which includes Ingenico Collect, a one-stop payment solution that enables merchants to offer preferred payment methods in many different countries, without the hassle of having to open multiple bank accounts or form new legal entities.

With its Ogone platform and other offerings, Ingenico ePayments goes beyond payments by offering global consultancy services on topics including local regulations, regional payment customs and preferences, and fraud and compliancy.

In the past and prior to taking on the name Ingenico ePayments, Ogone was temporarily named Ingenico Payment Services. However, once Ogone joined forces with GlobalCollect, the two came together under a new unified name: Ingenico ePayments.

Today, Ingenico Payment Services is a separate division of Ingenico Group that provides merchants with a comprehensive range of centralized and secure in-store transaction management services. Ingenico Payment Services ensures end-to-end security, control and monitoring of merchants transactions thanks to a centralized payment solution dedicated to organized retailers.

In addition, Ingenico Payment Services has a full range of customer loyalty solutions to increase merchant revenue, including: loyalty card programs and loyalty program management, prepaid cards and gift card management, customer data analysis and marketing campaign management.

As a payment service provider, Ingenico Financial Solutions SA collects, processes and reports payments on behalf of companies that sell products and services via the internet. These companies have authorized us to debit your account in order to complete your purchase of a product or service. 

Please note that Ingenico Financial Solutions SA is not authorized to provide you with information about entries on your statement. For all inquiries about a payment, please contact the company where you made your purchase directly. 

However, should you need help with identifying the merchant, please provide our Customer Care department with relevant information via e-mail or phone.

A SEPA mandate is easier to arrange and you as a merchant would not be burdened by paying our invoices manually.

In your Ingenico account menu, you can easily lookup your transactions by choosing "Operations" and then clicking either "View transactions" or "Financial history", depending on the type of transaction results you're looking for.

Go to Consult your transactions for more information.

By default you can send goods or deliver your service once a transaction has reached the status "9 - Payment requested". However, although status 5 is a successful status, it's only a temporary reservation of an amount of money on the customer's card. A transaction in status 5 still needs to be confirmed (manually or automatically) to proceed to the status 9, which is the final successful status for most payment methods.

Go to Transaction statuses for more information.

You can easily refund a payment with the "Refund" button in the order overview of a transaction (via View transactions). If your account supports it, you can also make refunds with a DirectLink request or with a Batch file upload (for multiple transactions).

Please note that the Refunds option has to be enabled in your account.

Go to Maintain your transactions for more information.

A full green thumbs-up icon means that the transaction was completed with a 3-D Secure authentication method, such as Digipass or a card reader. However, it doesn't necessarily mean the payment itself was processed successfully. Therefore, you should always check the transaction status to know whether you'll receive your money.

Go to Transaction statuses for more information.

Ingenico offers a complete suite of flexible products, sophisticated technologies and dedicated expertise to help you manage and optimize your online fraud prevention practices. Our industry-leading fraud detection tools and experts bring over 20 years of industry and regional expertise, and we will work closely with you to develop, implement and manage a holistic fraud solution that includes prevention, detection and management. We also offer comprehensive chargeback management and dispute management solutions. 

By working with Ingenico, you can pick the solutions that best fit your needs and customize our services to either outsource fraud management functionalities or keep them in-house with our ongoing support.

If you want to check specific details of an order/transaction or perform maintenance on transactions, you should use View transactions. "Financial history" is the most convenient to periodically check incoming and outgoing funds.

For more information, go to View transactions vs Financial history.

You can only perform refunds on transactions which have already received status 9 for at least 24 hours. A cancellation or deletion can be done within approximately 24 hours after final status has been received (status 9 or 5).

To know the cut-off time of the acquirer, we recommend you to check directly with our Customer Care department.