iCheckOutX – Integration manual

Version 2.3.3
Last update 2024-07-31
Author ZMS Info

Introduction

iCheckOutX is a WEB front-end service which simplifies web-shop integration with iPayGate by utilizing web technology and standard functionalities.

iCheckOutX provides:

Supported transactions types

iCheckOutX solution supports multiple transaction types and payment channels.
Supported transaction types include:

Purchase using QR codes

iCheckOutX System Architecture

The architecture of typical high-availability iCheckOutX / Internet Payment Gateway (IPGW) solution is described in the following image. The functionalities provided by the system are divided into categories:

iCheckOutX front-end

Request from web shops (V-POS) are processed by the frontend - iCheckOutX system. iCheckOutX system validates all incoming requests, verifies the received web shop information, checks if merchant is active and allowed to perform the specific transaction type. If request validation is successful, iCheckOutX continues with 3D secure validation. The 3D secure validation is done utilizing the 3D Server that communicates with Directory server of the networks.

If required, iCheckOutX will initiate additional security validations as defined in 3D Secure standard. If cardholder authentication is required, iCheckOutX will redirect the cardholder to issuer API to enter the required information. After these steps are done, the transaction is authorized through the IPGW system.

Internet Payment Gateway - IPGW

Internet payment gateway solution is based on ZMS PowerZaC Application server that is configured to support card-not-present transaction types. The IPGW solution supports different transactions types: purchase, preauthorization and completion, refund, void, proprietary payment schemes based on QR code or other mobile technology.

IPGW can be used to securely store cardholder data that can be used for initiating recurring transactions or enabling cardholders to initiate payment without (re)entering card information (One-click payment).

Sensitive cardholder data on IPGW are stored encrypted with key protected inside Hardware Security Module (HSM) device. IPGW supports IBM CCA 4767 and Tales 9000 and 10K HSM devices.

iCheckOutX System Arhitecture

Integration procedure

Prerequisites

Before merchant can start its integration with iCheckoutX system the following prerequisites must be met.

  1. Merchant must be registered on iCheckoutX. This can be done through iCheckoutX Admin GUI interface. All relevant merchant data must be defined for the merchants: MID, TID, Name and location, Acquirer links, Accepted card types, installment support.
  2. Secret key must be exchanged between iCheckoutX and Merchant. It can be defined under merchant settings in the iCheckoutX Admin GUI interface. This key is used to sign all requests between merchant and iCheckoutX system.
  3. [optional] Merchant defines their own custom design of the Payment page by uploading CSS file. If custom CSS file is not uploaded default design of the payment page will be used.

iCheckoutX Message Flow

Transaction flow

The iCheckOutX transaction flow begins with merchant web shop sending the initial purchase request described in integration chapter. After validating the request, iCheckOutX will display the landing page for Cardholder data input. The design of the landing page can be customized for each merchant by defining merchants CSS. If no Merchant CSS is provided then default landing page will be displayed. On the cardholder landing page Cardholder can enter the Card data (PAN, CVV, expiry date) and basic Cardholder information (Name, Surname, Address…)
If merchant has additional payment options enabled, such as payment by QR code, they will also be offered of the landing page.

Payment Landing page

After the cardholder data is entered, iCheckOutX will automatically perform 3D Secure validation for the card. If no 3D Secure validation is needed for cards (card is not enrolled in 3DS or is marked as frictionless) iCheckOutX will continue to Authorization.

If Cardholder Authentication is required iCheckOutX will display Issuers page and wait for customer to continue the authentication process.

3D Authentication on iCheckOutX

After the 3D Secure process is done the transaction is authorized through IPGW system with appropriate acquirer. This process is transparent to the Merchant web shop.

In the final step the iCheckOutX redirects customer back to the original Web shop URL with the transaction result. If the transaction is successful (is Approved) authorization code and other data is returned to the merchants Web shop. Response message details are defined here.

E-commerce Transaction Flow

3-D Secure Authentication request processing – Acquirer side

If the merchant participates in 3-D Secure program, typical shopping process for “not-on-us” cards will be extended with additional steps, with purpose of customer authentication. Authentication will be processed on customer´s issuer ACS (Picture 4).

1 - Customer selects one or more products or services and creates order,

2 - a) When request is received, iCheckOutX service checks merchant enrollment in 3-D Secure program and if needed sends a query to the Central Directory of the corresponding card network. * 3-D Secure Client executes query on the Central Directory * Central Directory checks enrollment of issuer in 3-D Secure program and if needed executes query to the Issuer ACS * Issuer ACS checks card participation in 3-D Secure program and returns data about participation and URL for customer authentication.

2 - b) If card participates in 3-D Secure program, customer Internet Browser is redirected to the authentication URL (on the picture redirection is logically presented with dashed line).

3 - iCheckOut service formats Authorization request and proceeds it to the iPayGate system that forwards transaction to acquirer authorization system

4 - If the card is issued by acquiring bank authorization is supplied from local authorization host

5 - If the card is not issued by acquiring bank, authorization host forwards authorization request to the network.

3D Secure flow - Acquirer side

3-D Secure Authentication request Processing – Issuer side

When processing 3-D Secure request on the issuer side processing is different from previously described models includes next steps (picture 5):

1 - 3-D Secure Authentication request comes from the “Central Directory” server to issuer ACS (Access Control Server) which checks if the card participates in 3-D Secure program. ACS returns response with card status and URL for customer authentication.

2 - If customer participates in 3-D Secure program, acquirer’s system will redirect customer’s Internet browser to the URL received in previous step. ACS form for authentication data input is presented on received URL.

3 - ACS checks validity of inserted data and returns XID and CAVV/AAV values in the authentication response.

4 - Authorization host accepts authorization request from the network extended by XID and CAVV/AAV values.

3D Secure flow - Issuer side

Authorization response processing

Processing continues with authorization response.

6 - Network provides authorization response in case when authorization has been sent to the network. If request was not sent to the network response comes from local authorization host.

7 - Response is forwarded to the iPayGate where appropriate business logic will be applied.

8 - Appropriate formatted response is forwarded to the iCheckOut service.

9 - iCheckOut service returns (https) response to the Internet shop system (web-shop).

10 - Web shop will notify customer about authorization result (payment status).

Processing authorization Response

Integration with iCheckOutX system

This chapter describes all integration details. It defines message types and data elements for all iCheckOutX messages.

To simplify the integration process, a predefined HTML template is provided that can be used to test the iCheckOutX integration. The scripts assumes the role of a Web shop and can be used to initiate different transaction requests towards iCheckOutX.

Integration script can be downloaded from this link.

iCheckOutX service integration with Internet shop system is done through HTML POST method. POST data sent in form must be UTF-8 encoded. Example:

<form enctype="application/x-www-form-urlencoded;charset=UTF-8">

iCheckOutX Messages

This section defines the messages defined for iCheckOutX system. Message exchange between merchant shop and iCheckOutX service is done using HTTP protocol. Web shop prepares HTML form which is sent usign HTTP POST to iCheckOutX endpoint. An HTTP POST request should be sent to URL:

https://host-domain/iCheckOutX/v1/icheckout/confirm.xhtml
Notice: “host-domain” should be replaced with the exact system domain.

iCheckOutX Request Parameters

