Real Time (HTTPs) APIs




Integration Notes


3D Secure Verification  

To learn more about 3D Secure, follow this link.

3D secure authorization with MPI can be implemented in two ways:
  • Hosted payment page is used. In addition to the regular workflow, 3D secure authorization will be incorporated in the process if the card is enrolled and the results of 3D secure verification will be used to process the transaction. In this case, 3D secure redirects will be handled by the system. No additional actions are needed. Appropriate API configurations must be set up within the system.
  • Hosted payment page is not used. In this case, processing will happen in two phases. After an API call is made, the system will verify whether 3D Secure is required. If 3D Secure is not required, then the submitter will get a regular API response - approval or decline. If 3D Secure is required, the submitter is going to receive X03 response code indicating that a subsequent redirect of the cardholder is necessary. In such case, the submitter needs to use the transaction ID returned in the transaction response and execute the redirect (specifying callback URL where the final result should be posted). The redirect is going to lead the cardholder to the card issuer's website for 3D Secure verification. The result of 3D Secure verification will be returned to the gateway and the gateway will attempt to complete the transaction (complete authorization). The final result of the transaction is going to be posted to the URL supplied by the submitter within the redirect request.

Please, note that there are several possible outcomes of the 3D Secure verification process. You can decide whether to complete authorization based on 3D Secure verification outcome and configure the system to act accordingly. For those cases when subsequent authorization is not desired, the transaction will be declined with E10 response code.

Below you can find the possible outcomes with their explanation:
Status Message
U or blank Unable to Authenticate. Process transaction as Normal SSL.
N Failed Authentication. Reject transaction.
Y Authentication Successful. Proceed to authorization.

For example, you can choose to only proceed with transaction authorization if the status of 3D Secure verification is Y. You can also attempt to authorize regardless of the status.

Account Data  

The field accountData contains one of the following items:
1) for payment cards:
  • track data (unencrypted/encrypted);
  • EMV data (unencrypted/encrypted);
  • manually keyed number;
2) for Check21 transactions:
  • MICR data


Track Data

The system supports submission of track data in two ways - encrypted and unencrypted. Both are submitted within accountData field.
When the accountData field contains unencrypted track data, it has to be encoded before it is sent to eliminate any issues with special characters. Use standard URL encoding procedure for that.
If track data is encrypted, generally, encoding is not required (but it may be needed if non-alpha-numeric characters are present). The system accepts track data encrypted by both external and internal encryption methods. If an internal encryption method is used, the system will decrypt track data with a key registered within the system and submit decrypted value for processing. If an external encryption method is used, the data will be passed to the processor as it was received by the gateway i.e. without modifications. To identify that submitted data is encrypted, its value has to be preceded by tilde sign (~). Otherwise, the system assumes that data is unencrypted. For example, ~021301000F3D0000%*4111.....

Currently, three encryption algorithm are supported for track data encryption:
  • TDES - a symmetric algorithm that requires one key for both encryption and decryption. Used by ID Tech devices.
  • AES - a symmetric algorithm that requires one key for both encryption and decryption. Used by ID Tech devices.
  • RSA - an asymmetric algorithm that requires two different keys for encryption (public key) and decryption (private key). Used by a native terminal application.

Currently, the following ID Tech models are supported by the system:
  • M100
  • M130


EMV Data


When the accountData field contains unencrypted EMV data, its value has to be preceded by exclamation mark (!). For example, !4F07A00.....
To identify that submitted EMV data is encrypted, its value has to be preceded by exclamation mark and tilde sign (!~ or ~!). For example, !~021301000F3D0000%*4111.....

EMV processing requires various tags to be included into receipt. These tags are also included in account data associated with a particular EMV card. Tags in transaction response come in random order, so the format can start from any available tag. Account data in transaction response includes both required and optional tags. The tag 0x91 is a required tag. It is always present in the transaction response. The tag 0x8A allows to check the status of the transaction. It is optional and whether it is present or not in the response depends upon the processor. Full list of EMV tags is available here.

Please see request and response examples of sale operation with EMV card for more details.

Authentication  

Authentication is a mechanism that allows a service user to obtain a temporary one-time password for subsequent use in API calls instead of a permanent password. A temporary password is active for 10 minutes only.

A temporary password is used in the following cases:
  • when a service user is configured to access API using a temporary password only. In this case, the only API operation that a user can access with a permanent password is authentication to have a temporary password generated. After the temporary password is received, the user obtains access to other API operations for a limited period of time. See Security Management guide for more information.
  • when a service user submits transactions via a hosted payment page. Because HPP is rendered in a user’s browser, the authentication information can be cached by the browser. This potentially provides a security hole in the system and hence an opportunity for hackers to exploit the system. In this case, a temporary password can safely be serviced to customers using HPP even if caching is potentially possible.

Authorization and Settlement  

Transaction processing is comprised of two steps and can be implemented as a one-step process or two-step process. The steps are authorization and settlement. It’s possible to do authorization and settlement in one shot (which often used in bill payment and recurring billing) or in two different steps.

1st step – During authorization step, a card is verified for its validity and specified amount of money is blocked on the card for future settlement. Therefore, successful authorization implies that card is valid and the needed amount of money is present on that card at that time.

2nd step – During settlement step, previously allocated amount of money on the card is sent to the account, the actual transfer of money takes place. There are two scenarios to settle transaction: host capture and terminal capture.

  • In terminal capture scenario merchant is required to supply all the settlement information about each transaction to be settled at the time of settlement. And settlement doesn’t occur until the merchant submits this information.
  • In host capture scenario the settlement is handled by authorization system without any explicit information from the merchant. There are two conceptual ways of looking at host capture. Host capture can be implemented using two mechanisms: merchant-initiated and time-initiated. During merchant-initiated process, settlement is taken care of by the host. The process doesn’t start until merchant explicitly sends in a settlement message or settlement request. During time-initiated process settlement happens automatically at a certain time and there’re two common approaches: either once a day at a specified time or multiple times per day every ‘X’ number of hours.

Capture, Void and Refund Operation  

Capture

UniCharge provides an auto-settlement mechanism to all merchants. Settlement occurs once per day at the time designated by a merchant (usually at night). When settlement occurs, all sales processed the same day as well as all captured authorizations are posted and money is deposited. Consequently, Capture operation can be issued on authorization if and only if the settlement has not yet occurred. If merchant misses the settlement cut-off time, a new sale will have to be issued.

Capture operation can be used in cases when authorization amount and capture amount are different. Capture amount cannot exceed authorization amount; the only exception is tip adjustment functionality. For example, if authorization amount is $100 and customer indicates tip amount $10, capture amount will be $110. In this case field 'amount' takes value $110 while field tipAmount takes value $10.

Some of the processors support multiple capture of sale-auth transactions allowing to capture parts of authorized amount. In this case, capture operation can be executed several times. A total amount of all partial capture transactions that are submitted, must not exceed the authorization amount of the original sale-auth transaction. To use multiple capture, verify whether an underlying processor supports this functionality.

Void

Void is used to reverse sale or credit transaction before settlement for the day occurs. Void can be either submitter-initiated (issued via the user interface or API) or gateway-initiated (issued automatically during the transaction processing under certain circumstances). When void is initiated by the submitter, the transactionId field has to be submitted as an identifier of the transaction. See integration notes for more information.

A transaction gets voided automatically by the gateway in the following cases:
  • At the settlement time, if sale-auth/credit-auth transactions are not captured at the moment when settlement occurs.
  • At the authorization time, if a user sends a sale/sale-auth/credit/credit-auth request and does not receive a response due to a communication error. Therefore, the API is called but the response in not consumed by a submitter. Note that if a hosted payment page is used and a user closes a page before being redirected to the result, it does not count as an error and the transaction will be processed anyway.
  • At the authorization time, if a submitter does not support partial authorization (isPartialAuthorization flag is set to false) and partial approval is received as the transaction response. See integration notes for more information.
  • At the authorization time, if a post-processing filter gets triggered and requires a reversal of the transaction. See integration notes for more information.
  • At the authorization time, if an external fraud protection tool similar to post-processing filter requires reversal of the transaction. See integration notes for more information.
  • At the transaction time, when a transaction is made via a terminal and the payment card gets removed before processing has been completed or processing is declined by a card chip.
  • At the transaction time, when a transaction is made via a terminal and the transaction is unprocessed due to timeout or connection is lost between the terminal and the gateway/cloud. In this case, the POS issues void as well.

When void is initiated, the process goes as follows:
  1. The gateway marks the transaction to prevent the transaction from getting settled.
  2. The gateway attempts to reverse an authorization to release funds that were held during processing. If the reversal attempt is successful, A03: Void Posted (Auth Reversed) responseCode/responseMessage are received in the void response. If the attempt is unsuccessful, A06: Void Posted (Auth Not Reversed) responseCode/responseMessage are received. The unreversed authorization will eventually expire; however, a cardholder will not be able to use the amount that was blocked, and a merchant may incur misuse of authorization assessment.

If void that has been initiated and sent to a processor is subsequently declined due to some reason, the following responses can be received:
  • When a gateway-originated void that was done at the authorization time is declined, A11: Approval (Reversal failed) responseCode/responseMessage are received in the response.
  • When a merchant-originated void is declined, S26: Operation declined by the processor. responseCode/responseMessage are received in the response.

When a void is declined, the transaction needs to be reverted manually by issuing a refund.

Refund

