Icepay Rest API Manual

REST API Implementation manual
Version 1.0
Table of Contents
1 License Conditions REST API .................................................................................................................................. 3
2 Introduction ............................................................................................................................................................ 5
2.1 Who is this document for? ...................................................................................................... 5
2.2 Glossary ................................................................................................................................... 5
2.3 Integration with ICEPAY ........................................................................................................... 5
2.3.1 Payment process.............................................................................................................. 5
2.3.2 Webshop Modules ........................................................................................................... 6
2.3.3 API.................................................................................................................................... 6
3 Starting your implementation ............................................................................................................................... 6
3.1 REST and JSON ......................................................................................................................... 6
3.2 Security .................................................................................................................................... 6
3.3 Important considerations during implementation................................................................... 6
3.4 How to make a request to the API ........................................................................................... 7
3.5 URL........................................................................................................................................... 7
3.6 HTTP headers ........................................................................................................................... 7
3.7 Basic object structure .............................................................................................................. 8
3.8 Examples .................................................................................................................................. 8
3.8.1 Request ............................................................................................................................ 8
3.8.2 Response.......................................................................................................................... 8
3.9 Available services and operations ............................................................................................ 9
3.9.1 Payment operations......................................................................................................... 9
3.9.2 Refund operations ........................................................................................................... 9
4 Checksum ................................................................................................................................................................ 9
4.1 How to calculate ...................................................................................................................... 9
5 Operation parameters..........................................................................................................................................10
5.1 Payment Service .................................................................................................................... 11
5.1.1 Checkout ........................................................................................................................ 11
5.1.2 VaultCheckout ............................................................................................................... 12
5.1.3 AutomaticCheckout ....................................................................................................... 13
5.1.4 GetPayment ................................................................................................................... 13
5.1.5 GetMyPaymentMethods ............................................................................................... 14
5.2 Refund service ....................................................................................................................... 15
5.2.1 RequestRefund .............................................................................................................. 15
5.2.2 CancelRefund ................................................................................................................. 16
5.2.3 GetPaymentRefunds ...................................................................................................... 16
ICEPAY | REST API Implementation manual | v1.0 | 1

6 Error messages .....................................................................................................................................................17
6.1 General .................................................................................................................................. 17
6.2 Refund service ....................................................................................................................... 18
Change Log
Version Date Changes Author
1.0 2015-10-01 Initial version Simon Strijbos
Related Documents
Title Version Document location
Supported Parameters Sheet Latest https://icepay.com/downloads/tech-
docs/ICEPAY_Supported_Parameters_Sheet.pdf
ICEPAY Terms & Conditions EN Latest https://icepay.com/downloads/pdf/company/TC-2015-EN.pdf
ICEPAY Terms & Conditions NL Latest https://icepay.com/downloads/pdf/company/AV-2015-NL.pdf
ICEPAY Terms & Conditions FR Latest 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 b efore 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 applica ble
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
Term Definition
Merchant A company that processes payments through the ICEPAY transaction
platform. An ICEPAY client can have several Merchants (websites/webshops).
Consumer The customer of the Merchant. The end-user who makes a payment through
the website/webshop of the Merchant. Also referred to as Customer.
Postback Asynchronous message sent when the payment status changes.
Checksum Digital signature used to sign all messages.
Secret Pre-shared key used in checksum calculation. You can find your secret when
you log in to https://portal.icepay.com
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:
- Compatibility with various programming languages and frameworks

- 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.
Header name Description