Parameter Name Parameter Description Value Format Value Length
account_id One-Click Payments Account ID AN 36
additional_compl_data1 Additional Completion Data AN 36
card_cvd Payment Card CVV N 4
card_expdate Payment Card Expiration Date N 4
card_pan Payment Card Number N 20
card_type (deprecated)
customer_address Customer Street AN 200
customer_city Customer City AN 50
customer_country Customer Country AN 30
customer_email Customer Email AN 30
customer_lang Customer Language AN 2
customer_name Customer First Name AN 50
customer_phone Customer Phone AN 30
customer_surname Customer Last Name AN 50
customer_zip Customer ZIP AN 8
discounted_amount Discounted Amount AN 13
discounted_card_types Card Types to which the discount is applied AN 200
discounted_max_installments Maximum number of installments to which the discount is applied N 2
fixed_card_type Fixed (unchangeable) card type AN 10
fixed_installments Fixed (unchangeable) number of installments AN 5
merchant_approve_url Merchant Dynamic Approve URL AN 128
merchant_decline_url Merchant Dynamic Decline URL AN 128
merchant_id Merchant ID AN 16
order_delivery_date Order Delivery Date AN 11
order_number Unique Order Number AN 50
payment_method Payment method that will be used. If not present, all methods will be allowed. AN 16
purchase_amount Purchase Amount AN 13
purchase_currency Purchase Currency N 3
purchase_description Purchase Description AN 200
purchase_differperiod (deprecated)
purchase_installments Purchase Installments N 2
recurring_order_number Original Order Number for Recurring Payments AN 50
request_hash Request Hash AN 128
request_type Request Type AN 15
submit_type (deprecated)
terminal_id Terminal ID AN 32
transaction_id (deprecated)
trantype Transaction Type AN 20

Definition of Request Parameters Presence

Presence is defined as:
- M, mandatory
- O, optional
- C, conditional (i.e. account_id must be present fore One-Click transactions)
- “-”, not relevant

If other value is listed (such as “auth”), parameter is mandatory and has to contain that exact value.

Parameter Name Preauthorization Authorization Completion Reversal Refund
account_id C C - - -
additional_compl_data1 - - O - -
card_cvd O O - - -
card_expdate O O - - -
card_pan O O - - -
customer_address O O - - -
customer_city O O - - -
customer_country O O - - -
customer_email O O - - -
customer_lang O O - - -
customer_name O O - - -
customer_phone O O - - -
customer_surname O O - - -
customer_zip O O - - -
discounted_amount O O - - -
discounted_card_types O O - - -
discounted_max_installments O O - - -
fixed_card_type O O - - -
fixed_installments O O - - -
merchant_approve_url O O O O O
merchant_decline_url O O O O O
merchant_id M M M M M
order_delivery_date O O - - -
order_number M M M M M
payment_method O O - - -
purchase_amount M M M M M
purchase_currency M M M M M
purchase_description O O - - -
purchase_installments O O - - -
recurring_order_number C C - - -
request_hash M M M M M
request_type transaction transaction completion reversal refund
terminal_id M M M M M
trantype preauth auth completion reversal refund

Details on parameter presence for One-Click Payments are listed in One-Click Payments chapter.

iCheckOutX Response Parameters

Parameter Name Parameter Description Value Format Value Length
account_id One-Click Payments Account ID AN 36
acquirer Order Acquirer AN 16
card_expdate Payment Card Expiration Date N 4
card_type Payment Card Type AN 64
customer_address Customer Street AN 200
customer_city Customer City AN 50
customer_country Customer Country AN 30
customer_email Customer Email AN 30
customer_lang Customer Language AN 2
customer_name Customer First Name AN 50
customer_surname Customer Last Name AN 50
customer_tel Customer Phone AN 30
customer_zip Customer ZIP AN 8
discounted_amount Discounted Amount AN 13
masked_pan Masked Payment Card Number AN 20
merchant_id Merchant ID AN 16
order_date Order Date AN 11
order_delivery_date Order Delivery Date AN 11
order_number Unique Order Number AN 50
payment_method Payment method that was used for the transaction AN 16
purchase_amount Purchase Amount AN 13
purchase_currency Purchase Currency N 3
purchase_description Purchase Description AN 200
purchase_installments Purchase Installments N 2
request_type Request Type AN 15
response_appcode Authorization Approval Code AN 6
response_hash Response Hash AN 128
response_message Authorization Response Message AN 200
response_random_number (deprecated)
response_result Response Result N 3
response_systan Transaction System Trace Audit Number AN 6
transaction_type Transaction Type AN 20

Additional Response Parameters For Cryptocurrency Payments

When payment is made using cryptocurrencies, indicated by response parameter payment_method=“crypto”, the following parameters will also be sent in final response to merchant:

Parameter Name Parameter Description Value Format
coin_amount coin amount in decimal value AN
coin_currency cryptocurrency used for payment AN
coin_payment_code unique coin payment identifier AN
coin_tx_fee_amount coin transaction fee amount AN
coin_exchange_rate_src_dst coin exchange rate: (coin_amount-coin_tx_fee_amount)/purchase_amount AN
coin_exchange_rate_dst_src coin exchange rate: purchase_amount/(coin_amount-coin_tx_fee_amount) AN

Examples

purchase_amount=100
purchase_currency=978
coin_amount=0.0018243847262
coin_currency=BTC
coin_payment_code=9FZaWF_0XOwzaQ_t5gwNRFW0e9QgyQo_Sj4LGrI0dGTF
coin_tx_fee_amount=0.00001
coin_exchange_rate_src_dst=0.00001814384726

purchase_amount=100
purchase_currency=978
coin_amount=2923121.89
coin_currency=SHIB
coin_payment_code=8AZaWF_0YOqzbQ_c5hwMRFY0f9QhyQo_Si5LHrI0dHTG
coin_tx_fee_amount=7543.86
coin_exchange_rate_src_dst=29155.78

Parameter details

request_type - Type of request

Type: alphanumeric Mandatory: Yes

request_type field defines the type of request sent to iCheckOutX system. The type can one of the following values:

Request type Description
transaction Indicates a request for financial transaction. Check trantype field for additional details.
register Oneclick register account request
update Oneclick update account request
get Oneclick get account request
use Oneclick use account request
delete Oneclick delete account request
recurring Indicates a request for an automated financial transaction
checkstatus Used for checking the status of an order previously processed by the system
checkstatusfull (deprecated)

trantype - Transaction Type

Type: alphanumeric Mandatory: Yes

trantype field defines the type of type of Financial transaction request sent to iCheckOutX system.

Valid values Description
auth Purchase request. Transaction is done in one step, no completion is required
preauth Preauthorization request
completion Completion of previous Preauthorization request. Preauth must be Approved.
reversal Cancels/Voids of Preauthorization. Reversal for other transaction types is not supported
refund Refund of previously done Purchase or Completion transactions. Max amount limited to the amount of original Purchase or Completion.

submit_type - iCheckOut Submit Mode

Type: alphanumeric

submit_type has been deprecated and should not be included in any request.

merch_id - Merchant ID

Type: alphanumeric Mandatory: Yes

merch_id field indicates the merchant ID (MID) that was initially defined at merchant registration with iCheckOutX.

It should be paired with terminal_id field to uniquely identify the merchant and terminal from which the transaction request originates.

terminal_id - Terminal ID

Type: alphanumeric Mandatory: Yes

