Concepts

The Ingenico Connect API has been designed as a REST API. It uses the HTTP protocol as its foundation. Each resource is accessible under a clearly named URL and the HTTP response codes are used to relay status. HTTP Verbs like GET and POST are used to interact with the resources. To support accessibility by clients directly, as opposed to your server, our servers support cross-origin resource sharing. We use JSON for all of our payloads, including error
messages

All these characteristics mean that you will be able to use standard off the shelf software to interact with Ingenico ePayments. To make the integration even easier, Ingenico ePayments also has SDKs that wrap both the complete Server API as well as the complete Client API.

To help you get started the below documentation is richly annotated with ready to be used code examples for each of the SDKs as well as JSON examples. These examples can be used against our sandbox. If you haven’t already, please create an account now.

Server and Client API

We offer two RESTful APIs: A server API which is used for your server-to-server integration and a client API which is used by clients like desktops, laptops, mobile phones and other internet connected devices. The Client API will be consumed on the devices of your clients and supports less functionality as this device will not be under your full control. This API is designed to drive your UI to enabale you to collect the right information and safely encrypt it already on the client device.

Server API

The server API enables merchants to access the GlobalCollect platform functionality such as doing payments, starting hosted checkouts, creating tokens, and much more. All these calls require the caller to have a secret API key that merchants can look up in their Configuration Center account.

Client API

The client API enables clients such as mobile phones, browsers, and apps to access the hosted data on the GlobalCollect platform such as detailed information about the available payment products, profile management, and public keys used for encrypting sensitive data. These calls require a session id that the merchant can create using the server API.

Access to the Client API has to be granted through the Server API create session API call and is then granted for 2 hours. There is no limitation on the number of payments created during these 2 hours, however we do require any payment requests done within the context of a session to be submitted within those 2 hours as the encryption keys used for the client side encryption are also linked to the context of the session.

Multiple processing platforms

Ingenico Connect provides access to multiple Ingenico processing platforms through one integration. Currently two platforms are supported:

Most of the functionalities are not impacted by the processing platform that is behind Ingenico Connect, but there are some differences. Some of these differences will disappear as we rollout additional functionality during the beta phase for our connection to Ingenico’s Ogone Payment Platform. At this moment the following items are noticably different:

statusCode

The field status that is returned reflects the status of an object that has the same meaning regardless of the underlying processing platform. The raw statusCode of the underlying processing platform is also returned in the statusCode field as part of the statusOutput object. It is returned to ease the migration from the local APIs to Ingenico Connect. You should not write new business logic based on this field as it will be deprecated in a future version of the API. The value can also be found in the Global Collect Payment Console, the Global Collect report files and the Ogone BackOffice and report files.

captures

Ingenico’s Ogone Payment Platform supports multiple captures and Ingenico’s Global Collect Payment Platform does not yet support this. This means that for transactions processed on Ingenico’s Ogone Payment Platform a transaction can reach the PENDING_CAPTURE status, which requires a capture payment API call to initiate one or more captures. Each
of these capture requests result in a new Captures object with its own ID that can be interacted with. On Ingenico’s Global Collect Payment Platform such a transaction will reach PENDING_APPROVAL, which requires a approve payment API call to initiate the capture. This action will not result in a new capture object, but will put that transaction in the capture queue.

Tokens

Both processing platforms support tokenization, but the behavior is a bit different. Using a token for the processing of a payment is the same for both platforms. The creation and updating of a token however is done more implicitly on Ingenico’s Ogone Payment Platform, while its creation and especially the updating is explicit on Ingenico’s Global Collect Payment Platform. To update a token with a new value you simply submit a payment
request with both the token and the new data on Ingenico’s Ogone Payment Platform. This will automatically update the token with the new data. This behavior is not supported on Ingenico’s Global Collect Payment Platform, here you will explicitly have to submit a update token API call with the new data. The create a token from payment API call can only be used on Ingenico’s Global Collect Payment Platform. Note: In the future we will switch to using a central Ingenico tokenization platform and this will result in identical token behavior regardless of the platform.

Card payouts

This functionality is currently only supported on Ingenico’s Ogone Payment Platform. Please note that refunds are supported on both platorms.