Checksum Your calculated checksum which verifies you as the sender of the
message. See 4.1 for the checksum calculation method.
MerchantID Your 5-digit MerchantID (not to be confused with the CompanyID)
given to you when you registered with ICEPAY.

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",
...
}
Property Description
Timestamp The date and time in UTC when your request was generated.
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
{
"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.
Service Description
Payment All methods related to performing payments, retrieving active payment
methods, retrieving payment information, etc.
Refund All refund operations.
3.9.1 Payment operations

Operation Description
Checkout Initiate a new payment
VaultCheckout Initiate a payment that will result in storing consumer data in our data
vault
AutomaticCheckout Perform recurring payment with a previously stored consumer’s data
GetPayment Retrieve details and status of a specific payment
GetMyPaymentMethods Retrieve all active payment methods and available issuers. This
operation can be used to populate the payment method selection
screen at merchant side.
3.9.2 Refund operations

Operation Description
RequestRefund Initiate a new refund on an existing successful payment
CancelRefund Cancel a pending refund before execution
GetPaymentRefunds Get all refunds done or requested for a specific payment
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:

a. The full URL of the request
b. The HTTP verb (always POST) in uppercase
c. Your 5-digit merchant ID
d. Your 40-characer secret code
e. 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/POST1234
5AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd{"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 Supported

Parameters Sheet (see link above) specifies for the allowed countries for each payment
method.
5.1 Payment Service

5.1.1 Checkout
Request
Member Description Data type

Timestamp This is the current UTC time that must have the following String
format: yyyy-mm-ddThh:mm:ssZ
Example: 2015-01-01T01:30:00Z
Amount This is the amount (in cents) that will be charged Integer
Country The 2-character ISO country code of the country of origin for String
the consumer, used to validate if the payment method is
supported in a certain country.
Currency This is the currency. String
Description A description of the payment. String
EndUserIP IP address of the end-user. String
Issuer This is the issuer of the payment method. String
Language Language of the payment screen. String
OrderID - A unique code up to 10 characters. String
- It is recommended to use the primary key field of
your local transactions table.
PaymentMethod This is the payment method that will be used for the String
transaction initialization.
Reference Custom information that you want to include, e.g. primary String
key of your local transactions table (up to 50 characters).
URLCompleted - The URL to which the end-user will be redirected. String
- If you do not set this member then the
URLCompleted that you set in your ICEPAY account
will be used.
URLError - The URL to which the end-user will be redirected. String
- If you do not set this member then the URLError that
you set in your ICEPAY account will be used.
Response

Timestamp This will be the current UTC time that has the following String
Example: 2015-01-01T01:30:00Z
Amount The requested amount in cents. Integer
Country This is the requested country code. String
Currency This is the requested currency. String
Description This is the specified description. String
EndUserIP This is the provided end-user IP. String
Issuer This is the requested issuer. String
Language This is the requested language code. String
OrderID This is your provided Order ID. String
PaymentID This is the generated ICEPAY transaction ID. Integer

Tip: if possible please store this in your local database
as this ID may come in handy if you contact our support
department.
PaymentMethod This is the requested Payment Method. String
PaymentScreenURL This is the URL of the payment screen (if available). String
ProviderTransactionID This is the transaction ID of the issuer (if available). String
Reference This is the specified reference information. String
TestMode Indicates whether the transaction was initialized in test Boolean
mode. This is true if your API key is still in test mode.
To switch to production mode, please contact your
account manager
URLCompleted This is the page to which the end-user will be String
redirected to after a successful transaction.
URLError This is the page to which the end-user will be String
redirected to after a failed or cancelled transaction.
5.1.2 VaultCheckout
Request

PaymentMethod Description of the payment method which will be used in the String
payment at the moment vaulting is supported for ‘credit card’
and ‘iDEAL’.
Amount The amount of the transaction. Integer
Language The ISO code of the language e.g. Dutch is ‘NL’ String
Currency The ISO code of the currency e.g. Euro is ‘EUR’ String
Country The ISO code of the country e.g. Netherlands is ‘NL’ String
Issuer The issuer connected to the payment method String
E.g. For credit card can be ‘VISA’ or ‘MASTERCARD’
ConsumerID The ID which is wished to link to the consumer credit card or String
bank account to perform automatic checkouts.
It can be alphanumeric.
Timestamp This is the current UTC time that must have the following format: String
yyyy-mm-ddThh:mm:ssZ
Example: 2015-01-01T01:30:00Z
OrderID It is the Unique OrderID of the transaction. String
Description It is the description which appears along the payment in the String
ICEPAY’s environment.
EndUserIP Is the ip address of the customer’s machine String
URLCompleted Is the url where the user is redirected after successful payment. String
URLError Is the url where the user is redirected after erroneous payment. String
Reference This field can be empty String
Response
See the CheckoutResponse under 5.1.1

5.1.3 AutomaticCheckout
Request

PaymentMethod Can have two values: String
 ‘ddebit’ this is required to perform an automatic checkout
prior to storing an iDEAL account number.
 ‘creditcard’ this is required to perform an automatic
checkout prior to storing a credit card number.
The keywords are not case sensitive.
Amount The amount to be billed in whole cents. Integer
Language Is the language code of the billing e.g. for the Netherlands ‘NL’ String
Currency Is the currency code e.g. for euro ‘EUR’ String
Country Is the country code e.g. for the Netherlands ‘NL’ String
Issuer This depends on the payment method insert before: String
 For ‘creditcard’ must be ‘CCAUTOCHECKOUT’
 For ‘ddebit’ must be ‘IDEALINCASSO’
ConsumerID This is the ConsumerID, which was vaulted previously using the String
VaultCheckout method.
Example: 2015-01-01T01:30:00Z
OrderID Is the OrderID corresponding to the transaction. String
Description An optional description, which can be left empty String
EndUserIP Is the IP address of the machine from which the action is String
performed.
URLCompleted Is the URL where the user lands upon a successful transaction. String
Reference Can be an additional remark, may be left empty. String
Response

Success Indicates whether the operation had been successfully completed. Boolean
5.1.4 GetPayment
Request

Example: 2015-01-01T01:30:00Z
PaymentID This is the ICEPAY PaymentID. You will receive this when you Integer
initialize a payment or in your Postback.
Response


Example: 2015-01-01T01:30:00Z
PaymentID The ICEPAY PaymentID. Integer
Amount The requested amount of the payment. Integer
Currency The requested currency of the payment. Integer
Description The description specified by the merchant during the
initialization.
Duration The numbers of seconds dialled. Only applicable for phone Integer
payments.
ConsumerName Name of the consumer (if available). String
ConsumerAccountNu Partial account number of the consumer (if available). String
mber
ConsumerAddress Address of the consumer (if available). String
ConsumerHouseNum House number of the address of the consumer (if available). String
ber
ConsumerCity City of the consumer (if available). String
ConsumerCountry Country of the consumer (if available). String
ConsumerEmail E-mail address of the consumer (if available). String
ConsumerPhoneNum Phone number of the consumer (if available). String
ber
ConsumerIPAddress IP address of the consumer (if available) String
Issuer Requested payment method issuer String
OrderID The OrderID specified by the merchant during the String
initialization
OrderTime The time the payment was started. In UTC. String
PaymentMethod The requested payment method String
PaymentTime The time indicating when the payment was closed/completed String
(successful or unsuccessful). In UTC.
Reference The reference specified by the merchant during the String
initialization.
Status The status of the payment (please see 5.1.1 for possible String
statuses).
StatusCode A description giving you more information on the status. String
TestMode Indicates whether the payment was created when the API Boolean
key was still in test mode.
5.1.5 GetMyPaymentMethods
Request

Example: 2015-01-01T01:30:00Z
Response

PaymentMethods A list of PaymentMethod objects describing all available Array of
payment methods. PaymentMethod

PaymentMethod object

PaymentMethodCode Text identifier of the payment method. This is the input String
for the PaymentMethod parameter of the Checkout
methods.
Description Description of the payment method. String
Issuers Contains all available issuers for the payment method. Array of Issuer
Issuer object

IssuerKeyword Text identifier of the issuer. This is the input for the Issuer String
parameter of the Checkout methods.
Description Description of the issuer. String
Countries Contains all available countries for the issuer. Array of Country
Country object

CountryCode Text identifier of the country. This is the input for the Country String
parameter of the Checkout methods.
Currency 3-letter code for the applicable currency in the country. String
MinimumAmount The minimum payment amount required for this combination of Integer
payment method, issuer and country.
MaximumAmount The maximum payment amount allowed for this combination of Integer
payment method, issuer and country.
5.2 Refund service

5.2.1 RequestRefund
Request
Parameter Description Data type

Timestamp This is the current UTC time that must have the String
following format: yyyy-mm-ddThh:mm:ssZ
Example: 2015-01-01T01:30:00Z
PaymentID The ID of the payment. Integer
RefundAmount The amount to be refunded (in cents). Integer
RefundCurrency The currency of the refund. String
Remark: This currency must match the currency of the
payment.

Response

Example: 2015-01-01T01:30:00Z
RefundID This is the ID of the requested refund. If possible, it is Integer
recommended to store this value in your system as you
may decide (at a later stage), to cancel the refund
request.
PaymentID This is the payment for which you requested a refund. Integer
RefundAmount The requested refund amount specified in the request. Integer
RemainingRefundAmount The remaining amount that you can still request a refund Integer
for.
RefundCurrency The requested refund currency specified in the request. String
5.2.2 CancelRefund
Request

Example: 2015-01-01T01:30:00Z
RefundID This is the RefundID that is returned by the RequestRefund web Integer
method upon a successful invocation.
PaymentID This is the PaymentID of the transaction, which you requested a Integer
refund for initially.
Response

Timestamp This is the current UTC time that must have the following format: yyyy- String
mm-ddThh:mm:ssZ
Example: 2015-01-01T01:30:00Z
Success This field will contain the value ‘Y’ if the refund request was cancelled String
successfully.
5.2.3 GetPaymentRefunds
Request

Example: 2015-01-01T01:30:00Z
PaymentID This is the PaymentID of the transaction for which you requested the Integer
refund initially.

Response

Example: 2015-01-01T01:30:00Z
Refunds A collection of Refund objects. If you have done several partial refunds, Array of
then this collection contains several objects. Refund
Refund object

RefundID This is a unique ID that is assigned to your refund request. Integer
RefundAmount This is the amount of the refund. Integer
RefundCurrency This is the currency of the refund. String
DateCreated This value indicates when the refund request was created (in String
UTC+0): yyyy-mm-ddThh:mm:ssZ
Example: 2015-01-01T01:30:00Z
Status A refund can have one of the following status: String
PENDING Refund is placed in the queue
PROCESSING Refund sent to financial institution for refund
COMPLETED Refund processed by financial institution
REFUSED Refund cannot be processed
6 Error messages
6.1 General
Error code Description
ERR_0000 Internal server error: XXX
An unexpected error occurred.
Please contact support@icepay.eu with the full merchant web shop database log
to resolve.
ERR_0001 Request is missing
You did not provide a request object with the web method.
ERR_0002 Please provide a valid 'MerchantID' member
You must provide a valid numeric 'MerchantID' member.
ERR_0003 Please provide the 'XXX' member
You forgot to include a member in your web method request object.
Where XXX is the name of the member that you forgot to include.
ERR_0004 Please provide the IP address of your end-user
You forgot to include the IP address of the end-user.
ERR_0005 Merchant 'XXXXX' is disabled
Your API key is disabled.
Please contact your account manager regarding this issue.
ERR_0006 Merchant 'XXXXX' was not found
Unknown MerchantID
ERR_0007 Checksum for 'XXX' is invalid
The provided checksum did not match.
Where XXX is the name of the web method for which the checksum failed.

Please make sure the hash of the checksum is in lower case.
ERR_0008 You can only invoke this method using the 'XXX' payment method
This exception means that the web method can only be used in conjunction with
the XXX payment method.
ERR_0009 Payment with ID 'XXX' not found
ERR_0010 ‘XXX’ parameter must be at least YY characters
The length of the provided parameter must be at least YY characters long.
ERR_0011 ‘XXX’ parameter may not exceed YY characters
The length of the parameter has exceeded the maximum allowed length YY.
ERR_0012 ‘XXX’ is an invalid payment method
ERR_0013 Invalid date: X
The provided date is in an invalid format.
Please provide a string in the following format:
YYYY-MM-DD or YYYY-MM-DD HH:MM
ERR_0014 Invalid date period
Please provide a valid month and year combination.
ERR_0015 The provided country code ‘XX’ is invalid
ERR_0016 Payment does not belong to specified merchant
You (accidently) specified a PaymentID that does not belong to the specified
merchant.
6.2 Refund service

Error Code Description
ERR_2000 Merchant not granted to use Refund Web Service
The merchant is not granted access to use the Refund Web Service. In order to
enable the Refund Web Service for your merchant, please log into your ICEPAY
account to configure your merchants.
ERR_2001 Invalid RefundID ‘XXX’
The RefundID that you provided is invalid. Please check the RefundID.
ERR_2002 Amount to refund exceeds remaining balance
You were trying to initiate a refund request with an amount that is larger than the
requested amount.
ERR_2003 Payment method is not supported by the Refund Web Service
The payment method used for the provided payment does not support refund
possibilities.
ERR_2004 Invalid RefundAmount
Please make sure that:
- The amount is in cents
- The amount is positive
ERR_2005 Refund currency does not match payment currency
ERR_2006 You can only refund payments with the status 'OK'
ERR_2007 RefundID does not belong to PaymentID

Icepay Rest API Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Icepay Rest API Manual

Uploaded by

Copyright:

Available Formats

REST API Implementation manual

ICEPAY | REST API Implementation manual | v1.0 | 1

ICEPAY | REST API Implementation manual | v1.0 | 2

1.1 ICEPAY REST API:

2. User License conditions REST API

3. User License ICEPAY REST API

4.2 ICEPAY B.V. makes no warranties, conditions, indemnities, representations or terms,

ICEPAY | REST API Implementation manual | v1.0 | 3

6. Additional work and support

8. General conditions and applicability

ICEPAY | REST API Implementation manual | v1.0 | 4

2.1 Who is this document for?

2.3 Integration with ICEPAY

- Compatibility with various programming languages and frameworks

2.3.1 Payment process

1) The consumer proceeds to checkout in the merchant’s webshop

ICEPAY | REST API Implementation manual | v1.0 | 5

3 Starting your implementation

3.1 REST and JSON

- A GET verb means read-only retrieval of information,

3.3 Important considerations during implementation

ICEPAY | REST API Implementation manual | v1.0 | 6

3.4 How to make a request to the API

- The API URL

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

A full API URL would have the following format:

3.6 HTTP headers

The header MerchantID identifies the beneficiary of the payment.

Header name Description

ICEPAY | REST API Implementation manual | v1.0 | 7

POST /webservices/api/v1/payment/checkout/ HTTP/1.1

ICEPAY | REST API Implementation manual | v1.0 | 8

3.9 Available services and operations

3.9.1 Payment operations

3.9.2 Refund operations

4.1 How to calculate

ICEPAY | REST API Implementation manual | v1.0 | 9

1) Build up a base string consisting of the following data:

2) Ensure the base string is UTF-8 encoded

ICEPAY | REST API Implementation manual | v1.0 | 10

5.1 Payment Service

Member Description Data type

Member Description Data type

ICEPAY | REST API Implementation manual | v1.0 | 11

Member Description Data type

See the CheckoutResponse under 5.1.1

ICEPAY | REST API Implementation manual | v1.0 | 12

Member Description Data type

Member Description Data type

Member Description Data type

Member Description Data type

ICEPAY | REST API Implementation manual | v1.0 | 13

Member Description Data type

Member Description Data type

ICEPAY | REST API Implementation manual | v1.0 | 14

Member Description Data type

Member Description Data type

Member Description Data type

5.2 Refund service

Parameter Description Data type

ICEPAY | REST API Implementation manual | v1.0 | 15

Member Description Data type

Parameter Description Data type

Member Description Data type