terminal_id field indicates the terminal ID (TID) that was initially defined at merchant registration with iCheckOutX.

It should be paired with merch_id field to uniquely identify the merchant and terminal from which the transaction request originates.

order_number - Order Number

Type: alphanumeric Mandatory: Yes

order_number field indicates the unique order identificator.

Merchant should make sure the order_number value is unique for the originating terminal_id.

merchant_approve_url / merchant_decline_url - Merchant Dynamic Callback URLs for Approved and Declined Transactions

Type: alphanumeric Mandatory: No

merchant_approve_url and merchant_decline_url parameters can be used in a transaction request to define on which URL the webshop expects the final response.

These URLs are commonly set permanently under merchant settings in iCheckOutX Admin GUI and do not have to be sent with each request.

Using merchant_approve_url and merchant_decline_url in a transaction request overrides the default merchant settings for that transaction.

Examples:

merchant_approve_url=https://host-domain.com/iCheckOutX/v1/testMerchant/approved
merchant_decline_url=https://host-domain.com/iCheckOutX/v1/testMerchant/declined

purchase_installments - Purchase Installments

Type: numeric Mandatory: No

A field used to split order payment into installments.

Can be either 0 or >= 2, while the maximum value is defined by merchant transaction rules. Merchant can also enforce different installment rules depending on the purchase amount.

Value of 0 indicates a one-time payment.

In a merchant response, this field represents the final number of installments chosen by the customer.

recurring_order_number - Recurring Order Number

Type: alphanumeric Mandatory: Yes (only in cases of subsequent ‘recurring’ requests)

A field used for recurring payments, recurring_order_number indicates the original order to which the new order is reffered.

payment_method - Payment Method

Type: alphanumeric Mandatory: No

When payment_method is sent as a request parameter, it defines a single payment method that is allowed by merchant and will be used for that particular payment. No other method will be allowed.

If the parameter is not present in the iCheckOutX request, all methods will be allowed and the customer will be able to choose a method of their choice.

When received as a response parameter, payment_method will indicate a method that was used for the payment.

Possible values are:

card (Credit Card Payment)
instant_payment (Instant Payment)
keks (KeksPay Payment)
crypto (Cryptocurrency Payment)
cash (Cash on Delivery)

request_hash - Request security hash

Type: alphanumeric Mandatory: Yes

In order to accept only the transaction requests that originate from registered merchants, iCheckOutX will perform validation of request_hash value. Merchants should calculate this value for each request and include it in the request payload.

