REST API

Back

Download REST API Manual Download API PHP Download API.NET

Table of Contents:

  1. License Conditions REST API
  2. Introduction
  3. Starting your implementation
  4. Checksum
  5. Operation parameters
  6. Error messages

Change Log:

Related Documents:

Supported Parameters Sheet
ICEPAY Terms & Conditions EN
ICEPAY Terms & Conditions NL
ICEPAY Terms & Conditions FR
Latest
Latest
Latest
Latest
https://icepay.com/downloads/tech-docs/ICEPAY_Supported_Parameters_Sheet.pdf
https://icepay.com/downloads/pdf/company/TC-2015-EN.pdf
https://icepay.com/downloads/pdf/company/AV-2015-NL.pdf
https://icepay.com/downloads/pdf/company/TC-2015-FR.pdf

1. License Conditions REST API

  1. Definitions
    • 1.1 ICEPAY REST API: The software product provided by ICEPAY B.V. is on an ‘as is’ basis without a warranty of any kind.
    • 1.2 License: A written public act from the Dutch Central Bank (De Nederlandsche Bank) or other governmental body which provides ICEPAY B.V. with these rights.
  2. User License conditions REST API
    • 2.1 This User License Agreement applies to the use of this ICEPAY REST API, as supplied by ICEPAY B.V. (further referred to as ICEPAY B.V.).
    • 2.2 BY USING THE ICEPAY REST API YOU FULLY AGREE TO THE CONDITIONS OF THIS USER LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THIS USER LICENSE AGREEMENT, YOU SHOULD REFRAIN FROM USING THE ICEPAY REST API.
    • 2.3 You may only use the ICEPAY REST API if such is directly obtained from ICEPAY B.V. and provided from www.icepay.eu and if you or the organization where you work has entered into an official contract with ICEPAY B.V. and is therefore a Client in accordance with these conditions.
    • 2.4 This User License Agreement and the use of the ICEPAY REST API are governed by the laws of The Netherlands. Any disagreement will be placed before a qualified court in The Hague, The Netherlands. The United Nations Convention on Contracts for the International Sale of Goods (CISG) is not applicable.
  3. User License ICEPAY REST API
    • 3.1 ICEPAY B.V. grants Client the non-exclusive right to use this ICEPAY REST API and corresponding documentation. The license shall go into effect after Client has fulfilled all its obligations.
  4. Warranty Disclaimer
    • 4.1 The ICEPAY REST API is made available on an ‘as is’ basis only and without any warranty or indemnity of any kind.
    • 4.2 ICEPAY B.V. makes no warranties, conditions, indemnities, representations or terms, expressed or implied, whether by statute, custom, or otherwise as to any other matters, including but not limited to non-infringement of third party rights, integration, accuracy, security, availability, satisfactory quality, merchantability or fitness for any particular purpose.
  5. Limitations to indemnification and liability
    • 5.1 Client agrees to indemnify ICEPAY B.V. from all liability, losses, actions, damages or claims (including all reasonable costs and attorney costs) which flow forth or are regarding the use or dependency upon the ICEPAY REST API.
    • 5.2 Under no circumstances will ICEPAY B.V. be liable to Client, or any other person or entity, for any loss of use, revenue or profit, lost or damaged data, or other commercial or economic loss or for any direct, indirect, special, statutory, or consequential damages whatsoever related to the use or reliance upon ICEPAY REST API, even if advised of the possibility of such damages or if such damages are foreseeable. This limitation shall apply to each breach of this User License Agreement by ICEPAY B.V.
  6. Additional work and support
    • 6.1 All activities that ICEPAY B.V. must perform upon request of Client related to the use of the ICEPAY REST API that has been made available at no charge, shall be invoiced as additional work (or support) on the basis of actual costs according to the applicable rates of ICEPAY B.V.
    • 6.2 (Future) incompatibility problems (products are unable to interoperate with each other) can be resolved on the basis of additional work.
    • 6.3 It will be assumed that Client has agreed with the performance of additional work and the connected costs, if Client has allowed additional work to take place without raising objections in writing prior to the commencement of additional work.
  7. Duration
    • 7.1 This agreement is effective as of the moment of acceptance and may be terminated at any time by ICEPAY B.V. whereby a notice period of one week shall apply.
  8. General conditions and applicability
    • 8.1 The ICEPAY General Terms & Conditions apply to the agreement. The General Conditions ICEPAY are filed at the Chamber of Commerce in The Hague under number 27348492. The applicability of purchase conditions or any other conditions from Client or third parties is, then, expressly rejected by ICEPAY B.V. Client explicitly declares to have received, read and agreed to the ICEPAY General Terms & Conditions.

