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 enbale you to collect the right information and safely encrypt it already on the client device.
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.
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.
Multiple processing platforms
Ingenico Connect provides access to multiple Ingenico processing platforms through one integration. Currently two platforms are supported:
- Ingenico’s Ogone Payment Platform (currently available in closed beta)
- Ingenico’s Global Collect Payment Platform
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 will 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:
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.
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.
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 implicit 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 future we will switch to using a central Ingenico tokenization platform and this will result in indetical token behavior regardless of the platform.
This functionality is currently only supported on Ingenico’s Ogone Payment Platform. Please note that refunds are supported on both platorms.
Services like convert amount and convert bank account are currently only available on Ingenico’s Global Collect Payment Platform.
For Ingenico’s Ogone Payment Platform the field returnUrl is required for all card transactions using the create payment API call. This is something we will change in one of our upcoming releases.