Request hash is calculated using the SHA512 algorithm and the string that is used for SHA512 encryption is constructed as follows:

  1. Convert all parameter names to lowercase. Example: “Customer_Name=John” is translated to lowercase “customer_name=John” The value (in this example John) is not converted.
  2. Sort all parameters alphabetically.
  3. In hash calculation input only include the parameters with non empty values.
  4. Concatenate all parameters separated with “&”. Example: account_id=123&customer_address=Customer Address&customer_city=New York…
  5. Add secret_key=XXXXXX as the last parameter in hash input. (replace XXXXX with unique secret key assigned to merchants.
  6. Calculate SHA512 hash for constructed input. Input to SHA512 function must be encoded as UTF-8
  7. Use the calculated hash as request_hash parameter in request

Possible parameters used for request_hash calculation are:

account_id
additional_compl_data1
card_cvd
card_expdate
card_pan
customer_address
customer_city
customer_country
customer_email
customer_lang
customer_name
customer_phone
customer_surname
customer_zip
discounted_amount
discounted_card_types
discounted_max_installments
fixed_card_type
fixed_installments
merchant_approve_url
merchant_decline_url
merchant_id
order_delivery_date
order_number
payment_method
purchase_amount
purchase_currency
purchase_description
purchase_installments
request_hash
request_type
terminal_id
trantype

The delimiter that is used to separate the parameters is ‘&’.

Example of hash calculation:

Input parameters:

merchant_id=5656565656
purchase_amount=1.00
purchase_currency=191
order_number=1ORD_120208_19
request_type=transaction
trantype=auth
submit_type=manual
purchase_installments=0
purchase_description=Test transaction
customer_name=John
customer_surname=Smith
customer_address=498 Gainsway Lane
customer_country=United States
customer_city=New York
customer_zip=10040
account_id=

Sorted and filtered list (removed empty account_id). Added secret_key=SecretKey123 at the end.

customer_­dress=I8 Gainsway Lane
customer_city=New York
customer_country=United States
customer_name=John
customer_surname=Smith
customer_zip=10040
merchant_id=5656565656
order_number=1ORD_120208_19
purchase_amount=1.00
purchase_currency=191
purchase_description=Test transaction
purchase_installments=0
request_type=transaction
submit_type=manual
trantype=auth
secret_key=SecretKey123

calculate SHA

SHA512(customer_address=498 Gainsway Lane&customer_city=New York&customer_country=United States&customer_name=John&customer_surname=Smith&customer_zip=10040&merchant_id=5656565656&order_number=1ORD_120208_19&purchase_amount=1.00&purchase_currency=191&purchase_description=Test transaction&purchase_installments=0&request_type=transaction&submit_type=manual&trantype=auth&secret_key=SecretKey123)
=
a87a67e635e726e591e01cab3e11b4c3ba4522fa4e4cad05124085df9ce7169bd59c4ee12759bd1d7a7d206cb7eb58b2784690647f0d5b0c30a00019eb7107ec

Request to iCheckOutX must have:

request_hash=a87a67e635e726e591e01cab3e11b4c3ba4522fa4e4cad05124085df9ce7169bd59c4ee12759bd1d7a7d206cb7eb58b2784690647f0d5b0c30a00019eb7107ec

NOTICE: A deprecated request_hash calculation method is using the SHA1 algorithm and fewer request parameters. Merchants that have merchant attribute HASH_TYPE < 4 use this method of hash calculation. This is used for backward compatibility.

response_hash - Response security hash

Type: alphanumeric Mandatory: Yes

After the transaction is processed, merchants will receive a final response containing the transaction result and other details, including response_hash.

To make sure that the transaction response originates from iCheckOutX, merchants should calculate a response_hash value and compare it to the one received within the response. If correct method was used for calculation and a mismatch between the comparing values is detected, response should not be considered valid. Additionally, merchants can use checkstatus requests to inquire about current transaction status.

Response hash is calculated using the SHA512 algorithm and the string that is used for SHA512 encryption is constructed as follows:

  1. Convert all received parameter names to lowercase. Example: “Customer_Name=John” is translated to lowercase “customer_name=John” The value (in this example John) is not converted.
  2. Omit response_hash parameter from hash calculation.
  3. Sort all parameters alphabetically.
  4. In hash calculation input only include the parameters with non-empty values.
  5. Concatenate all parameters separated with “&”. Example: acquirer=123&customer_email=example@mail.com&customer_lang=hr…
  6. Add secret_key=XXXXXX as the last parameter in hash input. (replace XXXXX with unique secret key assigned to merchants.
  7. Calculate SHA512 hash for constructed input. Input to SHA512 function must be encoded as UTF-8
  8. Check if calculated hash matches the response_hash parameter value in response

Possible parameters used for response_hash calculation are:

account_id
acquirer
card_expdate
card_type
customer_address
customer_city
customer_country
customer_email
customer_lang
customer_name
customer_surname
customer_tel
customer_zip
discount_amount
masked_pan
merchant_id
oneclick_result
order_date
order_number
payment_method
purchase_amount
purchase_currency
purchase_description
purchase_installments
request_type
response_appcode
response_hash
response_message
response_result
response_systan
transaction_id
transaction_type

The delimiter that is used to separate the parameters is ‘&’.

Example of hash calculation:

Merchant received parameters:

acquirer=123
card_type=Visa
customer_address=Test Address
customer_city=Test City1
customer_country=Hrvatska
customer_email=test@email.com
customer_lang=hr
customer_name=TestName
customer_surname=TestSurname
customer_tel=+38512345678
customer_zip=10000
order_date=2021-09-14 11:54:10.004
order_number=1ORD_121149_1567
payment_method=
purchase_amount=15.00
purchase_currency=191
purchase_description=Test order
purchase_installments=0
request_type=transaction
response_appcode=781722
response_hash=7c434756a1fc689f651334ed88603c9c8664b384bacdab82265e2f0cc9827309b184eb200cc03155977c0590a655b90f0b3594cf9edcbfc19c500f05dd1fe06f
response_message=ODOBRENO
response_result=00
response_systan=002977
transaction_id=
transaction_type=auth
account_id=
oneclick_result=

Sorted and filtered list (removed empty account_id). Added secret_key parameter at the end.

acquirer=123
card_type=Visa
customer_address=Test Address
customer_city=Test City1
customer_country=Hrvatska
customer_email=test@email.com
customer_lang=hr
customer_name=TestName
customer_surname=TestSurname
customer_tel=+38512345678
customer_zip=10000
discount_amount=0.00
order_date=2021-09-14 11:54:10.004
order_number=1ORD_121149_1567
purchase_amount=15.00
purchase_currency=191
purchase_description=Test order
purchase_installments=0
request_type=transaction
response_appcode=781722
response_message=ODOBRENO
response_result=00
response_systan=002977
transaction_type=auth
secret_key=XXX

calculate SHA

SHA512(acquirer=123&card_type=Visa&customer_address=Test Address&customer_city=Test City1&customer_country=Hrvatska&customer_email=test@email.com&customer_lang=hr&customer_name=TestName&customer_surname=TestSurname&customer_tel=+38512345678&customer_zip=10000&discount_amount=0.00&order_date=2021-09-14 11:54:10.004&order_number=1ORD_121149_1567&purchase_amount=15.00&purchase_currency=191&purchase_description=Test order&purchase_installments=0&request_type=transaction&response_appcode=781722&response_message=ODOBRENO&response_result=00&response_systan=002977&transaction_type=auth&secret_key=???)
=
7c434756a1fc689f651334ed88603c9c8664b384bacdab82265e2f0cc9827309b184eb200cc03155977c0590a655b90f0b3594cf9edcbfc19c500f05dd1fe06f

Response hash value from iCheckOutX must be:

response_hash=7c434756a1fc689f651334ed88603c9c8664b384bacdab82265e2f0cc9827309b184eb200cc03155977c0590a655b90f0b3594cf9edcbfc19c500f05dd1fe06f

response_result - Response Result

Type: alphanumeric

Field contains response code received from the authorization host. Required only in responses. Response code is the only value that determines whether the request is approved or declined.

Response code Response code description
000 Approved/Accepted
100 Declined
101 Expired Card
104 Restricted Card
109 Invalid merchant
111 Card not on file
115 Requested function not supported
121 Insufficient funds
400 Reversal accepted
909 Technical error – unable to process request *
912 Host link down ** / Server not available **
930 Transaction not found ***
931 Transaction voided/reversed ***

* this response code shouldn’t be treated as declined when presenting information to end user. This response means it is unable to process the request at this moment and the customer should try later.
** this response code means the system can’t process customer requests at that moment. Shouldn´t be treated as declined only when presenting information to end user.
*** can be returned only for authorization/completion status requests; reserved for future use

response_message - Response Message

Type: alphanumeric Mandatory: Yes

response_message field contains details about order status on the payment system.

For cryptocurrency payment method, this field can contain one of the following values:

Response message Description
CRYPTO_PAYMENT_CREATED Payment has been created
CRYPTO_PAYMENT_WAITING_TRANSACTION Waiting for the amount to appear on blockchain
CRYPTO_PAYMENT_WAITING_CONFIRMATIONS Waiting for the right amount of confirmations
CRYPTO_PAYMENT_UNDERPAID An insufficient amount detected on blockchain. Client will be contacted by PayCek support and he will either make additional payment to the full amount or get the refund in which case the payment will be canceled
CRYPTO_PAYMENT_SUCCESSFUL Right amount detected and confirmed on blockchain
CRYPTO_PAYMENT_EXPIRED Time for this payment has run out
CRYPTO_PAYMENT_CANCELED The payment has been manually canceled by paycek operations
CRYPTO_PAYMENT_COMPLETED The payment has been manually canceled by paycek operations

Merchant notification (server-to-server)

Aside from the final response that merchants receive on customer redirect to webshop, there is an additional possibillity to receive that same response on a dedicated merchant’s endpoint as soon as the transaction has been approved or declined. This can be useful to reduce the potential uncertainty of the transaction status in cases when customers close their web-browser session before redirecting, or lose internet connection etc.

Parameters (as well as response hash) in s2s notification will have the same values as the customer redirect a few moments later.

Parameters will be sent via HTTP POST request in a JSON format.

To verify the notification has been received successfully by the merchant, iCheckOutX should receive HTTP 200 with JSON parameter status=OK. In all other cases, iCheckOutX will try to send the same notification until reaching out maximum number of tries or receiving status=OK.

Merchant notification setting can be triggered using the iCheckOutAdminX interface, which is also where the endpoint URL will be set.

If a webshop does not have a designated s2s response endpoint, it can implement a similar status checking method using checkstatus requests.

Integration Examples

Purchase Request

Payment initiation request: trantype=auth

merchant_id=SAMPLEMID
purchase_amount=15.00
purchase_currency=191
order_number=1ORD_1211310_4926
request_type=transaction
trantype=auth
purchase_description=Test+order
customer_name=TestName
customer_surname=TestSurname
customer_address=Test+Address
customer_country=Hrvatska
customer_city=Test+City1
customer_zip=10000
customer_lang=hr
customer_email=test@email.com
customer_phone=+38512345678
terminal_id=SAMPLETID
request_hash=01322f2d817a9a3f8bd244f9a77221c3307ac19ae1f1aa72180fd22834f96f0122a07361e9befff272920f1276506a51fac51a7e8c0ee62262ba9c8afb91b823

Merchant receives response parameters:

account_id=
acquirer=***
card_type=Visa
card_expdate=2404
customer_address=Test Address
customer_city=Test City1
customer_country=Hrvatska
customer_email=test@email.com
customer_lang=hr
customer_name=TestName
customer_surname=TestSurname
customer_tel=+38512345678
customer_zip=10000
masked_pan=400000******0000
merchant_id=SAMPLEMID
oneclick_result=
order_date=2021-10-13 15:38:13.752
order_number=1ORD_1211310_4926
payment_method=
purchase_amount=15.00
purchase_currency=191
purchase_description=Test order
purchase_installments=
request_type=transaction
response_appcode=153819
response_hash=7e5ff52cf33912d78f635b1e4be1969369992e9bb6195025a9a5197465d27aeeafc4af6fb07f7c124154bee31af1eacf19cead10efdfaceb61b299cc7d7b329d
response_message=ODOBRENO
response_result=000
response_systan=003167
transaction_type=auth

Preauthorization Request

Payment initiation request: trantype=preauth

merchant_id=SAMPLETID
purchase_amount=2.40
purchase_currency=191
order_number=1ORD_1211310_3939
request_type=transaction
trantype=preauth
purchase_description=Test+order
customer_name=TestName
customer_surname=TestSurname
customer_address=Test+Address
customer_country=Hrvatska
customer_city=Test+City1
customer_zip=10000
customer_lang=hr
customer_email=test@email.com
customer_phone=+38512345678
terminal_id=SAMPLETID
request_hash=3eebb82fdfae91ab864e5a07b2bd7886ee1a4e844a76f1021629af1a36538f8e1c220424dcb540939ca36e4e94d39110d234122b32286121507e215cc7d02fd2

Merchant receives response parameters:

account_id=
acquirer=***
card_type=Visa
card_expdate=2509
customer_address=Test Address
customer_city=Test City1
customer_country=Hrvatska
customer_email=test@email.com
customer_lang=hr
customer_name=TestName
customer_surname=TestSurname
customer_tel=+38512345678
customer_zip=10000
masked_pan=400000******0000
merchant_id=SAMPLEMID
oneclick_result=
order_date=2021-10-13 15:42:10.841
order_number=1ORD_1211310_3939
payment_method=
purchase_amount=2.40
purchase_currency=191
purchase_description=Test order
purchase_installments=
request_type=transaction
response_appcode=154216
response_hash=1be6687e1545098d05b81cd35a9f6e61acf9a3e39585ebe5099deef3244f7e9e58e0aba829dbf54336bc3843de6869f2562e6e8543a208de97b3c4490be605f8
response_message=ODOBRENO
response_result=000
response_systan=003168
transaction_type=preauth

Completion of the Preauthorized Request

Completion request must refer to the original (preauthorized) transaction using the order_number value:

merchant_id=SAMPLEMID
purchase_amount=2.40
purchase_currency=191
order_number=1ORD_1211310_3939
request_type=transaction
trantype=completion
purchase_description=Test+order
customer_lang=hr
terminal_id=SAMPLETID
request_hash=1660fab796d5082db795b94756e9cdd449b6495324b9213b19d8b2fde08db78306814fad2adfc7723e8e54ad60bdb74a8443156dd963bea3287c1251d001d463

If a completion request is sent through the webshop, merchant receives response parameters:

account_id=
acquirer=***
card_type=
card_expdate=
customer_address=
customer_city=
customer_country=
customer_email=
customer_lang=hr
customer_name=
customer_surname=
customer_tel=
customer_zip=
masked_pan=
merchant_id=SAMPLEMID
oneclick_result=
order_date=
order_number=1ORD_1211310_3939
payment_method=
purchase_amount=2.40
purchase_currency=191
purchase_description=Test order
purchase_installments=
request_type=transaction
response_appcode=154830
response_hash=c68b3a242449c89f1bb8de9e116cda74f4c47985ccae09998e1efb4d2dba00446d74edd0a50225c26e1ff5adc18baff7774ac751d9dfe2e061b30f8cfa1ac88a
response_message=ODOBRENO
response_result=000
response_systan=003168
transaction_type=completion

Refund Request

Refund request must also refer to the original transaction using the order_number value: request_type=refund

merchant_id=SAMPLEMID
purchase_amount=15.00
purchase_currency=191
order_number=1ORD_1211310_4926
request_type=transaction
trantype=refund
purchase_description=Test+order
customer_name=TestName
customer_surname=TestSurname
customer_address=Test+Address
customer_country=Hrvatska
customer_city=Test+City1
customer_zip=10000
customer_lang=hr
customer_email=test@email.com
customer_phone=+38512345678
terminal_id=SAMPLETID
request_hash=2c3414c7426a446f90b15f1bbc94bc5de2302175edcbb2610bc20cd54b1a08a15e447af03af2650363a857ecdf8dd393a7f5f10c8025306867ee8f2f19e0c75b
account_id=
acquirer=***
card_type=
card_expdate=
customer_address=Test Address
customer_city=Test City1
customer_country=Hrvatska
customer_email=test@email.com
customer_lang=hr
customer_name=TestName
customer_surname=TestSurname
customer_tel=+38512345678
customer_zip=10000
masked_pan=
merchant_id=SAMPLEMID
oneclick_result=
order_date=
order_number=1ORD_1211310_4926
payment_method=
purchase_amount=15.00
purchase_currency=191
purchase_description=Test order
purchase_installments=
request_type=transaction
response_appcode=155435
response_hash=ff288cdd3659fe97fb36ef3339a6d7a405d57f9e6f2a16b40186742074cbdaaf9fa9ef3653d8b27562dae651d8354816a72eae8b9d3d12b56b0e80e102905fca
response_message=ODOBRENO
response_result=000
response_systan=003167
transaction_type=refund

Instead of initiating payments through the webshop, merchant can also prepare an order on customer demand and provide a payment link that is sent to customer via e-mail. When the customer follows the link, a checkout form will be presented to them with pre-filled order ID, purchase amount and other order details.

To generate payment link for the customer, merchant has to prepare HTTP GET request which will send the payment initiation parameters to iCheckOutX. The link can be presented to customer in text format, as a button, linked image or any other HTML implementation by merchant’s choice.

Parameters appended to the payment link’s query are the same request parameters that are used for regular transaction initiation. However, in case of Payment by Link, HTTP GET method should be used instead of HTTP POST.

It is important to never include the merchant’s secret_key value in the URL, as it is a security parameter that should not be accessible to customer. It is only used for hash calculation, again using the same procedure as in the standard payment requests.

After clicking the link in the e-mail, customer only has to fill out their card data and personal data that is required for continuing the payment.

Example of a fully formed payment link:

https://host-domain/iCheckOutX/v1/icheckout/confirm.xhtml?merchant_id=SAMPLEMID&purchase_amount=15.00&purchase_currency=191&order_number=1ORD_122082_4631&request_type=transaction&trantype=auth&purchase_description=Test+order&customer_country=Hrvatska&customer_lang=hr&terminal_id=DEMOTID&request_hash=2d83f681da0e2afdef5967d5f7e6a1586fed0fb40a0ea98474476dd795e3ba021096b49c3511a20d57de684f59fbecfb8a173a635dfe354a6b566b2f54f901b0

Notice: “host-domain” should be replaced with the exact system domain.

Other payment methods

Along with regular card payment, iCheckOutX supports some other payment methods.

These are:

Paycek payment

Customers who want to pay with crypto currencies, can do so via Electrocoin’s Paycek secure payment portal. Merchants must have this payment option enabled in iCheckOut admin interface for their customers to be able to use it in production. During the payment process, customer needs to select the cryptocurrency that he wishes to use for payment and enter a valid crypto wallet address that will be used.

Paycek payment

KeksPay payment

Another payment option is via KeksPay mobile application. Merchants must have this payment option enabled in iCheckOut admin interface for their customers to be able to use it in production. iCheckOut system generates a unique QR code for every order that a customer need to scan with their KeksPay mobile application, if they want to pay with this method. When payment is successfully processed by KeksPay, iCheckOut system gets notified, and the order is finalized.

KeksPay payment

GooglePay™ payment

If a customer chooses GooglePay as a payment method, a button will appear on payment form that can be used to finalize the transaction via GooglePay.

GooglePay payment

When a customer selects the GooglePay option as a payment method, the customer will need to select the desired card registered in his Google account. Our system supports all major credit and debit cards such as: Amex, Visa, Maestro, MasterCard, Diners and Discover cards. The selected card may require further customer authentication via 3DS authentication request processing, described in our 3-D Secure Authentication request Processing chapter

To be able to process 3DS authentication for customers, merchant must have the 3DS authentication option enabled in the iCheckOut admin interface.

For customers to be able to select GooglePay as a payment method, merchants must be approved to use this payment method. Each merchant will be granted a unique gatewayMerchantID that will be used for payments, which can be obtained by registering their business with Google.

Registering:

All merchants that use GooglePay as a payment method must register their business with Google to receive their unique gatewayMerchantID parameter, which will be used for GooglePay transactions.

Register link is provided as follows:

 https://pay.google.com/business/console

After successful registration, the gatewayMerchantID parameter must be assigned in the in iCheckOut admin interface before merchant can use GooglePay.

In addition to the gatewayMerchantID, all merchants using the iCheckOut hosted payment page must use a unique gateway parameter which will be set for all merchants as gateway:mstartipg value, and there will be no option to modify this value in the iCheckOut admin interface.

  IMPORTANT NOTICE: All merchants that use GooglePay as a payment method must have the following customer data fields enabled in iCheckOut admin interface and set as mandatory, for billing address verification purposes:

If a merchant does not want to use the iCheckOut hosted payment page, there are a couple of methods for integrating GooglePay into the webshop:

Web integration:

The following links should help to integrate GooglePay option into merchants webshop:

Android integration:

The following links should help to integrate GooglePay option into merchants Android application shop :

Terms and conditions:

All merchants that use GooglePay as a payment method must read and accept Google terms and conditions:

  https://payments.developers.google.com/terms/aup

  https://payments.developers.google.com/terms/sellertos

Checking Order Status

To check order status at any moment, an HTTP POST request should be made to URL:

https://host-domain/iCheckOutX/v1/icheckout/confirm.xhtml
Notice: “host-domain” should be replaced with the exact system domain.

If an order with specified order_number exists for the specified merchant, response from iCheckOut will contain the corresponding authorization or preauthorization response_result. Transaction is considered approved only if its response_result is equal to “000”. Response will also contain other details for queried order such as response_message, order_date, systan and approval_code.

Parameter order_lifecycle can obtain the following values:

Case: a) Order is not found

order_lifecycle = “Order not found”

Case: b) Order is pending