Refund is used to issue a credit for sale transactions where settlement has already occurred. Consequently, refund will always succeed in reversing any existing (unrefunded) sale transaction.

Available Actions

The following actions can be applied for sale-auth, sale, credit and refund operations:
Transaction Type Actions
void capture partial
void
partial
capture
refund partial
refund
sale-auth (approved) x x x x
sale-auth (approved)
+ partial void
x x x
sale-auth (approved)
+ partial capture
x x
sale-auth (settled) x x
sale (approved) x x
sale (approved)
+ partial void*
x
sale (settled) x x
refund/credit x
* Note that only one partial void is allowed. If a transaction has already been voided partially, then only full void can be made for remaining transaction amount.

Client Host  

To eliminate potential fraud and to help with the resolution of suspected duplicate transactions, the gateway can track two host/IP addresses (request host and client host).

Request host is the host or IP-address of the external system submitting directly to the gateway.

Client host is the host or IP-address of a client that originated the transaction through some action (such as on-line purchase) in the external submitting system (which then issued direct request to the gateway).

When transaction is processed, the host/IP address of the submitting system (request host) is automatically captured; in addition, the integrators of web-based solutions are encouraged to include the host/IP address of the client into their system (using clientHost field), which, in turn, results in the gateway request.

For example, a customer from IP-address 211.167.76.181 connects to ShoppingCart.com (which communicates with the payment gateway). When the request is sent, the gateway automatically captures IP of the ShoppingCart.com, and ShoppingCart.com software is encouraged to include the IP address 211.167.76.181 in the gateway request as part of the clientHost field.

Cross-reference Fields  

The system provides an ability to specify values that can be used for cross-referencing of entities between the gateway and a submitter’s system. The fields that can be provided by an integrated external system are listed below:











Entity Field Name Description
Transaction transactionCode Identifier of the transaction assigned by an external system that submits the transaction for processing.

Note that if you would like to avoid having multiple transactions with the same transactionCode value, transaction duplicate policy has to be configured correspondingly on the user interface.
transactionInternalCode* Unique internal identifier of the transaction assigned by an external system that submits the transaction for processing. Can be used as a supplement to a transactionCode.
Customer customerAccountCode Identifier of a customer assigned by an external system that submits the transaction for processing.
customerAccountInternalCode* Unique internal identifier of a customer assigned by an external system that submits the transaction for processing. Can be used as a supplement to a customerAccountCode.
Item itemCode Identifier of a purchased product or service assigned by an external system that submits the transaction for processing.
Split Schema splitSchemaCode Identifier of a split schema assigned by an external system that submits the transaction for processing.


*In some cases, the submitting system is going to have two different identifiers for a given transaction: one, shown to the end user on the UI, and the other one, a system identifier (very often a database-generated artificial ID). In such cases, the user-visible ID (which is used in the business context) should be submitted in the regular fields (in transactionCode or customerAccountCode), while internal ID (artificial ID), should be sent as transactionInternalCode or customerAccountInternalCode.

Delayed Transactions  

Delayed processing can be employed when it is necessary to notify gateway of a pending transaction request, which is then subsequently finalized as the second phase of the processing. It is most commonly used when POS system initiates request for transaction to the gateway, which is then subsequently handled by a payment terminal. Generally, a POS system will submit a transaction using regular request with processingMode=request or processingMode=queue. Subsequently, terminal executes fetch operation, which is triggered by pressing button on a terminal, and the terminal receives the information passed by the POS from the gateway, collects the information from the cardholder and then processes the transaction with the gateway. Once the transaction is processed, POS receives the notification on the URL, which is specified in the initial request.

Please note that the callback mechanism, employed here, is similar to the one used in the payment pages, and the kind of interaction with a terminal is only recommended to those people that are using payment page in a similar fashion.

Delayed transactions can be sent to the gateway in two modes:
  • with processingMode = request. In this case, only one request at a time will be sent to the gateway. This implies that the gateway is only going to accept a subsequent transaction request for processing if previous request has already been completed at the time of the call;
  • with processingMode = queue. In this case, all requests will be queued up. The gateway will accept any number of requests for the given terminal and put them in a linear queue.

Direct Debit  

Direct debit is the process of funds transfer from one bank account to another. Currently, the following direct debit systems are supported within the system: ACH for US and Canada, BACS for UK, SEPA for EU and Direct Entry for Australia and New Zealand. For direct debit transactions, two fields are required: bank identification number, submitted as accountAccessory, and bank account number, submitted as accountNumber. To format these fields correctly, please use guidelines below depending on the country.

US ACH

For ACH transaction processing in the US, routing number is used as accountAccessory and its format is nine-digit number. For example, 325070760. See this link for more information.

Canada ACH

For ACH (EFT) transaction processing in Canada, three fields are required: three-digit institution number, five-digit branch number, and account number. For processing purposes of Canadian ACH, the institution number and branch number are combined in a single routing number value using the rules below.
  • The Canadian routing number is comprised of three parts: a leading zero (0), three-digit institution number (YYY) and five-digit branch number (XXXXX), which go respectively all together with no dashes: 0YYYXXXX. Please, note that the institution number (YYY) should never be all zeros (000). See this link for complete list of institution numbers.
  • The XXXXX-YYY format with a dash between the branch number and the institution number is only valid for paper-type transactions, such as checks. Thus, if a check reads XXXXX-YYY, the corresponding EFT code will be 0YYYXXXXX.

EU SEPA

For SEPA transaction processing in the European Union, bank identification number is submitted in BIC format and bank account number is submitted in IBAN format.
  • Bank identification number consists of 8-11 characters and is comprised of four parts: four-letter institution code or bank code, two-letter country code, two-letter or two-digit location code and three-letter or three-digit branch code. Last three characters are optional. See this link to have better understanding of BIC format.
  • Account number consists of up to 34 alphanumeric characters and is comprised of three parts: two-letter country code, two check digits and a long and detailed bank account number. See this link to have better understanding of IBAN format.

UK BACS

For BACS transaction processing in the United Kingdom, format of these fields is the following:
  • Bank identification number is formatted as sort code, which is a six-digit number, formatted as three pairs of numbers. For example, 12-34-56. See this link for complete list of sort codes.
  • Account number consists of 8-10 digits.

Australia/New Zealand Direct Entry

For Direct Entry transaction processing in Australia, format of these fields is the following:
  • Bank identification number is submitted in BSB format. It consists of 6 digits and is comprised of two parts: two-digit bank code and four-digit branch number. For example, 033088. See this link for complete list of Australian bank codes and this link for complete list of New Zealand bank codes.
  • Account number consists of up to 17 characters.

Dynamic Descriptor  

An important feature that many merchants require is support for custom defined soft descriptor. Depending on the processor, this feature can be supported as a static value associated with an underlying merchant ID or as a dynamic value that can be specified for each transaction processed.

For credit cards, the descriptor is a single value 25 characters length; for direct debit, the descriptor is comprised of two fields: Merchant Name (13) and Item Descriptor (10), the values should be separated with two colons (:), e.g:

[descriptor]::[merchantName]

When transactions are processed through PSP or an aggregator, it is common to include an identifier of the underlying payment processor or aggregator through a prefix, which is, usually, 3 or 6 characters in length. The prefix is added to the name of the merchant and is generally separated from it by an asterisk (*).

For each transaction processed through a processor, which supports dynamic descriptor feature, submitter can supply the value of the descriptor in the following format:

[item-descriptor]:[prefix]*[merchant-name]

Note that a processor can require a specific set of symbols to be present or absent in the descriptor. To avoid any issues, such symbols as ampersand (&) and asterisk (*) are replaced with a space ( ) in real-time API requests.

Each part of the descriptor is optional; if respective value is not supplied at the transaction level (as part of the request), the default value will automatically be taken from the profile (if it is configured). When deciding on which value to supply, please make sure that maximum allowed length for each component is respected.

If the descriptor is not formatted correctly, the system is going to make the best attempt to properly truncate the values and process the transaction. A special warning will be issued and returned to the submitter (as warningCode field) explaining how descriptor should be adjusted in the future submissions.

Different payment card associations (Visa/MC/Discover) have different processing rules and timelines. While a Visa transaction is funded within 24h and cardholders may see the transactions in their online account almost instantly after an authorization happens (depending on their issuing bank), Amex takes 3 days to fund and sometimes it may take up to 3 days to see the transaction settled into the account and to have the transactions show up in online cardholder’s account. Please note that this delay depends on Amex processing rules only and can't be changed in the settings of the gateway.

Depending on the processor, dynamic descriptor mechanism can be supported at the authorization time or at the settlement time. In cases when the mechanism is supported at the settlement time, the descriptor gets supplied only after the transaction is settled. This means that a transaction will show up on cardholder's bank account with a generic descriptor (in pending authorizations section), while in a day (or 2-3 days later in case of Amex) it will be displayed with the proper descriptor.

While all issuing banks will show at least the descriptor characters when the transaction is presented to the card holder, some can show more information (such as merchant name, phone, merchant state). It doesn't depend on the settings of the gateway and is specific to an online banking system of a particular issuing bank.

