2. General procedures and security settings
The following general procedures and security controls are valid for all DirectLink requests: new order requests, maintenance requests and direct queries.
2.1 API user
An API (Application Program Interface) user is needed to make DirectLink requests.
In general it's a user specifically designed to be used by an application to make automatic requests to the payment platform.
You can create an API user in your Ingenico ePayments account via "Configuration" > "Users". Select "New user" and fill the required fields.
To make the new user an API user, make sure to enable the "Special user for API (no access to admin.)" box.
Even though various user profiles are available for an API user, we strongly recommend you to configure this user with the "Admin" profile.
If you want to limit the rights for maintenance of transactions (refunds, cancellations etc.), you can still change the user profile to e.g. "Encoder".
If you are not sure, we recommend you to choose the "Admin" profile, otherwise go to User profiles (User Manager) for more information.
The password for an API user does not have to be changed regularly. This is more convenient when the password has to be hard-coded into your application. However, we recommend you to change the password from time to time.
For more information about User types and how to change the API user's password, go to User types (User Manager).
2.2 Request form
For new order requests, maintenance requests and direct queries, you must send requests with certain parameters to specific URLs. The new order/maintenance/query parameters must be sent in a POST request as follows:
The type/subtype indicating the Media Type in the Content-Type entity-header field in the POST request needs to be "application/x-www-form-urlencoded".
DirectLink works in “one request-one reply” mode; each payment is processed individually. Our system handles individual transaction requests via DirectLink and can work synchronously (where this option is technically supported), i.e. we wait for the bank’s reply before returning an XML response to the request.
When we receive a request on our servers, we check the level of encryption and the IP address which the request was sent from.
DirectLink is built on a robust, secure communication protocol. DirectLink API is a set of instructions submitted with standard HTTPS POST requests.
At the server end, we use a certificate delivered by Verisign. The TLS encryption guarantees that it is our servers you are communicating with and that your data is transmitted in encrypted form. There is no need for a client TLS certificate.
When we receive a request, we check the level of encryption. We allow merchants to connect to us only in secure https mode using TLS protocols and we strongly recommend to use the most recent and secure versions which are currently TLS 1.1 and 1.2.
2.3.2 IP address
For each request, our system checks the IP address from which the request originates to ensure the requests are being sent from your (the merchant’s) server. In the IP address field in the "Checks for DirectLink" section of the "Data and origin verification" tab in your account's Technical Information page, you must enter the IP address(es) or IP address range(s) of the servers that send your requests.
If the originating IP address has not been declared in the given IP address field, you will receive the error message “unknown order/1/i/”. The IP address the request was sent from will also be displayed in the error message.
2.3.3 SHA signature
The SHA signature is based on the principle of your (the merchant’s) server generating a unique character string for each order, hashed with the SHA-1, SHA-256 or SHA-512 algorithms. The result of this hash is then sent to us in your order request. Our system reconstructs this signature to check the integrity of the order data sent to us in the request.
Go to SHA-IN Signature (Ingenico ePayments e-Commerce documentation) - the principle is the same in e-Commerce and DirectLink mode.
For DirectLink, the SHA-IN passphrase needs to be configured in the "Checks for DirectLink" section of the "Data and origin verification" tab in your Technical information page.
2.4 Response parsing
We will return an XML response to your request. Please ensure that your systems parse this XML response as tolerantly as possible to avoid issues in the future, e.g. avoid case-sensitive attribute names, do not prescribe a specific order for the attributes returned in responses, ensure that new attributes in the response will not cause issues, etc.