order_lifecycle = “Received” OR order_lifecycle = “Sent”

Case: c) Order is declined

order_lifecycle = “Declined” OR order_lifecycle = “Canceled” OR order_lifecycle = “Session expired”

Case: d) Order is approved

order_lifecycle = “Authorized” OR order_lifecycle = “Completed” OR order_lifecycle = “Refunded” OR order_lifecycle = “Reversed”

Response Hash should be calculated the same way as in standard e-commerce transactions. In the following example, these parameters were included in response hash calculation: card_type=PBZ Visa
order_date=2021-09-29 12:32:38.889711
order_number=1ORD_121299_3108
response_appcode=874161
response_message=ODOBRENO
response_result=000
response_systan=003055
secret_key=XXXXX

checkstatus request example

merchant_id=SAMPLEMID
order_number=1ORD_121299_3108
request_type=checkstatus
terminal_id=SAMPLETID
request_hash=33aba71b36782c729d89c63d3651799eac1496485b4b03d169b97e6e1becb14b46a5e894b7a5c8ea5b981a3a112956feccc78c1c3d353134c5c12dc99dfdadc6

checkstatus response example

<response>
    <card_type>PBZ Visa</card_type>
    <order_date>2021-09-29 12:32:38.889711</order_date>
    <order_number>1ORD_121299_3108</order_number>
    <response_appcode>874161 </response_appcode>
    <response_hash> c65ee526cf852a47f7b6ec64fafa78969fdcbde96a706acb41f1e90b694edcf1ac91bbb995b956bd122a7a01cb0cc56293c914979756973e9d6004768d752039
    </response_hash>
    <response_message>ODOBRENO</response_message>
    <response_result>000</response_result>
    <response_systan>003055</response_systan>