2. Introduction

  • 2.1 Who is this document for?
  • This REST API Implementation Manual is for the reference of developers wanting to make a custom implementation using the REST API gateway.

 

  • 2.2 Glossary
  • 2.3 Integration with ICEPAY
  • ICEPAY offers several gateways for merchants to connect through, including a SOAP Web Service and a REST API. Both these gateways offer seamless integration with your webshop, meaning that your end customers will not see any user interface at ICEPAY. The whole payment process can take place entirely in the webshop.An exception to the above is credit card, since PCI regulation puts heavy requirements on merchants who offer credit card number inputs directly in their webshop. Entry of credit card data takes place exclusively on a payment screen hosted by ICEPAY or by the credit card acquirer.The most popular method of web service integration today is using a JSON message structure over a RESTful API. RESTful architecture has the following properties:
      1. Compatibility with various programming languages and frameworks
      2. A considerably shorter implementation time

     

      • 2.3.1 Payment process
      • When using the REST API, the payment process is generally as follows:
          1. The consumer proceeds to checkout in the merchant’s webshop
          2. The consumer selects a payment method and additional information if applicable (such as their consumer bank in the case of iDEAL)
          3. The merchant performs a Checkout request
          4. ICEPAY returns a RedirectURL in the response
          5. The merchant redirects the consumer to the provided RedirectURL
          6. After paying, the consumer is returned to the merchant webshop at the URL provided in the website settings, or in the Checkout request
          7. ICEPAY sends the merchant webshop a Postback with the current status of the payment

         

      • 2.3.2 Webshop Modules
      • For merchants using well known webshop software (e.g. Magento, OSCommerce, WooCommerce), ICEPAY offers ready-to-install payment modules.

     

    •       2.3.3 API
      • For PHP developers, ICEPAY also offers a reusable API client that allows for quick implementation.

3. Starting your implementation

3.1 REST and JSON

REST (REpresentational State Transfer) is a web service architectural style. In general it means that aspects of the HTTP protocol are used to retrieve or manipulate data from a remote system. As in HTTP, a RESTful API is called with the combination of a URL and a verb. The verb indicates the type of action that is requested:

  • A GET verb means read-only retrieval of information,
  • Verbs such as POST, PUT and DELETE indicate adding, changing or removing data.

Since most operations involve performing a payment or refund, the verb POST is used by nearly all operations on the ICEPAY REST API.

JSON (JavaScript Object Notation) is a notation style to represent complex object structures in a serialized manner (i.e. transferable over the internet). It has the same role as XML, but is much less verbose and therefore faster.

3.2 Security

The ICEPAY REST API uses two layers of security to ensure two-way authentication of sender and receiver, and to prevent interception of messages and tampering.

SSL is used for transport security. All calls to the REST API must be done over HTTPS, ensuring end-to-end encryption of the message and authentication of ICEPAY as the recipient of your requests. A custom checksum algorithm using SHA256 is used to sign requests and responses. Using a pre-shared secret code, this algorithm authenticates the sender of requests and ensures that any response you receive really came from ICEPAY.

3.3 Important considerations during implementation

  • ICEPAY’s services are hosted in Microsoft Azure where we employ multiple geographical locations to optimize performance. This means that calls from your webshop might be assigned to a specific geographic location. The public IP address from which ICEPAY communicates to your webshop may therefore vary. Do not employ any form of IP whitelisting in your implementation. To verify the authenticity of responses and Postbacks from ICEPAY, the checksum should always be used.
  • All of ICEPAY’s payment services make use of secured connections. This means ICEPAY has an up to date SSL certificate that needs to be renewed every year. Do not cache any data regarding the SSL certificate as we may need to renew or replace the SSL certificate at any moment. To verify the identity of the ICEPAY service, validate the certificate itself with its root CA.
  • As our service continuously improves, we may need to add more parameters to request and response messages. Whenever possible any new request parameters will always be optional, but new response parameters may be added at any time. Ensure that your implementation does not break when receiving previously unknown parameters in the response.

 

3.4 How to make a request to the API

To make a basic Checkout call, a message must be sent to the API with the following information:

  •  The API URL
  •  The HTTP verb POST
  •  The Content-Type application/json
  •  HTTP headers MerchantID and Checksum, containing your merchant ID and message checksum
  •  A JSON-formatted body containing a valid Checkout object

The API will then return a JSON-formatted response body.

3.5 URL

The base URL for the API is: https://connect.icepay.com/webservice/api/v1/

The service and operation name follow on after the base URL. See Chapter 3.9 for a list of available services, and Chapter 5 for a list of operations per service.

A full API URL would have the following format: https://connect.icepay.com/webservice/api/v1//payment/checkout

This URL calls the Checkout operation under the Payment service.

3.6 HTTP headers

To authenticate the message, two values are sent as HTTP headers.

The header MerchantID identifies the beneficiary of the payment.

The header Checksum verifies that the merchant mentioned in the header MerchantID is also the sender of the message. See Chapter 4 for an explanation of how this is done.

3.7  Basic object structure

The basic JSON structure for every API call is formatted as below. Every message contains at least the field Timestamp. Every API operation has its own set of required or optional parameters.

{

“Timestamp”: “2015-01-01 00:00:00″, …

}

 

 

3.8 Examples

The examples below show what a basic message exchange between the web shop and the ICEPAY REST API involves. The parameters per operation are listed under Chapter 5.

 

3.8.1 Request