For all processors that support descriptor, processors configuration profile contains fields allowing to specify the default value that is used in a transaction if descriptor was not explicitly provided within the request. For those cases when you don't want to supply descriptor and you don't want any default values from the profile to be used (basically, you don't want to supply any descriptor information to the processor), you can send the value "-::-" in the descriptor field. This will indicate to the system that no descriptor information should be supplied to the processor and whatever descriptor is associated with the respective MID at the processor's end will be used.

External API Data  

When the hosted payment page mechanism is used, various custom parameters that are not part of the real-time API can be submitted within a request. Under usual circumstances, these parameters are not stored in the gateway. However, for cases when the information that is not related to the gateway API should be recorded within the gateway, it can be submitted with an underscore (_) in a parameter name, while a value of the parameter is submitted as it is. For example: _name1=value1&_name2=value2. Length of the data that can be stored in the database is limited to 300 characters.

Regardless of whether custom data has been submitted with or without an underscore, it is always returned as a part of an API response or within a callback. Note that if data submitted in the request exceeds 300 characters, a corresponding warning code (T: Custom parameters data truncation) is returned within the response indicating that the remaining characters cannot be saved.

Fallback Transactions  

Fallback is a mechanism, which allows to process an EMV card without using EMV technology in exceptional situations, when proper EMV processing is not possible. At the normal circumstances, an EMV card can be processed using an integrated circuit, or using contactless technology by tapping card. In situation, when none of these approaches can be used, a fallback routine is initiated. Currently, the fallback routine may be initiated because of the following reasons:
  • technical fallback - occurs when processing is not physically possible. For example, if the chip does not respond when the card is inserted. In this case, the terminal will allow to swipe this card.
  • no application match - the chip contains one or more applications, that are selected by the terminal to process the transaction. In order for transaction to occur, the terminal must be configured to deal with the apllications that are available on the chip. Situation might occur, when none of the applications, available on the chip, are supported by the terminal. For example, when current credit card is used on the terminal that only accepts US debit cards. In such cases, fallback will be allowed and the merchant can swipe the card if transaction is desirable.

Format Field  

For cases when it is needed to vary the fields that are received within sale or sale-auth API response or callback, format field included in a respective API request is used.

Currently, the following value is supported:
  • signature - implies that a transaction is card-present and is made using digital signature capture device. Signature image is going to be included in sale/sale-auth callback within signatureContent field.

Note that all values that are submitted within format field are required to be pipe-delimited.

Healthcare Industry Transactions  

When processing a healthcare industry transaction (using HSA account What is it?) additional amount fields need to be specified.

The only amount that is required is healthcareAmount, while other amounts are optional. If medical transportation was involved, then transitAmount should be added.

Depending on the type of service rendered, additional amounts can be specified to healthcareAmount to indicate how much was spent on prescription (prescriptionAmount), vision/optical (visionAmount), dental (dentalAmount) and clinic/hospitalization (clinicAmount) services. The total of prescription, vision, dental and clinic amounts can be less than or equal to healthcareAmount.

Holder Name Normalization Rules  

Currently, the gateway saves the holderName field value as two separate values: firstName and lastName. If a holder’s name, which is submitted to the gateway by a user or within track data/EMV data, contains more than two words (for example, a middle name is included), the following rules are used to split holderName into firstName and lastName:
  • when the additional word is an initial and contains only 1 character, it gets removed automatically. In this scenario, only the first and last names are shown within the holderName field in the response. For example, if JOHN/J SMITH is submitted as the holderName field value within the request, JOHN SMITH is returned within the holderName field value in the response;
  • when the additional word is a middle name and contains 2 or more characters, the system defines it as a part of the first name. In this scenario, the first and the last name get reversed, and the middle name is returned as the first name within the holderName field in the response. For example, if SMITH/JAMES JOHN is submitted as the holderName field value within the request, JAMES JOHN SMITH is returned within the holderName field value in the response.

Identity Verification  

In some cases, additional identity information is necessary to complete a direct debit transaction. This additional information can be supplied using four identity verifications fields: driverLicenseNumber, driverLicenseState, identityVerificationType and identityVerificationValue.

Fields driverLicenseNumber and driverLicenseState can be used to transmit account holder’s driver license number and driver license state (for the US) or province code (for Canada and Australia) respectively.

They also can be used to provide a courtesy card ID issued for an account holder. In this case, the value of courtesy card ID must be supplied as driverLicenseNumber, while the value of driverLicenseState should be set to XX.

Increment  

Increment operation can be used to increase the authorization amount of already authorized transaction (to add payment for additional product or service). For example, if amount of $100 was originally authorized, and additional amount of $20 needs to be added, you will send an increment request for $20. If increment succeeds, the response message is going to indicate the total amount of $120 that is currently authorized as part of this transaction. Increment operation is primarily used within lodging industry and should not be used within restaurant industry to add tips. Tip adjustment functionality should be used in such case.

Interchange Rate Qualification  

Based on the fields present in a transaction, transaction may qualify for different interchange rates. Among the fields that commonly affect qualification for Card Not Present transactions (those that do not involve track data) are CSC code and address fields (street, city, state, ZIP code). Presence of these fields reduces possibility of fraud and therefore improves the interchange rate, that the transaction qualifies for, as well as a greater chance of winning a dispute by merchant in case of chargeback. Providing these fields is highly recommended and among address fields, at least, ZIP code should always be provided.

Legacy Fields Names  

To unify field names within the APIs and the user interface of the gateway, the following reference field names have been changed:

Deprecated Field Name New Field Name
merchantCode merchantId
merchantAccountCode accountId
terminalCode terminalId
referenceNumber transactionId
providerReferenceNumber providerTransactionId
originalReferenceNumber originalTransactionId
aggregateReferenceNumber aggregateTransactionId
submissionCode submissionId
transactionCategory transactionCategoryType

Both deprecated and new names are currently supported by the system. The deprecated names will be supported until October, 30th, 2019. All new integrations should be done with the new names only.

Note that if you submit account ID value via the merchantAccountCode field within an API request, the system will return deprecated field names within the response. If account ID value is submitted via the accountId field, the system will perform validation using new field names.

Manual Cycle Closeout (settlement)  

All retail transactions are batched daily and settled when a corresponding retail cycle is closed. Each account that requires retail transaction processing must have a retail cycle associated with it.

By default, retail cycle is closed and settled automatically on daily basis. However, manual closeout is possible through close cycle request. Issuing such request allows merchant to close and settle any cycle at any moment in time. If a request is issued on the account that has no retail cycle associated with it at the moment, the request will be ignored and no action will be taken by the system.

Additionally, there is a manual batch approval logic available in the system. This logic is applicable to processors that support terminal capture. If the function of manual batch approval is enabled, every closed batch must be explicitly approved before it is sent for further processing. The batch approval can be done through the user interface of the gateway. Alternatively, the batch approval can be done through the API using isSettlementApproved parameter in closeCycle request. Setting the value of isSettlementApproved=1 will override the manual batch approval logic that might be available in the gateway.

Depending on the settings, the value of the cycleType field is set according to the following rules:
  • In case cut-off time is set only for card transactions or coincides for both cards and direct debit, the value of the cycleType field is automatically set as Primary. In this scenario, one RTC is closed for both cards and direct debit transactions.
  • In case cut-off time is different for card and direct debit transactions, the value of the cycleType field is automatically set as Secondary. In this scenario, two RTCs are closed - one for cards, and one for direct debit.

Non-Financial Operations  

Recording of non-financial transactions can be accomplished using the sale-info operation. Here are some example situations wherein the sale-info operation might be used:
  • To record cash, check, credit card transactions, which were performed outside of the gateway. In general, this is done to capture transactional data or for loyalty and gift points accumulation.
  • For the exchange of goods at the POS. For example, exchange of a T-shirt of one color to another. Some merchants may choose not to record such exchange while others may like to record it using non-financial transactions. To account for these scenarios, the sale-info operation exists.

Therefore, sale-info can be used to record credit card transactions that took place outside of the gateway, or cash or check transactions. In this case, the amount of the actual transaction can be specified. In case of exchange, the amount has to be set to zero, explicitly stating that no money was actually withdrawn or returned from a customer.

Offline Transactions  

Offline processing occurs when communication with a host is either impossible or not desired. There are two types of offline transactions:
  • Offline authorization is used for EMV transactions. In this case, transaction is authorized offline using EMV chip within the card. Commonly used for "on-board" transactions (when there is no internet connection, for example, on a plane or a ship). The chip's decision (approval or decline) is synchronized with a host when the internet connection is reestablished.
  • Store-and-forward is used for non-EMV transactions. When store-and-forward functionality is used, the transaction is not authorized. If transaction amount is below pre-set floor limit, payment information is saved within the terminal. Once internet connection is re-established, the transaction is submitted to the gateway for processing. The general expectation is that most of such transactions will get approved, although, it is possible that some of them will get declined.
A callback URL can be specified in order to allow POS systems to be notified of the outcome of offline transactions.

Please contact support to register your desired callback URL. The delivered callback will follow the same format as the response message for a sale or sale-auth operation.

Partial Authorization  

For retail and restaurant industries, there can be cases when a cardholder has no sufficient funds on the card to pay for goods/services. For this purpose, when a sale/sale-auth operation is done and a full transaction amount is not available on the payment card, the system provides the ability to split the transaction into several parts via the partial authorization mechanism. In this case, different payment options can be used to cover the total amount of the transaction.

When partial authorization is done, a submitter receives partial approval for the amount that corresponds to the funds available on the card. In this case, authorized amount is shown in the API response within the amount field and originally requested authorization amount is shown within the originalAmount field. Optionally, the balance field may be returned (depending on the issuing bank of the card) indicating the balance that available on the card after authorization is done.

If partial authorization is not desirable, it can be disabled via the corresponding field (isPartialAuthorization = 0). In this case, when the processor returns partial authorization, the gateway reverses processor's authorization and returns decline code with a corresponding message (D03 Insufficient Funds) to the submitter.

Partial Settlement  

When supported by underlying processor, it is possible to perform a partial capture/settlement on a transaction. This functionality may be useful when original authorization was for an amount greater than the actual amount of the transaction (for example, customer placed an order, but some items were discovered as being out of stock at a later time). To accomplish this, it is sufficient to indicate desired settlement amount in the amount field of capture operation request.

Password Encoding  

If passwords, as well as other fields, contain special characters (#, @, % etc.), the value of the fiels must be URL encoded.

For example, if the password is: 'Pa$$word', the URL encoded version of this password should be: Pa%24%24word.

For more information please read this article.

PGP Encryption  

For clients that do not use a built-in tokenization functionality and would like to process transactions containing raw card data, an additional layer of encryption - PGP - can be used to remain compliant with PCI regulations. In order to use PGP encryption, a public PGP encryption key must be requested from the integration support. Any PGP encryption software can be used.

Sensitive data, such as an account number or user password, can be encrypted with the received public key and submitted as part of API request. To indicate that submitted data is PGP encrypted, its value has to be preceded by tilde sign and asterisk (~*).

For example, sale request, where accountNumber is encrypted, looks like the following one:
https://[server-name]/gates/xurl?requestType=sale&userName=myUsername&password=myP%40ssword&accountId=2001&transactionIndustryType=RE&amount=5000&accountType=R&accountNumber=~*-----BEGIN%20PGP%20MESSAGE-----%0AVersion%3A%20GnuPG%20v2%0A%0AhQEMA1aSPz7%2Bdb1oAQgAtiOW5xuWW%2F9f7IjqDwjUSy3o9BoKr5P3kihA32dHSb9N%0ADE%2FmQo4xXcS6WSvFNYiHoUUmATvwY1UMQX8QShPmOn%2BGc9%2FQuIwIHLbdgywZlMZe%0AlMm%2F%2BO3Pv3RxZStayzUbJC%2BOjR1omBLY2ICA%2FF4x4Uj6eqoIsvyZDVYk7R7YGWL2%0ATMMMNJnJdL9TR81xu1ZTlYpL1gONgvLyp%2F%2BgRP8v1wNChI5swcpoqJZhZIGbDN72%0ARVCQJhEeStW8u0Hh4GeWzBp%2Barpo1pmPgk9kOP3h4T2PIt%2FoMDwjOYDacowMSq81%0Aa6z%2BnRlkttbqnj6UYb4wNEoWdEk1DyM%2BMCG9OgoxbdI%2BATiKnAmdsfEIAhkh0RcT%0AuFceBYWQAUKbaNAAP62ATuq8nxnhKAxIgbmkTb%2BXfGBUWKuRj1B7qb5wwbQ49LY%3D%0A%3DWSed%0A-----END%20PGP%20MESSAGE-----%0A&accountAccessory=1017&customerAccountCode=0000000001&transactionCode=0000000001

For security reasons, PGP keys should be rotated regularly - every two years. Two keys are used during the key rotation process - current key and newly generated key. Key rotation procedure goes as follows:
  1. One month prior to the required rotation time, new private key gets generated by the integration team. A respective public key is derived from the private key and distributed to a client with the request to replace the current public key with the new one.
  2. Both keys, current and new one, can be used during 30-day rotation period. Current key is the primary key, and a new key is the secondary one.
  3. At the end of the rotation period, secondary key replaces the current key, thereby becoming the primary key and completing the rotation. The old primary key cannot be used from this moment.

Provider Response Data  

Generally response message for Sale-Auth, Sale, Credit-Auth or Credit, includes two groups of fields: responseCode (with its respective responseMessage), avsResponseCode, cscResponseCode and providerResponseCode (with its respective providerResponseMessage), providerAvsResponseCodeand, providerCscResponseCode. Fields that are responseCode and responseMessage as well as avsResponseCode and cscResponseCode fields are processor independent responses, while providerResponseCode and providerResponseMessage as well as providerAvsResponseCodeand and providerCscResponseCode fields are the original responses, coming from the underlying processor or bank.

It is recommended to use responseCode with responseMessage, because they are unified across all of the underlying processors or banks, with which processing is possible. Two others fields, providerResponseCode and providerResponseMessage are mostly for convenience and support of legacy systems.

Record ID  

To identify an object within the system, the gateway assigns its own unique identifier when the object is created. In the context of transaction processing, identifiers of previously created objects, such as merchant (accountId, merchantId) and a terminal (terminalId), are submitted as a part of an API request. Identifiers of objects created as a result of the transaction processing, such as an item (itemId) or a transaction itself (transactionId), are returned within an API response.

When transactionId and itemId are returned, depending on the context, values of these fields can be preceded by the prefixes listed in the table below:







Field Prefix Description Example
transactionId without prefix Reference to a merchant-initiated financial transaction that represents a sale or a credit. transactionId=123456
transactionId with * prefix Reference to a merchant-initiated financial transaction that represents a sale or a credit within a submitter’s system. Used for void and capture operations only. transactionId=*123456
transactionId with T prefix Reference to a merchant-initiated tokenization transaction. transactionId=T123456
transactionId with S prefix Reference to a split-out transaction. transactionId=S123456
itemId with I prefix Reference to an item created as a part of the transaction. itemId=I123
itemId with * prefix Reference to an item created as a part of the transaction within a submitter’s system. itemId=*123


Values of these fields can be subsequently used within API requests. A prefix used affects which type of the transaction the operation is applied to. For example, for void API request:
  • If transactionId value without prefix is submitted, specified transaction is voided;
  • If transactionId value with S prefix is submitted, only split-out transaction is voided;
  • If itemId with I prefix is submitted, only specified item in the transaction is voided. Note that the item cannot be voided when an associated transaction was split at transaction level.

Retail Cycle Balance Inquiry  

Merchants have the ability to validate totals within a retail cycle (real-time batch) by calling balanceInquiryCycle operation and comparing the transaction totals between the two systems. It is recommended to do this verification before performing closeCycle operation.

Resource Management  

There are situations when uploading of any additional data associated with a particular transaction is needed. Usually, it is done automatically when a transaction is processed and a corresponding API response is returned. However, in some cases, e.g. when an error has occurred during the uploading process, it needs to be done manually. To upload data to the gateway, upload-resource API call is used.

The following resources are available for submission:
  • a signature that has been provided to verify cardholder’s identity. Signature can be uploaded in either BMP or PNG format using content field. If the signature has been uploaded in BMP format, it gets automatically converted and uploaded to the gateway in PNG format. After upload, the signature can be downloaded using download-resource API call. To learn more about a signature, please review integration notes.
  • an issuer script result. Issuer script is a sequence of tags that is sent from issuing bank to be executed on an EMV card in order to update particular information, block or unblock an application, reset a PIN code or block a card itself. These scripts are usually sent within a response of a sale transaction, which is submitted using a particular EMV card, and are processed after a transaction has been finished. Issuer script result is the result of processing of this script. Some processors may require issuer script result to be sent back to an issuing bank. In such case, it can be easily accessed via the gateway and added to a settlement file. Can be uploaded using scriptResultData field.
  • email of a card or bank account holder for receiving transaction receipts. Can be uploaded using receiptEmail field.

Service Fees  

Quite often, companies that process transactions on behalf of other organizations may require to explicitly indicate that the payment amount includes a certain part that constitutes service fees. For example, when $105 sale is processed, $5 represent service fees that the company submitter wants to withhold when deposits will get remitted to the organization on behalf of which the transaction was done (e.g. organization gets $100 and submitter keeps $5 service fee).

In order to accommodate these needs, Sale operation provides feeAmount field, which should contain the amount of the processing fee that the submitter wants to withhold from remittance. Note: based on merchant configurations, actual processing/interchange fee will be deducted either from the amount remitted to the organization beneficiary or from the service fee amount of the submitter.

For cases, when elaborate convenience fee calculation logic is involved, it's possible to call convenience-fee operation to get the amount of convenience fee to include in a subsequent sale/sale auth call.

Settlement Delay  

There are cases, when the settlement of funds on the day of authorization is undesirable. For example, prior to rendering a service, merchant wants to verify the availability of funds but final settlement should not occur until the service is fully provided. While each card association has its own rules regarding the expiration time of an authorization, it's generally possible for an authorization to exist and not expire for seven consecutive days.

Every transaction is settled on the subsequent settlement by default, which tends to happen, in the majority of cases, on the same business day when authorization occurs.

For cases when it's desirable to delay settlement, it's possible to specify 'settlementDelay' indicating the desired time period to wait (up to six days). After the delay period has passed, if the transaction is confirmed (captured), it's going to be settled; if the transaction is unconfirmed (not captured), it's going to get voided and reversed.

If settlement delay was specified during the initial authorization, but it's desirable for the transaction to get captured at the day when capture operation occurs, it's possible to include 'settlementDelay' in capture request and set its value to zero.

This is going to serve as an indication to the system to settle the transaction as part of the settlement process that follows capture request (usually at the end of the business day). If 'settlementDelay' field is not included in the capture request, transaction will get settled when the delay period expires.

Settlement Group  

The concept of the settlement group is used to accomplish "all or none" settlement behavior for a group of transactions.

During sale or credit process (sale-auth, sale, credit-auth, credit operations), a transaction can be assigned to a settlement group (by indicating settlement group's unique identifier as part of the operation's request message). When settlement process happens (usually at the end of the day), all transactions belonging to a group that contains at least one voided or non-captured transaction will be automatically voided.

The concept is convenient for the cases of split payments or split credits, when more than one transaction is needed to accomplish a specific business goal (e.g. sale with 2 credit cards involved) and it is imperative to assure that either all transactions succeed and settle or all get voided.

Settlement group code can be any string value. It must be the same for all transactions belonging to the "all or none" scenario. More than one group per settlement cycle is possible, but code must be unique for each group. It is highly discouraged to reuse settlement group code over time. A common approach is to use Transaction Code value of the first transaction in a group as a settlement group code. Since transaction code is a unique value for a merchant, settlement group code will not get accidentally reused.

Signature Usage  

During Transaction Processing

There are two main methods of a cardholder's verification during transaction processing:
  • PIN code - cardholder enters a PIN associated with a card via a terminal keypad.
  • Signature - cardholder signs a digital or printed receipt.

In most cases, a PIN code is required when making EMV-transactions, while a signature is required in the following cases:
  • when a payment card is swiped through a terminal;
  • when an payment card requires both a PIN and signature;
  • when an EMV/technical fallback occurs and a card must be swiped.

When a signature is captured electronically (via a touch screen terminal) in a context of a transaction, it gets automatically uploaded to the gateway via the upload-resource API call. Additionally, you can use upload-resource API call if it is necessary to re-upload a signature for a transaction (e.g. when signature upload has failed due to an error) or to upload a signature that was received without using a touch screen terminal.

The submitted signature is returned to a POS within the API response via the signatureContent field.
Signature within the signatureContent field is not returned in the following cases:
  • when a transaction was made with the payment card requiring PIN verification;
  • when a transaction was made with the payment card requiring signature verification, but the signature was provided via tthe terminal without touch screen.

In case you need to download a signature associated with a particular transaction from the gateway, download-resource API call is used.

When a transaction is submitted offline, a signature can be obtained within a callback. To receive the signature via callback, the format field with a respective value has to be included in sale or sale-auth API request, as well as notifyURL field. In this case, the signature is returned via the signatureContent field. See integration notes for more information.

Outside of Transaction Processing

There are situations when a signature should be provided by a cardholder without submitting a transaction, e.g. when a cardholder has to sign a particular agreement. In such case, capture-signature API call can be used to receive a signature. When this API call is submitted, a terminal renders a respective screen requesting a signature (available for touchscreen terminals only). After the signature is submitted, it is cropped by the signature's boundaries, encoded and returned subsequently in the capture-signature API response within the image field.

Note that when the capture-signature API call is used, a provided signature is not saved automatically within the gateway. To upload it to the gateway, use the upload-resource API call.

How to Save Signature

To save the signature image, follow the instructions below:
  1. Decode the signature content via a URL decoder.
  2. Copy the result and paste it into a new TXT file.
  3. Decode the TXT file via a Base64 decoder.
  4. Save the decoded PNG file to your system.

Split Amount Format  

When amount field is used in the API request within a split subrecord, it can take one of two values. By default, the value of the field is assumed to be amount in cents that will be split out of a total amount of the transaction. However, you can also specify a percentage (rate) that you want to be split out of a total amount of the transaction.
  • To specify that the submitted value is an amount, it should be preceded by the prefix A. The amount is submitted as an integer value in cents. If you omit the prefix, the system will assume that the value is amount by default. For example, $10 is submitted as amount=A1000 or amount=1000;
  • To specify that the submitted value is a percentage (rate), it should be preceded by the prefix R . The rate is submitted as an integer value with four decimal places precision (10%=100000, 1%=10000, 0.25%=2500). For example, 10% of a total amount is submitted as amount=R100000.

Stored Credentials  

There can be cases when a payment card is going to be used for recurring/installment transactions, which can be processed either in real-time or as batch files. Some card brands require identification of an original authorization when recurring transactions are processed. The idea of that is when a cardholder was accepting the agreement, an initial transaction was processed either as card-present or with CSC included, and subsequent recurring transactions, which are processed as card-not-present without CSC, are assumed to be a continuation of the initial or previous transaction. This is needed to manage risk and fraud, resulting in fewer chargebacks and an improved cardholder experience.

To process a recurring/installment transaction, follow the steps below:
  1. Submit a processing request file. All transactions submitted within a processing request file are considered to be recurring/installment.
  2. Once the response file is returned, every transaction has the networkTransactionId field value included. This value must be used in every transaction associated with the first one to indicate that a transaction is a continuation of a recurring sequence and follows a recurring/installment transaction that has already been processed by the system before. Note that each networkTransactionId value is associated with a certain sequence of recurring/installment transactions and not with an account number of a cardholder.
  3. Submit the received networkTransactionID field value in the originalNetworkTransactionID field within the subsequent recurring/installment transactions.
  4. If you want to start a new sequence of recurring/installment transactions, you have to submit a new processing request file without the originalNetworkTransactionID field included in the transactions, as described in step 1.
  5. If the first recurring/installment transaction is scheduled for processing in the future, you can reserve the networkTransactionId field value in advance without funds withdrawal from a cardholder. To do this, submit the account-verification API request with the csc or accountData field value included. This transaction will be considered the first in the sequence of recurring/installment transactions. After the transaction is processed, the networkTransactionId field value is received in the account-verification response. This ID can be used in subsequent transactions associated with this recurring sequence, as described above.

In the table below you can see, which fields are required to submit in the request and which are returned in the response when using the stored credentials mechanism:
Transaction Sequence Transaction
Category Type
Transaction Mode Type Network
Transaction ID
Original Network
Transaction ID
Card-present Card-not-present*
Card-On-File/
Cardholder Initiated
Card-On-File/
Merchant Initiated
First transaction (request) x x
First transaction (response) x
Subsequent transactions (request) x x x x
Subsequent transactions (response) x
* Note that the transaction mode type for each subsequent transaction can be either Card-On-File / Cardholder Initiated or Card-On-File / Merchant Initiated.

Subrecord Format  

Subrecord is an entry within a primary record. Usually, the primary record has a list of subrecords. The following subrecords are currently supported within the system:
  • items (for transactions with items; may include a reference to a split schema or a split payment scenario);
  • extraCharges (for lodging and car rental transactions);
  • petroleumItems (for petroleum transactions);
  • distributions (for vendors distributions);
  • splits (for split payments).

The following formatting rules are applied to the fields with subrecords:
1. Each subrecord must be enclosed by brackets.
2. Equal sign (=) is used to separate field’s name and value, semicolon (;) - to separate fields.
3. To submit multiple subrecords, list them one after another.

For example, if the following item information is needed to be submitted:
Item 1:
  • code=001
  • quantity=1
  • description=t-shirt
  • totalAmount=50000
Item 2:
  • code=002
  • quantity=1
  • description=jeans
  • totalAmount=70000,

items field’s value must be formatted as shown below:
items=(code=001;quantity=1;description=t-shirt;totalAmount=50000)(code=002;quantity=1;description=jeans;totalAmount=70000);

If amounts of the items listed above should be split between two or more recipients, items field’s value must be formatted as follows:
items=(code=001;description=t-shirt;quantity=1;totalAmount=50000;splits=(accountId=2011;amount=7000)(accountId=*johnsmith123;amount=2000))(code=002;description=jeans;quantity=1;totalAmount=80000;splits=(accountId=2011;amount=9000)(accountId=*johnsmith123;amount=2000)(accountId=*my+Merchant+Account+code;amount=3000));

Terminal Data Entry  

To define which payment option is used and how payment information is submitted through a terminal, the entryModeType and entryMediumType fields are used. For more information about the available values of these fields, review entryMediumType and entryModeType enumerations.

All available combinations of the entryModeType and entryMediumType field values are shown in the table below.

Manual Swipe/Scan Chip Contactless
Not Present x
Magnetic Card x x x
Chip Card x x x x
Check x x

Terminal ID  

When provisioning terminals in the portal, you have the ability to enter a 3-digit, numerical terminal ID. This terminal ID is passed in all API requests to identify the transaction’s target device. As such, it’s important that these IDs be tracked within your system. If you do not enter a terminal ID, one will be assigned automatically. Each terminal will have a sticker which displays the terminal’s key, a numerical identifier which is comprised of the concatenated account ID and terminal ID. When a terminal arrives at its destination, the recipient should have the ability to register the device within your software, using the terminal ID or key. We recommend that you enter the terminal in your database when you first provision it, making sure to include the terminal ID and the related account ID. This will allow you to associate the terminal with its recipient upon registration.

The terminal ID can take one of two values:
  • Internally assigned identifier, generated by the gateway (for example, 001).
  • Externally assigned submitter’s specific identifier (for example, *021).

Please, note, that when an externally assigned identifier is used, the value must be preceded by an asterisk (*) in a submitted API call.

Terminal Message  

Terminal Message mechanism is used to pass control messages from the TMS system to the terminal within the context of a transaction. It allows to notify (within transaction response) the terminal of the need to execute a particular procedure such as invoke certain function of the TMS. There are certain processes such as terminal software update or parameter update that are running on a regular basis at the scheduled time. However, there are situations when it is necessary to initiate one of such processes sooner than scheduled.

For example, due to an issue an update needs to be performed right away. One way to do this would be to deliver a terminal message in a response of the next transaction that is going to take place. The response messages then are consumed by the terminal and appropriate action takes place.

Terminal message consists of three control functions:
1. exec(operation-name) - used to notify a terminal that particular operation needs to be executed. Usually it means that terminal needs to call a certain operation of the TMS system. Supported operations are listed below:
For example, terminalMessage=exec(get-update);exec(log-state);exec(get-parameters);

2. key(name, value) - implies that terminal needs to replace a particular key with value specified in the parentheses. The key mechanism can be used for various reasons. One of the most common is rotation of the MAC session key, when rotation is necessary as part of the processing. Currently, three keys are available:
  • MAC - session key used for encryption of message authentication code (MAC) data block. Used for Canadian transactions only;
  • PIN - key used for encryption of PIN value associated with customer's credit card;
  • P2PE - key used for point-to-point encryption of EMV and track data.
All of these keys consists of 16 alphanumeric characters: digits and letters from A to F.
For example, terminalMessage=key(mac,0123456789ABCDEF);key(pin,FEDCBA9876543210);key(p2pe,ABCDEF0123456789);

3. message(text) - used to send text messages to a terminal. To divide text in lines, pipe (|) sign is used. Note that a number of available lines on the screen is limited to five. See integration notes for more information. For example, if it is necessary to restart a terminal, the following message should be submitted:
terminalMessage=message(Please restart|the terminal|now!);

Note that within the terminalMessage field any desirable combinations of control functions can be used.

This field has no importance in the context of processing.

Timeout Handling  

There are two common approaches to handle transaction processing from the stand-point of time-outs and network communication problems: optimistic and pessimistic.

In the optimistic approach, the original transaction is processed as a sale (or credit) and thus is automatically assumed as good to settle. If settlement is not desired, a subsequent void has to be issued (prior to settlement).

In the pessimistic approach, the original transaction is processed as a sale-auth (credit-auth) and requires subsequent capture call to confirm this transaction as good to settle. Consequently, if time-out occurs, no capture request is sent and the transaction automatically gets reversed (if it actually happened). Please, note that Implicit Capture mechanism can also be used to capture previously authorized transactions.

Transaction Export  

Merchants, who want to pull their transaction history by means of the API, can use export operation. Caller of the API can specify a certain type of transaction or a combination of transaction types he wants to receive. This can be used as an alternative to callback notifications to get, for example, returns.

To control which type of transaction is necessary, transactionType field is used (follow the link to review possible values for this field). To load a combination of transactions, multiple pipe-delimited values should be specified as a transactionType value. Merchants can use transaction export operation for auditing purposes or if they feel that callbacks logic on their end may have malfunctioned. Note that date range for export cannot exceed a one month period.

From the point of view of their origin, transactions in the system can be of two types:
  • transactions that come from the submitter and their respective responses - sale-auth, sale, credit-auth, refund, decline, blacklist, void;
  • transactions that come from the processor – reversal, chargeback, return, notice.
Depending on the type of the transaction, transactionDate and settlementDate may vary or be the same.

For transactions which come from the submitter, transactionDate is the date when the transaction was processed (authorized) and settlementDate is the date when the transaction was settled, if it was successfully settled. For direct debit transactions, transactionDate and settlementDate will always be the same.

For transactions which come from the processor, transactionDate and settlementDate are same, and they represent the date when the transaction was loaded into the system (from the processor).

Please note, that information about returns, chargebacks and reversals is updated only once per day.

Transaction Levels  

While most transactions require standardized set of fields (such as card number, expiration date, etc), there are also types of transactions, that require higher level of detailing. Additional detail level is coming by context of the transaction and is designed to simplify credit card processing in the specific situations. Aside from the standard transaction level, the following ones are available:
  • Level II - transactions with commercial (corporate) payment cards used by corporates (API fields associated with taxes are required to be submitted);
  • Level III - transactions with government or corporate payment cards used by corporations and government (detailed information of every item associated with a transaction is required to be submitted).

Level II transactions are used to simplify business-to-business (B2B) payment processing with lower interchange rates applied. The system will process transactions as level II, if the following fields are included in the API call:
  • orderCode
  • shippingAmount
  • dutyAmount
  • taxAmount
  • taxRate
  • taxIndicator
  • customerAccountTaxId

Level III transactions are used to simplify payment processing for business-to-business-heavy industry and government cards with lower interchange rates applied. The system will process transactions as level III, if the following fields are included in the API call:
  • shippingOriginZipCode
  • discountAmount
  • taxInvoiceCode
  • localTaxAmount
  • localTaxIndicator
  • nationalTaxAmount
  • nationalTaxIndicator
  • orderDate
  • commodityCode
  • items
  • itemCount

Level I and II transactions can be run through a standard terminal or POS software. Level III transactions require special software to be installed for transferring the additional information required to qualify the transaction.

Transaction Origin Code  

TransactionOriginCode is used to track the origin of the transaction. Each integrator is assigned to their respective code, that they should include, when transaction is submitted. If an integrator has more than one place within application from which the request can be originated to the gateway, the integrator can append additional value after the assigned transaction origin code (using : as separator).

For example, an integrator (SuperSoft) has two places in its software that send transactions to the gateway. One of them is originated by POS (point of sale), the other one is originated by back-end billing process. Transaction origin codes for these transactions should look similar to this:

SuperSoft:pos
SuperSoft:recurring

The maximum length of the transaction origin code must not exceed 35 characters (including assigned value and separator).

Transit Fields  

Transit fields are the fields that are passed to an underlying processing platform if it supports such functionality. They are used to enable or disable whatever behavior is associated with the field. Please note that such fields do not trigger any functionality within the gateway itself. If you are not certain whether the field has any impact based on your processing configuration, please confirm it with the gateway support.

User Message Overriding Mechanism  

User messages specified in the Error Codes section can be overridden using the developer message mechanism. This mechanism can be used only within the API (including hosted payment pages).

For the real-time API, an integrator can replace default user messages with custom ones using javascript in their own application. If you need to replace default user messages with custom ones on HPP, the gateway provides the architecture described in the Processing Management guide.

Warning Code  

Warning code is a letter code that indicates additional conditions, which have occurred during transaction processing. However, such conditions are not dramatic enough to affect processing one way or another. Warning code can be received as a part of the API response, within warningCode field. At this point, it is preliminary used to notify a user about an unsuccessful reversal of a transaction or any errors related to a descriptor.

There are three cases when a transaction should be reversed after successful authorization because certain business condition does not match:
  • Submitter does not support partial authorization, therefore, isPartialAuthorization flag is set to false. The expected behavior is that in case when partial approval is received, the transaction should be reversed and the submitter should receive a decline and not a partial approval;
  • Post-processing filter gets triggered and requires a reversal of the transaction. For example, post-processing filter requires reversal of any transactions where AVS codes have not matched;
  • External fraud protection tool similar to post-processing filter requires reversal of the transaction.

In these cases the system executes void. If void has been approved, A03/A06: Void Posted response is received. If void has been declined, A11: Approval (Reversal failed) message, as well as a respective warning code is returned within a response.

Follow this link to learn more about possible warning codes.


Concepts


Tokenization (Concepts)  

General overview of the tokenization concept can be found here.

UniCharge provides a simple and convenient tokenization mechanism for merchants that deal with recurring payments and want to avoid storage of customer’s payment information (credit card and bank account numbers) within their own system. When a merchant uses any given payment card or bank account for the first time (as part of sale-auth, sale, credit-auth or credit operation), UniCharge will generate an identification number (token) associated with this payment information. While being tokenized, bank account numbers are verified by length, while payment card numbers are additionally verified by Luhn algorithm correspondence (checksum). Generated token can be later removed from the system either manually - via untokenization API call if this feature is supported by tokenization provider and enabled in processing settings, or via scripts run by the gateway support team upon request.

There are two ways to use tokenization, and if errors occur in this process, different processing codes are returned by the gateway:
  • in case when a card number is replaced by token, and the tokenized card number is stored without preliminary account verification, P-codes are returned by the gateway. It’s a group of processing codes applied only for tokenized transactions declines;
  • in case when account verification is carried out as part of the tokenization process, and tokenization may be declined by the processor due to invalid expiration date, AVS information, CSC, etc, D-codes are returned by the gateway. It’s a standard group of processing codes applied for payment card transactions declines.

There are two approaches to implement tokenization:
  • pure tokenization. See the integration notes;
  • profiling. See the integration notes.

Pure tokenization  

In this case account number is replaced with a token, however, all of the other fields (routing number, expiration date, address information, etc.) must be sent within each request.

If in the future a merchant wants to perform another operation (e.g. another sale) using the same credit card or bank account, it is sufficient to include into the request the value of the previously generated token (in the token field) as an alternative to an account number. Only one of the following values is necessary in a request: account number / account data / token. Respective expiration dates and routing numbers must be supplied every time a token is used; the value has to be specified in accountAccessory field.

Profiling  

In this case, a token is associated with an internal account profile, which in addition to account number can contain other account information (for example, holder name, expiration date, routing number, address information).

When a transaction request is submitted, fields from the profile can be automatically used if they were not specified as part of the request. The disadvantage of the profiling approach is that profiles have to be updated if the customers’ information is changed,
in particular, the following fields:
  • accountAccessory
  • holderName
  • isOrganization
  • street
  • city
  • state
  • zipCode
  • countryCode

Token Structure (Extended)  

As well as simple token structure, the extended structure enables integrators to easily derive information needed for reporting or system maintenance from the token itself.

For example, XVC01S0000000099990000014426594111001111.


# Name Type Description
1 Token Format String(1) Identifier of the extended format (always X).
2 Account Type Enum(2) Type of account. See possible values for more information.
3 Sequence Number String(2) For bank accounts only.
Sequence number assoсiated with the underline account number for cases when account number is not unique. For example, the same account number is used in different banks.
4 Tokenization Origin Enum(1) Identifies the system, underlines system, that generates the stock. See possible values for more information.
5 Bank Identifier String(7) Identifier of a bank that issued the credit card or that holds a bank account.
6 Reserved for Future Use String(1)
7 Account Number String(16) Tokenized account number.
8 First Four Digits String(6) The first four digits of credit card or bank account number (the last two digits of this value are reserved).
9 Last Four Digits String(4) The last four digits of credit card number or bank account number.

Token Structure (Simple)  

A token generated by the gateway is comprised of 3 logical parts:
  • two-letter account type (see possible values for more information);
  • tokenized account number;
  • the last 4 digits of the actual account number.

For example, a card number 4111111111111111 will be tokenized as VC84632147254611111111, where:
  • VC is the Visa account type;
  • 8463214725461111 is a tokenized account number;
  • 1111 are the last 4 digits of the actual card number.

This structure enables integrators to easily derive information needed for reporting or system maintenance from the token itself.

Convenience Fee  

Convenience fee is a transaction that represents a charge in addition to the original transaction amount for a convenience usage service for credit card payments, which in most cases is a surcharge, that generally is kept by the service provider that facilitates the payment (payment gateway, processor, etc).

Processing of a sale with convenience fee occurs in two phases:
  1. Calculating of convenience fee amount;
  2. Submitting of sale/sale-auth transaction with retrieved convenience fee value.

The process of obtaining and submitting convenience fee value via API occurs in the following way:
1. The respective request for convenience-fee calculation is submitted:
requestType=convenience-fee&userName=myUsername&password=myPassword&accountId=2001&transactionIndustryType=RE&accountType=R&accountNumber=4111111111111111&accountAccessory=1017&amount=5000
2. Once the response is retrieved, feeAmount value needs to be extracted from the response:
responseType=convenience-fee&accountId=2001&responseCode=A01&responseMessage=Approved&feeAmount=500&transactionId=603559&cycleCode=8765
3. Sale and sale-auth transactions with convenience fee are available only if a cardholder's has approved the transaction to be made.
To process a sale/sale-auth transaction with convenience fee included, feeAmount value is added additionally to the total amount of the transaction in the respective request:
requestType=sale&userName=myUsername&password=myPassword&accountId=2001&terminalId=001&amount=5000&accountType=R&transactionIndustryType=RE&holderType=P&holderName=John+Smith&accountNumber=4111111111111111&accountAccessory=1017&street=12+Main+St&city=Denver&state=CO&zipCode=80110&customerAccountCode=0000000001&transactionCode=0000000001&feeAmount=500

When convenience-fee is involved, the sale through HPP becomes a two-phase process:
  • calculation of the convenience-fee - initially, the HPP is rendered to capture all the necessary payment information. When the HPP is processed, the convenience-fee operation is called and the convenience fee itself is calculated.
  • processing of the transaction - the HPP is re-rendered with the information already entered by the customer (in the previous phase) and with the convenience-fee, visible as a separate field, and, also, added to the total amount of the transaction. At this point, a card holder has an option of either accepting the payment with either convenience-fee and completing the sale, or canceling the entire transaction.

Hosted Payment Page (HPP)  

General Information

General overview of the Hosted Payment Page concept can be found here.

According to PCI requirements, it is forbidden to store any card data. If non-tokenized card data is stored within the system or any sensitive data goes through the software system, the company goes under PCI scope and subsequent PCI audit. To avoid having cardholder's data uploaded to the software system, Hosted Payment Page mechanism can be used. When HPP is used, all sensitive data is collected through the page and subsequently converted into a token that can be safely used by the software system for processing. Since the page is hosted by gateway service provider, the software application that uses an HPP remains out of scope.

UniCharge provides a simple and secure mechanism for capturing cardholder’s information using a secure HPP (web page to capture account holder’s information, including credit or debit card numbers). Using HPP, the submitter’s application doesn’t touch sensitive account holder's data, and thus remains outside of the PCI scope. The common fields that HPP captures are card number, expiration date, CSC code and optionally address information. HPP seamlessly integrates into the Real-Time HTTPs API and accommodates all of the parameters supported by it.

HPP-related fields

HPP mechanism makes use of the following parameters that can be provided as part of the sale, sale-auth, credit or tokenization API requests.
  • notifyURL – the presence of this parameter triggers the appearance of HPP. If definite URL is specified within the notifyURL field, the result of the transaction is delivered to this URL. For example, the notifyURL page with the transaction result may look as shown on the screenshot.
  • postNotifyURL – URL, which is used in conjunction with notifyURL. The result of the transaction is delivered to this URL after the callback with the same information is successfully delivered to notifyURL. The format of the callback to this URL is the same as the one used for notifyURL. You can use this parameter if you need to receive a callback within two different systems.
  • cancelURL – URL to which a user gets redirected if he or she decides to terminate transaction without completing.
  • returnURL – URL to which a user gets redirected after a transaction is successfully processed. If returnURLPolicy is set as page, a confirmation page is rendered with specified returnURL. If returnURLPolicy is set as redirect, a user is redirected to the specified returnURL bypassing confirmation page.
  • styleURL – when dynamic styles are needed, URL of a CSS stylesheet that should be dynamically included in the HPP.
  • returnURLPolicy – defines how returnURL is used when a transaction is completed.

There are situations when a notify URL fails to reach a merchant system. In such cases, it does not try to reach it again. The information about a failed attempt can be retrieved within the system logs only. However, an information about failed transactions can still be retrieved traditionally via the user interface or a transaction export report.

Additionally, the HPP mechanism allows a user to control the source of notifyURL parameter. It can be pulled from the value specified either within an API request or on the user interface. On the UI, there are two URLs that are stored within the merchant profile in the system and can be used for callback purposes. If notifyURL value should be taken from the API request, it is submitted as it is. If the value of notifyURL should be taken from one of URLs specified in the processing settings of the merchant, the following values preceded by tilde (~) should be submitted: offline-url – to submit URL used for offline transactions, or chargeback-url – to submit URL used for returns or chargebacks receiving, e.g.: notifyURL=~offline-url or notifyURL=~chargeback-url.

When cancelURL is used, the HPP is going to have the cancellation option available (cancel transaction button). By default, if a user clicks on the cancel button, he or she will be redirected to the URL, specified within the cancelURL field. Additionally, if the keyword page is specified as cancelURL field value, then if the customer clicks on the cancel button, he or she will be redirected to the confirmation page (results.html), which will indicate that the transaction was cancelled.

HPP Rendering

There are two ways in which an HPP can be rendered:
1) By generating a payment page via an API call. The most typical way, in which a transaction is processed, is as follows:
  • a user initiates a sale, sale-auth, credit or tokenization transaction;
  • a software platform submits an API request specifying the value of the notifyURL field to the gateway. This field triggers rendering of a hosted payment page. Additionally, returnURL and cancelURL can be submitted along with the notifyURL field;
  • the gateway renders a payment page and returns it to the software platform, which forwards it to the user;
  • a user enters secure information and clicks "Submit" button. The transaction gets processed and the result is posted to the URL specified in the notifyURL field;
  • a confirmation page with “Continue” button is rendered. When clicking on this button, the user gets redirected to the URL specified in the returnURL field;
  • if during the process the cardholder clicks "Cancel" button, further transaction processing gets canceled and the user is redirected to the URL specified in the cancelURL field.
To learn how an HPP is rendered for this scenario, review this diagram.
2) By generating a payment page via a URL. It is used when a payment page has to be rendered solely by the gateway bypassing a software platform:
  • a user initiates a sale, sale-auth, credit or tokenization transaction;
  • a software platform submits an API request specifying the values of the notifyURL and processingMode fields to the gateway. The processingMode has to be set as queue;
  • the gateway generates an API response containing a particular requestId and returns it to the software platform;
  • after receiving a request ID, the software platform forms the URL and passes it to a user. The URL is formed as follows: https://[server-name]/gates/redirects/r671684f1-5c73-4c3d-96ea-0bee3190497a, where r671684f1-5c73-4c3d-96ea-0bee3190497a is a requestId that was returned within the API response;
  • the user receives the URL that is available for 10 minutes and follows it to access the hosted payment page;
  • after the HPP has been rendered, the user finishes the transaction following the steps described above.