</response>

One-Click Payment

iCheckOut system supports one-click payment type orders and transactions. This functionality is typically used when cardholder wants to save his card data and use it in subsequent orders on the webshop. This is useful as cardholder doesn’t need to enter his card data with every order, he just selects on the webshop which card he would like to use, and icheckout does all the rest.

For One-Click payment transactions, an HTTP POST request should be sent to URL:

https://host-domain/iCheckOutX/v1/icheckout/confirm.xhtml
Notice: “host-domain” should be replaced with the exact system domain.

where host-domain/ represents a merchant web domain, which is usually different for each merchant.

One-click payment requests that are sent to icheckout are similar as regular authorization requests, with a few modifications in parameters and request types.

There are 5 different request types that can be used for one-click payment transactions:

  1. Register – request type that is sent for initial card registration for the webshop. Icheckout uses this request to issue a unique account_id for the card, which can subsequently be used for later payments. Note that subfield account_id must be empty in the request, as it will be assigned by icheckout. Parameter acount_id is of type UUID and is written as a sequence of lower-case hexadecimal digits, in several groups separated by hyphens, specifically a group of 8 digits followed by three groups of 4 digits followed by a group of 12 digits, for a total of 32 digits. Registered account will not be active until card number, expiry date and card verification data is assigned to account. If expiry data and/or card verification data is missing during register account request, update account request must be used to add missing elements before account becomes active.

  2. Update – request type that is used to update card information for a specific account_id. This should be used when card number, expiry date and/or card verification data needs to be changed or added to the account. Any number of elements can be updated with one update request. Elements that must remain unchanged must not be sent in update account request.

  3. Get – This is instruction for icheckout to get card data from existing account and return it to webshop. Card PAN is always returned masked. Request must contain a valid account_id.

  4. Use – This is instruction for icheckout to use existing (stored) account information to retrieve card number, expiry date and card verification data and use it for authorization, preauthorization,completion, reversal or refund. Request must contain a valid account_id.

  5. Delete - This is instruction for icheckout to delete existing account, and should be used when account is not required any more. Request must contain a valid account_id.

Register account

The following table contains request parameters that need to be sent for valid account registration.

Presence is defined as:

M – mandatory, must be present in the message.
O – optional, present if information is available.

Parameter name Usage
trantype M –> only auth or preauth
request_type M –> fixed value register
request_hash M
purchase_amount M
purchase_currency M
order_number M
merchant_id M
terminal_id M
payment_method O
purchase_installments O
purchase_description O
customer_lang O
customer_name O
customer_surname O
customer_address O
customer_country O
customer_city O
customer_zip O
customer_phone O
customer_email O

Request:

