REST API Implementation manual - ICEPAY · ICEPAY | REST API Implementation manual | v1.0 | 6 2.3.2...

REST API Implementation manual

Version 1.0

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

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


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

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


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 rel iance 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

https://portal.icepay.com/


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

https://icepay.com/nl/en/webshop-modules/

https://github.com/ICEPAYdev/REST-API-PHP/releases


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.

https://connect.icepay.com/webservice/api/v1/

https://connect.icepay.com/webservice/api/v1/

https://connect.icepay.com/api/v1/payment/checkout

https://connect.icepay.com/api/v1/payment/checkout


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/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:


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 format: yyyy-mm-ddThh:mm:ssZ

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

String

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 the consumer, used to validate if the payment method is supported in a certain country.

String

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. - It is recommended to use the primary key field of

your local transactions table.

String

PaymentMethod This is the payment method that will be used for the transaction initialization.

String

Reference Custom information that you want to include, e.g. primary key of your local transactions table (up to 50 characters).

String

URLCompleted - The URL to which the end-user will be redirected. - If you do not set this member then the

URLCompleted that you set in your ICEPAY account will be used.

String

URLError - The URL to which the end-user will be redirected. - If you do not set this member then the URLError that

you set in your ICEPAY account will be used.

String

Response


Timestamp This will be the current UTC time that has the following format: yyyy-mm-ddThh:mm:ssZ

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

String

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 mode. This is true if your API key is still in test mode.

To switch to production mode, please contact your account manager

Boolean

URLCompleted This is the page to which the end-user will be redirected to after a successful transaction.

String

URLError This is the page to which the end-user will be redirected to after a failed or cancelled transaction.

String

5.1.2 VaultCheckout Request


PaymentMethod Description of the payment method which will be used in the payment at the moment vaulting is supported for ‘credit card’ and ‘iDEAL’.

String

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 E.g. For credit card can be ‘VISA’ or ‘MASTERCARD’

String

ConsumerID The ID which is wished to link to the consumer credit card or bank account to perform automatic checkouts. It can be alphanumeric.

String


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

String

OrderID It is the Unique OrderID of the transaction. String

Description It is the description which appears along the payment in the ICEPAY’s environment.

String

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:

‘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.

String

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:

For ‘creditcard’ must be ‘CCAUTOCHECKOUT’

For ‘ddebit’ must be ‘IDEALINCASSO’

String

ConsumerID This is the ConsumerID, which was vaulted previously using the VaultCheckout method.

String


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

String

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 performed.

String

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

String

PaymentID This is the ICEPAY PaymentID. You will receive this when you initialize a payment or in your Postback.

Integer

Response



String


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 payments.

Integer

ConsumerName Name of the consumer (if available). String

ConsumerAccountNumber

Partial account number of the consumer (if available). String

ConsumerAddress Address of the consumer (if available). String

ConsumerHouseNumber

House number of the address of the consumer (if available). String

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

ConsumerPhoneNumber

Phone number of the consumer (if available). String

ConsumerIPAddress IP address of the consumer (if available) String

Issuer Requested payment method issuer String

OrderID The OrderID specified by the merchant during the initialization

String

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 (successful or unsuccessful). In UTC.

String

Reference The reference specified by the merchant during the initialization.

String

Status The status of the payment (please see 5.1.1 for possible statuses).

String

StatusCode A description giving you more information on the status. String

TestMode Indicates whether the payment was created when the API key was still in test mode.

Boolean

5.1.5 GetMyPaymentMethods Request



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

String

Response


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

Array of PaymentMethod


PaymentMethod object


PaymentMethodCode Text identifier of the payment method. This is the input for the PaymentMethod parameter of the Checkout methods.

String

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 parameter of the Checkout methods.

String

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 parameter of the Checkout methods.

String

Currency 3-letter code for the applicable currency in the country. String

MinimumAmount The minimum payment amount required for this combination of payment method, issuer and country.

Integer

MaximumAmount The maximum payment amount allowed for this combination of payment method, issuer and country.

Integer

5.2 Refund service

5.2.1 RequestRefund Request

Parameter Description Data type


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

String

PaymentID The ID of the payment. Integer

RefundAmount The amount to be refunded (in cents). Integer

RefundCurrency The currency of the refund. Remark: This currency must match the currency of the

payment.

String


Response



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

String

RefundID This is the ID of the requested refund. If possible, it is recommended to store this value in your system as you may decide (at a later stage), to cancel the refund request.

Integer

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 for.

Integer

RefundCurrency The requested refund currency specified in the request. String

5.2.2 CancelRefund Request



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

String

RefundID This is the RefundID that is returned by the RequestRefund web method upon a successful invocation.

Integer

PaymentID This is the PaymentID of the transaction, which you requested a refund for initially.

Integer

Response



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

String

Success This field will contain the value ‘Y’ if the refund request was cancelled successfully.

String

5.2.3 GetPaymentRefunds Request



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

String

PaymentID This is the PaymentID of the transaction for which you requested the refund initially.

Integer


Response



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

String

Refunds A collection of Refund objects. If you have done several partial refunds, then this collection contains several objects.

Array of 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 UTC+0): yyyy-mm-ddThh:mm:ssZ

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

String

Status A refund can have one of the following status: 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

String

6 Error messages

6.1 General Error code Description

ERR_0000 Internal server error: XXX An unexpected error occurred. Please contact [email protected] 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.

mailto:[email protected]


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

REST API Implementation manual - ICEPAY · ICEPAY | REST API Implementation manual | v1.0 | 6 2.3.2...

Documents

Transcript of REST API Implementation manual - ICEPAY · ICEPAY | REST API Implementation manual | v1.0 | 6 2.3.2...