The time during which the page is available to the user can be extended in two cases:
1) If the authenticate API request is sent with the requestId received in the previous steps, the time during which the page is available can be extended by 15 minutes up to three times.
Authenticate API request submitted for the fourth time will return an error with the following code/message: L01 (Username or password is invalid).
2) If the invalid card number is submitted via HPP, you should press “OK” button inside the Reauthenticate pop-up window to extend the session.

To learn how an HPP is rendered for this scenario, review this diagram.

Note that if GET request is used in an initial call to render HPP, it is advised to use a temporary password instead of the original one, to prevent caching of a password by the browser. In such cases, a temporary password can be acquired by using authentication request. Please, see the integration notes for more information.

HPP Customization

HPP can be configured by each merchant to reflect look and feel of its website or application and accommodate its specific business needs. There are five resources available for customization: paypage_card.html, tokenization_card.html, paypage_account.html, tokenization_account.html, result.html. Pages with _card are used for card processing and pages with _account are used for processing of direct debit transactions.
  • paypage_card.html - used for sale, sale-auth and credit operations done with payment cards.
  • tokenization_card.html - used for tokenization operations done with payment cards.
  • paypage_account.html - used for sale, sale-auth and credit operations done with bank accounts.
  • tokenization_account.html - used for tokenization operations done with bank accounts.
  • result.html – a page shown to a user once an operation is successfully completed.