Account registration request is sent to icheckout when a customer selects on a webshop page that he wants to save his card data so that he can use the same card for later payments on the webshop. Customer can save any number of cards, and can use any of them after they are properly registrated on the icheckout payment system. Card registration request will be used to generate a unique account_id number that is used for all subsequent payments with use account requests. For card registration, an icheckout form will be presented to the customer, in which he must enter all card information (pan, expiry date, cvv…), and when the customer selects “SAVE” button on the form, card will be registered and the transaction will be processed as preauthorization transaction with generated account_id. The transaction is processed as preauthorization to verify the customer account. If the preauthorization is declined, card registration will also be declined. If account_id is generated, it will be returned in response parameters, and that same account_id information can be later used to make subsequent orders with “Use account” request type.

Response:

If the transaction is approved response message will contain account_id response parameter filled with assigned identification code. WEB shop can use this ID code in subsequent requests to identify payment information (card number, expiry date and card verification data). If the account registration is declined, account_id parameter will be empty. Payment gateway will reject request for creating account if such functionality is not activated for merchant.

NOTE: customer card data information is not saved on the webshop domain by any means. Customer enters card data manually, and when account_id is generated by icheckout, it stores encrypted card data that is used for transaction authorization. Also, card PAN is returned masked to the webshop in response parameters, so it can be used as a reference to the customer and to the webshop.

Update account

The following table contains request parameters that need to be sent for valid account update.

Presence is defined as:

M – mandatory, must be present in the message.
O – optional, present if information is available.
C – conditional, must be present only if the parameter needs to be updated.

Parameter name Usage
trantype O
request_type M –> fixed value update
request_hash M
merchant_id M
terminal_id M
account_id M
card_pan C
card_expdate C
card_cvd C

Request:

For update account requests, a customer selects on the webshop which card they would like to modify and according to the selection, webshop sends an update account request to icheckout. A valid account_id must be sent in request so that icheckout can correctly update card data. Upon receiving an update account request, icheckout generates a customer form for card data modification in which a customer enters data that needs to be modified. For example, if only expiry date needs updating, update account request must contain new and valid card_expdate parameter and a valid account_id. Parameters like card_pan and card_cvd must be empty in this case.

Response:

oneclick_result response parameter will contain update confirmation value. Possible values are:

300 = Successful
301 = Reserved for future use
302 = Unable to update, account ID doesn’t exist
303 = Reserved for future use
304 = Failed, technical error (retry at later time)

Get account

The following table contains request parameters that need to be sent for valid account info fetch.

Presence is defined as:

M – mandatory, must be present in the message.
O – optional, present if information is available.

Parameter name Usage
trantype O
request_type M –> fixed value get
request_hash M
merchant_id M
terminal_id M
account_id M

Request:

This type of request is used to fetch card information data based on a valid account_id.

Response:

If account_id is registered in the icheckout system, card data will be returned in masked_pan and card_expdate fields. Response card PAN will always be masked. oneclick_result response parameter will contain retrieval confirmation value. Possible values are:

300 = Successful
301 = Reserved for future use
302 = Unable to retrieve data, account ID doesn’t exist
303 = Reserved for future use
304 = Failed, technical error (retry at later time)

Use account

The following table contains request parameters that need to be sent for valid account usage.

Presence is defined as:

M – mandatory, must be present in the message.
O – optional, present if information is available.

Parameter name Usage
trantype M
request_type M –> fixed value use
request_hash M
merchant_id M
terminal_id M
account_id M
purchase_amount M
purchase_currency M
order_number M
payment_method O
purchase_description O
customer_lang O
customer_name M for auth/preauth,otherwise O
customer_surname M for auth/preauth,otherwise O
customer_address M for auth/preauth,otherwise O
customer_country M for auth/preauth,otherwise O
customer_city M for auth/preauth,otherwise O
customer_zip M for auth/preauth,otherwise O
customer_phone M for auth/preauth,otherwise O
customer_email M for auth/preauth,otherwise O

Request:

This type of one-click payment request is used to make payments on a webshop using a valid and registered account_id. Transaction types that can be processed are: authorization (purchase), preauthorization, completion, reversal and refund. Card information data doesn’t need to be sent in the request. Instead, a valid and registered account_id parameter needs to be used.

Response:

oneclick_result response parameter will contain confirmation value. Possible values are:

300 = Successful
301 = Operation not permitted
302 = Request rejected, account ID doesn’t exist
303 = Reserved for future use
304 = Failed, technical error

Use account (Smart store special case)

For merchants operating as a “Smart store”, using request_type=“use” in combination with submit_type=“auto”, iCheckOutX will return regular Response parameters (along with a oneclick_result) in an XML format.

This funcionality can be used for the purposes of server-to-server communication in “use” request processing.

submit_type parameter is currently used exclusively for this special case.

Example: Use (Smart store special case) request
merchant_id="SAMPLEMID"
purchase_amount="1.01"
purchase_currency="978"
order_number="1ORD_124311_9136"
submit_type="auto"
request_type="use"
trantype="auth"
purchase_description="Test+order"
customer_name="TestName"
customer_surname="TestSurname"
account_id="a**********b"
customer_email="test@email.com"
customer_phone="+38512345678"
terminal_id="SAMPLETID"
request_hash="371dbdc92a74444abb2261a5867db63368d4105942cb934f64dcea903c7c1ca96137890ff74c91b34a30621d1d72f16be7225f6faa1b5e894f4a8056dce1906d"
Example: Use (Smart store special case) response
<response>
    <request_type>use</request_type>
    <transaction_type>auth</transaction_type>
    <order_date>2024-01-11 16:28:48.325</order_date>
    <acquirer/>
    <customer_name>TestName</customer_name>
    <customer_surname>TestSurname</customer_surname>
    <purchase_amount>1.01</purchase_amount>
    <discount_amount/>
    <purchase_currency>978</purchase_currency>
    <purchase_installments/>
    <purchase_description>Test order</purchase_description>
    <response_result>000</response_result>
    <response_random_number/>
    <order_number>1ORD_124311_9136</order_number>
    <masked_pan>4************9</masked_pan>
    <response_appcode>000111</response_appcode>
    <response_message>APPROVED</response_message>
    <response_systan>015191</response_systan>
    <card_type>Visa</card_type>
    <payment_method>card</payment_method>
    <account_id>a**********b</account_id>
    <oneclick_result>300</oneclick_result>
    <merchant_id>SAMPLEMID</merchant_id>
    <card_expdate>2312</card_expdate>
    <response_hash>11473014e25940785184da4b3c72314b5030c2f01d0d9cfe17d49390a803c0a32de621cb1b8f261829b3d992463a6a9717082daf965326c354622362497c8944
    </response_hash>
</response>

Delete account

The following table contains request parameters that need to be sent for valid account deletion.

Presence is defined as:

M – mandatory, must be present in the message.
O – optional, present if information is available.

Parameter name Usage
trantype O
request_type M –> fixed value delete
request_hash M
merchant_id M
terminal_id M
account_id M

Request:

This type of request is used to unregister a specific cardholder card. After account is successfully unregistered, subsequent payments with Use account requests won’t be possible unless a new register request is sent. A valid account_id parameter must be presented in the request.

Response:

oneclick_result response parameter will contain deletion confirmation value. Possible values are:

300 = Successful
301 = Reserved for future use
302 = Unable to delete, account ID doesn’t exist
303 = Reserved for future use
304 = Failed, technical error (retry at later time)

One-Click Payment Examples

Registration with authorization example

Register request:

trantype=auth
request_type=register
purchase_amount=15.00
purchase_currency=191
order_number=1ORD_1211310_9607
merchant_id=SAMPLEMID
terminal_id=SAMPLETID
purchase_description=Test+order
customer_name=TestName
customer_surname=TestSurname
customer_address=Test+Address
customer_country=Hrvatska
customer_city=Test+City1
customer_zip=10000
customer_lang=hr
customer_email=test@email.com
customer_phone=+38512345678
request_hash=78ec32466a1b3f40533ec6d38304c3c9d4e87e96a71629c7ea8a4f0d68fa78355c79b18392e6030eb6c0a6d28ea2819357d3f3ea3581fb34738d114cea1d974b

On icheckout payment form, customer enters their card data:

card_pan=4********0000
card_expdate=2701
card_cvd=***

Register response:

account_id=23d92892-2c2e-11ec-bead-f0b913d67fdb
acquirer=***
card_type=Visa
card_expdate=2606
customer_address=Test Address
customer_city=Test City1
customer_country=Hrvatska
customer_email=test@email.com
customer_lang=hr
customer_name=TestName
customer_surname=TestSurname
customer_tel=+38512345678
customer_zip=10000
masked_pan=400000******0000
merchant_id=SAMPLEMID
oneclick_result=
order_date=2021-10-13 16:01:57.316
order_number=1ORD_1211310_9607
payment_method=
purchase_amount=15.00
purchase_currency=191
purchase_description=Test order
purchase_installments=
request_type=register
response_appcode=160204
response_hash=750181435d591d12d0f3fc393c236ce136a1e151bacedf4906ec6aeb8b71b4d7e0ac8342681c98db6a7e75df2c37c6ed1503c0bfe91dcd8551974d4db9430c3a
response_message=ODOBRENO
response_result=000
response_systan=003169
transaction_type=auth

Since account_id parameter is received in response, account registration was successful.

Update account example

In previous card registration example, a newly assigned account ID was received: 842ec9ca-cde9-11eb-8738-7acb13d67fdb
which can now be used as an example for an account update request.

Update account request:

trantype=auth
request_type=update
merchant_id=SAMPLEMID
terminal_id=SAMPLETID
account_id=842ec9ca-cde9-11eb-8738-7acb13d67fdb
card_expdate=2408
card_cvd=444
request_hash=3f9dba73c8a70818aab720d30076206fd38860bba972ef443e39c7f203950a9928f1693f50f2f7eda84f6c4da0707413b166a5de723713333cb9ccf6c80d874b

Update account response:

account_id=
acquirer=
card_type=
card_expdate=2408
customer_address=
customer_city=
customer_country=
customer_email=
customer_lang=
customer_name=
customer_surname=
customer_tel=
customer_zip=
masked_pan=
merchant_id=SAMPLEMID
oneclick_result=300
order_date=
order_number=
payment_method=
purchase_amount=
purchase_currency=
purchase_description=
purchase_installments=
request_type=update
response_appcode=
response_hash=8c24f5fd9546b638482ae44525ea47c0fcc2bdf87c5df84f923b09b67987ed8d71dde7345679064afe251a20652369b6894bfce7b06f65a9c1916d7aeba76071
response_message=ODOBRENO
response_result=000
response_systan=
transaction_type=auth

Since value ‘300’ was received in parameter oneclick_result, the account was successfully updated.

Get account example

Get account request:

trantype: auth
request_type: get
merchant_id: SAMPLEMID
terminal_id: SAMPLETID
account_id: 842ec9ca-cde9-11eb-8738-7acb13d67fdb
request_hash: 5ad15ebb79c1cc6edd86c63251217aa5eae496c702fcd9e49bea5a4b61b26877469cf04b74500e8e0573f1659cc94fbc4289938b684a036bd3be732f9d22743e

Get account response:

account_id=842ec9ca-cde9-11eb-8738-7acb13d67fdb
acquirer=
masked_pan: 4000*********00 
card_expdate: 2312
customer_address=
customer_city=
customer_country=
customer_email=
customer_lang=
customer_name=
customer_surname=
customer_tel=
customer_zip=
discount_amount=
masked_pan=
merchant_id=DEMOBBANK
oneclick_result=300
order_date=
order_number=
payment_method=
purchase_amount=
purchase_currency=
purchase_description=
purchase_installments=
request_type=get
response_appcode=
response_hash=b5717b459b745d469b7189910f5ed90781a912d0f4abeafb9c7e7e87abbd0ffd4a81eb91d32fec32c1c4d98769abd11aceff31c9c58cd68f7e8e3890f6a3eb25
response_message=APPROVED
response_result=000
response_systan=
transaction_type=auth

The get account request was successful since parameters masked_pan and card_expdate are received in response.

Use account example

Use account request:

trantype: preauth
request_type: use
merchant_id: SAMPLEMID
terminal_id: SAMPLETID
account_id: 842ec9ca-cde9-11eb-8738-7acb13d67fdb
purchase_amount: 1.00
purchase_currency: 191
order_number: ORD_TEST_12345
payment_method:
purchase_description: Test
customer_lang: en
customer_name: TestName
customer_surname: TestSurname
customer_address: TestAddress
customer_country: Hrvatska
customer_city: 
customer_zip: 
customer_phone: 
customer_email: test@email.com
request_hash: 8ea5147d13e8a1869432280249272eb7cf44ede061918b39c142f7824fadd628784ae5b1a440006bcffa30b5bb55bc6cbe8a2dc0f1a496cc7b7d16485dd1b0f9

Use account response:

customer_address: TestAddress
customer_city:
customer_country: Hrvatska
customer_email: test@email.com
customer_lang: en
customer_name: TestName
customer_surname: TestSurname
customer_tel:
customer_zip:
order_date:
order_number: ORD_TEST_12345
payment_method:
purchase_amount: 1.00
purchase_currency: 191
purchase_description: Test
purchase_installments: 0
request_type: use
response_appcode: 889834
response_message: ODOBRENO 
response_result: 000
transaction_type: preauth
account_id: 842ec9ca-cde9-11eb-8738-7acb13d67fdb
oneclick_result: 300
response_hash=750181435d591d12d0f3fc393c236ce136a1e151bacedf4906ec6aeb8b71b4d7e0ac8342681c98db6a7e75df2c37c6ed1503c0bfe91dcd8551974d4db9430c3a

The preauthorization was approved since oneclick_result=300 was received.

Delete account example

Delete account request:

trantype: auth
request_type: delete
merchant_id: SAMPLEMID
terminal_id: SAMPLETID
account_id: 842ec9ca-cde9-11eb-8738-7acb13d67fdb
request_hash: 7278b3541776d467b7257dc11037d7b0ce79c08427f841ec225d426af1b3093e6ed0c28205ed4b8651925595dcfa6cf284da1cb310947dd81d67b3a57619ae0b

Delete account response:

transaction_type: auth
request_type: delete
merchant_id: SAMPLEMID
terminal_id: SAMPLETID
account_id: 842ec9ca-cde9-11eb-8738-7acb13d67fdb
response_message: ODOBRENO
response_result: 000
oneclick_result: 300
response_hash=b5717b459b745d469b7189910f5ed90781a912d0f4abeafb9c7e7e87abbd0ffd4a81eb91d32fec32c1c4d98769abd11aceff31c9c58cd68f7e8e3890f6a3eb25

The account was successfully deleted since oneclick_response=300 was received.