Version | 2.3.3 |
Last update | 2024-07-31 |
Author | ZMS Info |
iCheckOutX is a WEB front-end service which simplifies web-shop integration with iPayGate by utilizing web technology and standard functionalities.
iCheckOutX provides:
iCheckOutX solution supports multiple transaction types and payment
channels.
Supported transaction types include:
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:
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 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.
Before merchant can start its integration with iCheckoutX system the following prerequisites must be met.
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.
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.
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.
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.
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.
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).
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">
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.
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 |
(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 |
(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 |
(deprecated) | |||
terminal_id | Terminal ID | AN | 32 |
(deprecated) | |||
trantype | Transaction Type | AN | 20 |
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.
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 |
(deprecated) | |||
response_result | Response Result | N | 3 |
response_systan | Transaction System Trace Audit Number | AN | 6 |
transaction_type | Transaction Type | AN | 20 |
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 |
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
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 |
(deprecated) |
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. |
Type: alphanumeric
submit_type has been deprecated and should not be included in any request.
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.
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.
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.
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
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.
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.
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)
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:
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 ‘&’.
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.
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:
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 ‘&’.
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
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
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 |
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.
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
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 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 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.
Along with regular card payment, iCheckOutX supports some other payment methods.
These are:
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.
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.
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.
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.
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:
customer_address
customer_city
customer_country
customer_zip
customer_name
customer_surname
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:
The following links should help to integrate GooglePay option into merchants webshop:
integration overview: https://developers.google.com/pay/api/web/overview
integration checklist: https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist
brand guidelines: https://developers.google.com/pay/api/web/guides/brand-guidelines
The following links should help to integrate GooglePay option into merchants Android application shop :
integration overview: https://developers.google.com/pay/api/android/overview
integration checklist: https://developers.google.com/pay/api/android/guides/test-and-deploy/integration-checklist
brand guidelines: https://developers.google.com/pay/api/android/guides/brand-guidelines
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
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
merchant_id=SAMPLEMID
order_number=1ORD_121299_3108
request_type=checkstatus
terminal_id=SAMPLETID
request_hash=33aba71b36782c729d89c63d3651799eac1496485b4b03d169b97e6e1becb14b46a5e894b7a5c8ea5b981a3a112956feccc78c1c3d353134c5c12dc99dfdadc6
<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>
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:
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.
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.
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.
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.
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.
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.
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)
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)
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
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.
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"
<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>
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)
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=***
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.
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.
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
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.
trantype: auth
request_type: get
merchant_id: SAMPLEMID
terminal_id: SAMPLETID
account_id: 842ec9ca-cde9-11eb-8738-7acb13d67fdb
request_hash: 5ad15ebb79c1cc6edd86c63251217aa5eae496c702fcd9e49bea5a4b61b26877469cf04b74500e8e0573f1659cc94fbc4289938b684a036bd3be732f9d22743e
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.
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
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.
trantype: auth
request_type: delete
merchant_id: SAMPLEMID
terminal_id: SAMPLETID
account_id: 842ec9ca-cde9-11eb-8738-7acb13d67fdb
request_hash: 7278b3541776d467b7257dc11037d7b0ce79c08427f841ec225d426af1b3093e6ed0c28205ed4b8651925595dcfa6cf284da1cb310947dd81d67b3a57619ae0b
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.