Note that these files have to be saved as UTF-8 with the content encoded in UTF-8 within the file as well.

To include custom scripts in any of the HTML files above, separate JS files have to be used. These scripts must be placed in the /resources folder located in a root folder of a corresponding merchant/account. This should be done via the user interface. References to the external custom scripts have to be specified as follows:
<script language="JavaScript" src="/resources/hpp/[merchant-id]/[script-name]"/>

For example:
<script language="JavaScript" src="/resources/hpp/2000/paypage_card.js"/>

Customized hosted payment pages can look similar to this one or this one.

Using HPP with MSR (magnetic stripe reader)  

HPP can handle both card-present and card-not-present transactions. When a card-present transaction is desired, regular or encrypting MSR can be used.

HPP supports two modes of card-present transactions handling:
  • Automatic mode. After the page is loaded, a cursor must be placed in the account number field (setting focus to the field). At this point, the card can be swiped (the system will automatically differentiate between account number, keyed into the page itself, swiped account data or manually keyed card data using MSR). Once the swipe is made and account data from the card is successfully read, HPP is going to automatically recognize the end of the account data, parse it and populate the values into the appropriated fields.
  • Manual mode. After the page is loaded, a user must press «Scan» button on the HPP to enable capture of the information from the MSR. Once pressed, the label of the «Scan» button is changed to «Stop» and the reading process begins. The card can be swiped at that time (the system will automatically differentiate between swiped account data and card data, manually keyed using MSR). User can press «Stop» button to pause the reading process (for example, if some other input from the keyboard is required). Once the swipe is made and account data from the card is successfully read, the reading process paused automatically and the label of the «Stop» button is changed back to «Scan». No further input from the MSR will be captured until «Scan» button is pressed again.