A basic HTTP request to the REST API may look like this:

POST /webservices/api/v1/payment/checkout/ HTTP/1.1
MerchantID: 12345
Checksum: 05b32c694c8b79bf77d6162df29364eb338de2038ac23b515826134dc311624e
Content-Type: application/json
{
“Timestamp”: “2015-01-01T00:00:00″,
“Amount”: “100”,
“Country”: “NL”,
“Currency”: “EUR”,
“Description”: “Order from the webshop”,
“EndUserIP”: “127.0.0.1”,
“PaymentMethod”: “IDEAL”,
“Issuer”: “ABNAMRO”,
“Language”: “NL”,
“OrderID”: “1000000123”,
“URLCompleted”: “https://mywebshop.com/Payment/Success”,
“URLError”: “https://mywebshop.com/Payment/Failure”
}

3.8.2 Response

The response to the above message is the following:

MerchantID: 12345
Checksum: b969a1fbb129fe623128b6b34b5a577af44a00b0e9d2ca322c2d5bdfaa0faf91
{

“Amount”: 100,
“Country”: “NL”,
“Currency”: “EUR”,
“Description”: “Order from the webshop”,
“EndUserIP”: “127.0.0.1”,
“Issuer”: “ABNAMRO”,
“Language”: “NL”,
“OrderID”: “1000000123”,
“PaymentID”: 123456789,
“PaymentMethod”: “IDEAL”,
“PaymentScreenURL”: “https://link.to.bank/payment_page”,
“ProviderTransactionID”: “”,
“Reference”: “”,
“TestMode”: false,
“URLCompleted”: “https://mywebshop.com/Payment/Success”,
“URLError”: “https://mywebshop.com/Payment/Failure”,
“MerchantID”: 12345
“Timestamp”: “2015-01-01T00:00:00″

}

3.9 Available services and operations

ICEPAY’s API operations are grouped under 4 services.

3.9.1 Payment operations

3.9.2 Refund operations

 

4. Checksum

The checksum is a digital signature that authenticates the sender of the message. This prevents others from sending payment requests in your name and prevents request tampering. It also assures you that any response or Postback you receive actually originated from ICEPAY.

  • 4.1 How to calculate
  • The checksum calculation for the REST API differs greatly from that of the classic Advanced Mode and Web Service gateways. In the REST API, the full JSON body message is used to calculate the checksum.This ensures all fields in the request are safe from tampering. This checksum algorithm is used for all requests to and responses from the REST API, but not in Postback messages.
  1. Build up a base string consisting of the following data:
    1. The full URL of the request
    2. The HTTP verb (always POST) in uppercase
    3. Your 5-digit merchant ID
    4. Your 40-characer secret code
    5. The full JSON-formatted body message, without formatting. This means no whitespace (spaces, tabs and newlines) between brackets and properties

    There should be no spaces or other characters inserted between the above data.
    Example:

    https://connect.icepay.com/webservice/api/v1/payment/checkout/POST12345AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd{“Timestamp”:”2015-01-01T00:00:00″}

  2. Ensure the base string is UTF-8 encoded
  3. Calculate a SHA256 hash over the base string and format the output as hexadecimal. Note: use a regular SHA256 hash, not an HMAC.

Example:

4c8b79bf77d6162df3305b32c698de20c8b79b38ac23b515826134dc311624e29364eb

With these steps you should have a 64-character, hex encoded string. This will be the value of the Checksum header.

5. Operation parameters

This chapter lists all possible parameters per API operation. For a list of all allowed values, and value combinations, please consult the parameters sheet available here:

https://icepay.com/downloads/tech-docs/ICEPAY_Supported_Parameters_Sheet.pdf

The parameters mentioned in this chapter form the JSON-formatted body of each request and response.

Important notes:

  • The field ‘issuer’ must always contain a value allowed under the chosen payment method. For example when paying with iDEAL, the issuer must be a Dutch consumer bank supporting iDEAL. When paying with credit cards, the issuer must be a supported credit card scheme for which you have a subscription.
  • Most payment methods are limited to certain countries. Some payment methods (iDEAL, Giropay, Carte Bleue etc.) are limited to one country, while others (Wire Transfer, SOFORT Banking) are limited to the SEPA area or to a certain part of the SEPA area. The SupportedParameters Sheet (see link above) specifies for the allowed countries for each payment method.

5.1 Payment Service

5.1.1 Checkout

Request

Response

5.1.2 VaultCheckout

Request

Response

See the CheckoutResponse under 5.1.1

 

5.1.3 AutomaticCheckout

Request

Response

 

5.1.4 GetPayment

Request

Response

 

5.1.5 GetMyPaymentMethods

Request

 

Response

 

PaymentMethod object

 

Issuer object

 

Country object

 

5.2 Refund service

5.2.1  RequestRefund

Request

 

Response

 

5.2.2 CancelRefund

Request

 

Response

 

5.2.3 GetPaymentRefunds

Request

 

Response

 

Refund object

 

6.  Error messages

6.1 General

 

6.2 Refund service