rest api implementation manual - icepay · icepay | rest api implementation manual | v1.0 | 6 2.3.2...
TRANSCRIPT
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
ICEPAY | REST API Implementation manual | v1.0 | 2
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
ICEPAY | REST API Implementation manual | v1.0 | 3
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.
ICEPAY | REST API Implementation manual | v1.0 | 4
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.
ICEPAY | REST API Implementation manual | v1.0 | 5
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
ICEPAY | REST API Implementation manual | v1.0 | 6
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
ICEPAY | REST API Implementation manual | v1.0 | 7
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.
ICEPAY | REST API Implementation manual | v1.0 | 8
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",
ICEPAY | REST API Implementation manual | v1.0 | 9
"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.
ICEPAY | REST API Implementation manual | v1.0 | 10
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:
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
ICEPAY | REST API Implementation manual | v1.0 | 11
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
Member Description Data type
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
ICEPAY | REST API Implementation manual | v1.0 | 12
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
Member Description Data type
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
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
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
ICEPAY | REST API Implementation manual | v1.0 | 13
5.1.3 AutomaticCheckout Request
Member Description Data type
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
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
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
Member Description Data type
Success Indicates whether the operation had been successfully completed. Boolean
5.1.4 GetPayment 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
PaymentID This is the ICEPAY PaymentID. You will receive this when you initialize a payment or in your Postback.
Integer
Response
Member Description Data type
Timestamp This is the current UTC time that must have the following format: yyyy-mm-ddThh:mm:ssZ
String
ICEPAY | REST API Implementation manual | v1.0 | 14
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
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
Response
Member Description Data type
PaymentMethods A list of PaymentMethod objects describing all available payment methods.
Array of PaymentMethod
ICEPAY | REST API Implementation manual | v1.0 | 15
PaymentMethod object
Member Description Data type
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
Member Description Data type
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
Member Description Data type
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
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
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
ICEPAY | REST API Implementation manual | v1.0 | 16
Response
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
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
Parameter 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
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
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
Success This field will contain the value ‘Y’ if the refund request was cancelled successfully.
String
5.2.3 GetPaymentRefunds Request
Parameter 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
PaymentID This is the PaymentID of the transaction for which you requested the refund initially.
Integer
ICEPAY | REST API Implementation manual | v1.0 | 17
Response
Parameter 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
Refunds A collection of Refund objects. If you have done several partial refunds, then this collection contains several objects.
Array of Refund
Refund object
Parameter Description Data type
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.
ICEPAY | REST API Implementation manual | v1.0 | 18
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