Please note, that MSR must be configured to work in Keyboard Emulation mode (normally enhanced by default). To check if Keyboard Emulation mode is enabled, please, open Notepad and make a swipe.

For additional information on configuration of MSR ID TECH SecureKey M series please see ID TECH Configuration Guide.

Proxynization API  

Overview

Traditionally, to take an application out of PCI scope, payment pages are used. However, there are cases when use of the payment pages is feasible or not desirable (for example, if the application, which needs to accept credit cards, uses AJAX-based interface or wants to utilize its own payment form). For such cases, an alternative JavaScript-based solution is available.

Proxynization API is the JavaScript library that can be embedded in an existing locally hosted payment page; proper usage of proxynization API keeps the payment page and its underlying application out of PCI scope.

The following steps should be taken to utilize proxynization functionality:
  • Download api.proxynization.js script and include it in your HTML page. Note that no additional settings including the user interface or server configuration are needed;
  • Use authentication request to receive a temporary password, which is valid for 10 minutes;
  • Submit the proxynization request with previously received temporary password to get a proxy number;
  • Use received proxy number for subsequent sale, credit and tokenization requests to the gateway.
See Workflow section below for more information.

Security constraint

JavaScript by its nature has a security limitation. Since it is client-side language, its source code is entirely accessible. Therefore, it is impossible to secure passwords within JavaScript. Consequently, no JavaScript call can be used to invoke a gateway operation (such as sale or tokenization request) because it is impossible to properly authenticate the caller.

To keep an application out of scope, JavaScript is used to generate a temporary token (proxy), which functions as a replacement for the actual account number. This proxy can be subsequently used in the server-side call to the gateway, utilizing appropriate credentials (which are secured, because everything happens at the server side).

In order to secure the script, temporary password key can be generated using server-side call and should then be assigned to proxynization API object to enable processing.

Workflow

1. Download api.proxynization.js script.
You can either download a default script and customize it using data associated with your server or contact gateway support to request a script that has already been adjusted to your needs.

If you have your own script, skip this step and proceed to step 2.

2. Include api.proxynization.js.
Copy the following lines and paste them to your HTML page. This will enable the proxynization functionality within your application.
 
<script type =" text/javascript" src="https://[server-name]/services/api.proxynization.js"></ script>
 

3. Implement the callback function.
Callback function is going to be invoked once proxynization response is returned from the gateway. The gateway generates a function call, which invokes the pre-defined callback function and passes the proxynization results into it. Post-proxynization logic (such as submission of the form) should be included in the callback function.

The function must declare three parameters: responseCode, responseMessage and proxyNumber:
  • responseCode - gateway generated response code. Possible values are listed in the table.
  • responseMessage - gateway generated response message, associated with the responseCode value. Possible values are listed in the table.
  • proxyNumber - gateway generated temporary proxy number.

Example of callback function is provided below:
 
function clientCallback(responseCode, responseMessage, proxyNumber){
	if(responseCode == "A01"){
		document.getElementById('accountNumber').value = proxyNumber;
		paymentForm.submit();
	} else{
		alert(responseMessage);
		return false;	}}
 


4. Implement the authentication (see integration notes) logic.
Obtain temporary password from the gateway and assign it to the ProxynizationAPI object. To obtain the temporary password, submit authentication request, using your credentials:
https://[server-name]/gates/xurl?requestType=authentication&userName=*****&password=*****&contextType=proxynization

Example of the server-side code is provided below:
 
ProxynizationAPI.password = '<?php echo (getPass()); ?>';
 

Example of the final JavaScript code is provided below:
 
(ProxynizationAPI.password = '7e850d1d-0f94-4281-92f9-2c2c8bc8f70e';) 
 

Note that temporary password (such as 7e850d1d-0f94-4281-92f9-2c2c8bc8f70e) is dynamically obtained from the gateway every time when the page is refreshed. It is valid for 10 minutes and can be used only once.

5. Implement the proxynization call.
Proxy number of the card can be retrieved in either of two ways:

1) Payment form implementation.
For this purpose, implement the payment form and insert a proxynization call within form's submit action.
process() function takes two parameters:
  • The first parameter can either be the value of account number, or it can be ID of the component, from which the value can be obtained. If the value of the parameter starts with a hashtag (#) symbol, the first parameter is assumed to be the ID of the component. If a hashtag is not present, the first parameter is assumed to be an account number;
  • The second parameter is the name of the callback function (previously implemented, see step 2), that will be called when proxynization call is completed.

Example of the proxynization call is provided below:
 
<input type="button" onClick=
"ProxynizationAPI.process('#accountNumber','clientCallback');"/>
 

2) Proxynization API call submission.
For this purpose, submit the proxynization API call with the temporary password obtained in step 4:
https://[server-name]/services/proxynization?accountNumber=4111111111111111&userName=myUsername&password=7e850d1d-0f94-4281-92f9-2c2c8bc8f70e&contextType=proxynization

Proxynization call will return the proxy number of the card.
responseCode= A01, responseMessage=Approved,
accountNumber=09ae55d5-8428-4274-ace7-21bcdd704390


How to use received proxy number

Proxynization call is used to retrieve proxy number of the card. This proxy number is valid for 10 minutes and can be used subsequently for sale, credit and tokenization requests to the gateway. See the following link to review an example of the sale request with proxy number. There are no limits for the number of times that the proxy value can be used within 10 minutes, and it can be used even if previous transaction attempts failed.

The proxy value should be submitted within the accountNumber field. To indicate that the proxy number is specified within the accountNumber field, its value should be preceded by an asterisk (*).

Split Payments  

Split payments mechanism allows merchants to split a fixed amount or a percentage of the payments between up to 9 different third parties (10 with the original merchant included).

Split scenario should be specified within an original transaction. There are 2 possible methods to create a split payment on a transaction:
  • to embed the rules directly into the transaction via the splits parameter, which is allowed to be used in real-time API transactions only;
  • to use predefined rules called a split schema, which is a template with a set of predefined split payouts. The template is primarily used in situations when the same split rules are repeatedly used or batch processing is required; a split schema should be created in advance.

Directly embedding the split rules within a transaction allows the split rules to be customized for each payment at both the total transaction or specific items within a transaction level. In order to create a split transaction, the splits field should be included in the sale API call. The splits field is formatted as follows:
splits=(accountID=*affiliate001;amount=100),
where
  • accountID is either internal or external identifier of the affiliate (see Reference Field Type for more information). The submitted value can be either account ID/code or merchant ID/code. If merchantId or merchantCode value is submitted, the system will automatically use the first account under this merchant for further transaction processing.
  • amount is the amount to be transferred to this affiliate The amount field can either be a fixed amount or a percentage. See integration notes for more information about amount field.

For cases when multiple items are included in a single transaction, you can apply either the split scenario to the overall transaction or a unique split scenario to each of the items within the transaction. The items field with splits subrecord included can be used to apply different split rules to each item in a single transaction. An item plays either an informational or functional role within the transaction request. When an item plays an informational role, the transaction can include one or more items and the split payment scenario is applied to the transaction as a whole, the total of all the items in the sale transaction. When an item plays a functional role, the transaction can include one or more items and each item specified in the transaction has its own split payment scenario applied to it.