Terminals APIs

Integration Notes

Concepts


Integration Notes

Capture, Void and Refund Operation  

Capture

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

Contactless Mode  

EMV cards can be processed using both ICC (integrated card circuit) and contactless technology. When a card is processed via ICC, it is physically inserted into a terminal. In the second case, it is processed by a tap.

When both ICC and contactless technologies are available in the context of a transaction and supported by a terminal and a card, the following issue may arise: card data can be read by a contactless antenna, even when ICC transaction is intended to be made. This happens due to the close placement of an ICC-reader to the reception zone of a contactless card reader. To avoid such situations, when a transaction is processed and both ICC and contactless modes are available to a card holder, the system supports a special mechanism that controls whether the contactless mode is enabled or not. When a cardholder wants to process a transaction as contactless, the respective mode can be activated by pressing 0 button on a terminal keypad while running an operation. In this mode, built-in contactless antenna gets activated and reads card data once a payment card is brought into antenna zone. To deactivate contactless mode, 0 button has to be pressed once again.

Note that if terminal entry mode is submitted within API request as contactless or as contactless and manual, the contactless mode will be activated on a terminal automatically.

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 within an external system that submits the transaction for processing.
transactionInternalCode* Unique internal identifier of the transaction within an external system that submits the transaction for processing. Can be used as a supplement to a transactionCode.
Customer customerAccountCode Identifier of a customer within the submitter’s system that submits the transaction for processing.
customerAccountInternalCode* Unique internal identifier of a customer within the submitter’s system that submits the transaction for processing. Can be used as a supplement to a customerAccountCode.
Ticket ticketNumber** Identifier of a ticket assigned by a POS system.
ticketId** Identifier of a ticket generated by a terminal.
Item itemNumber** Identifier of an item assigned by a POS system.
itemId** Identifier of an item generated by a terminal.


*In some cases, the submitting system is going to have two different identifiers for the 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.

**Fields ticketNumber/ticketId and itemNumber/itemId can be used subsequently as a reference in the operations designed to update tickets (close-ticket) and update items (update-item, remove-item).

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]

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

EMV terminal programming  

Some processors require certain non-standard tags to be included in the EMV card data. Therefore, special care must be taken to program the terminal to generate these tags as part of the request.
Below you can find detailed information about the process.

TSYS Sierra

For processing with TSYS Sierra, both 9F1E and DF79 tags must be programmed on the terminal along with EMV tags. All tag information must be submitted to the processor in hex format. Prior to being sent to the processor, data from the 9F1E tag is substituted in the DF78 tag. DF78 and DF79 tags from the TSYS Sierra specification are as follows:

Tag Name Description
DF79 Kernel Version Number The version number of the kernel used to process the chip data in the transaction.
DF78 Device Serial Number The manufacturer's unique serial number of the device that interacts with the chip card.

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.

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

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.

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 made and a full transaction amount is not available on the payment card, the gateway 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.

To define how partial authorization is handled, the partialAuthorizationPolicy field is submitted in the API request. The following partial authorization policies are available:





Field Value Description
partialAuthorizationPolicy=N
Partial authorization is disabled. 		When a transaction is partially authorized by a processor, the gateway reverses processor's authorization and returns the D03 (Insufficient Funds) decline code to the submitter.
partialAuthorizationPolicy=T
Partial authorization is performed by a terminal. 		For example, $150 transaction is submitted, and only $140 is available on a payment card. For partialAuthorizationPolicy set as T, both approved and remaining transaction amounts appear on a terminal screen when the transaction is processed. After that, the cardholder is prompted to pay the remaining amount in cash/check or using another payment card. Note that if the terminal splits the payment, the splitTransactionCount and splitTransactionSequenceNumber fields are returned in the response to indicate a total number of the transactions and a sequential number of the transaction. See integration notes for more information.
partialAuthorizationPolicy=P
Partial authorization is performed by a POS. 		For example, $150 transaction is submitted, and only $140 is available on a payment card. For partialAuthorizationPolicy set as P, the A05 (Partially Approved) response code is returned in the API response when the transaction is processed. The remaining part of the transaction amount (for transactions with or without items) can be paid either in cash/check or with a different payment card. See details below the table.


In case when partial authorization is performed by a POS (partialAuthorizationPolicy = P), the following options are available for the second part of the transaction to be paid:
  • if the cardholder pays in cash/check, the POS expects the terminal to provide the information about the partially approved amount ($140) to. After the information is received, the POS submits the sale-info API call to the terminal with the information about the remaining amount paid in cash ($10);
  • if the cardholder pays with another payment card, the POS receives partial approval message from the terminal ($140) and submits a new transaction for the remaining amount ($10).

If the transaction was made with a ticket, the terminal prints out a single check for the total amount ($150). After that, the ticket gets closed.

If the transaction was made without a ticket, the terminal prints out two separate checks:
  • one for the partially approved amount with the corresponding response code/message A05 (Partially Approved);
  • one for the remaining amount paid either in cash/check or with another payment card.

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.

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), providerAvsResponseCode, 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 providerAvsResponseCode 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.

Receipt Requirements  

EMV processing imposes certain receipt requirements. Specific fields that are the part of the transactions must be visible on a receipt. For approved transactions, it is recommended to be included on the receipt to aid in dispute resolution. For declined transactions, this information is mandated by the processors for tracing purposes. If you want to create receipts as a part of your application, please be sure to follow the guidelines below.

Fields that are recommended to be present on a receipt


The following fields are not required but recommended to be present on a receipt of any transaction:
  • Merchant Name
  • Merchant Address
  • Merchant Phone is displayed in ХХХ-ХХХ-ХХХХ format
  • Merchant ID
  • Terminal ID
  • Invoice number in POS system
  • Transaction Date

EMV Receipt Requirements


The following fields are required to be present on all EMV transactions receipts:
  • Transaction Type – Sale or Credit.
  • Application Name - a chip card application name (i.e. Visa, MasterCard, etc.) used to process the EMV transaction.
  • Total Amount – corresponds to the amount field.
  • Currency indicator – corresponds to the currencyCode field.
  • Account Number - corresponds to the accountNumberMasked field.
  • Card Entry Method – сan be derived from the combination of entryModeType and entryMediumType fields.
  • Approval Number - corresponds to the approvalCode field.
  • Transaction Id - corresponds to the transactionId field.
  • Verification Method – Signature, PIN or PIN Bypassed (optional, present for approved transactions).
  • Mode - corresponds to the processingMode field (online or offline).
  • PNN - corresponds to the paymentNetworkName field.
  • Specific EMV tags (see table below).

A receipt can be obtained in two ways:
  • if you are using the standard terminal solution that comes with the gateway, you can print receipt on your terminal. See integration notes to check whether your terminal supports receipt printing or not.
  • if you are using your own terminal solution or terminals that do not support receipt printing, you can obtain a receipt by e-mail. These receipts can also be downloaded in the gateway.
  • if you are using your own application for receipt printing, please stick rigidly to the guidelines.

For Sale and Credit transactions, PNN and Account Type fields take the default value of Interac in cases when the value of transaction ID is returned in stanValue field in transaction response.

Receipt examples are listed in the table below:





















Transaction Type Merchant Copy Customer Copy Email Copy
EMV sale transaction (approved) Example Example Example Example*
EMV sale with tips (approved) Example Example
EMV sale with items (approved) Example Example
EMV sale with fee included (approved) Example Example
Contactless sale transaction (approved) Example Example
Credit transaction (approved) Example Example
Refund transaction (approved) Example Example
EMV sale transaction (declined) Example Example
Split transaction (declined) Example Example
Split transaction with items
paid with two different cards (approved) 		Example Example
Split transaction with items
paid with card and cash (approved) 		Example Example
Split transaction with items (declined) Example Example
Split transaction
paid with two different cards (approved) 		Example
Example 		Example
Example
Split transaction
paid with card and cash (approved) 		Example
Example 		Example
Example


* for Interac card only


Tags To Be Included in a Receipt


EMV transaction fields listed below must be present on all online transactions.




Tag Tag Name Description
Mode Processig Mode (online or offline) (corresponds to the field value processingMode)
PNN Payment Network Name (corresponds to the field value paymentNetworkName)
APP Application Name for a chip card, which is used for EMV transactions
4F AID Application Identifier
95 TVR Terminal Verification Results
9F10 IAD Issuer Application Data
9B TSI Transaction Status Indicator
8A ARC Application Response Code

Usually these tags are displayed on a receipt one tag per line listing a tag name followed by colon (":") followed by the value of the tag.
To simplify the process for integrators, there is a field in the Sale response - receiptTagData - that will contain all of the tags that need to be rendered on a receipt in the order in which they need to appear. Two formats of the field are supported:

1) [tag1]:[tag-value1];[tag2]:[tag-value2];[tag3]:[tag-value3];[tag4]:[tag-value4];[tag5]:[tag-value5];[tag6]:[tag-value6].
2) [tag1]–[tag -name1]:[tag-value1];[tag2]–[tag-name2]:[tag-value2];[tag3]–[tag-name3]:[tag-value3];[tag4]–[tag-name4]:[tag-value4];[tag5]–[tag-name5]:[tag-value5];[tag6]–[tag-name6]:[tag-value6].

So, for example, 4F:A0000000041010;95:0000008000;9F10: 0110A04009240000000000000000000000FF;9B:;91:B2C567CDE15E4C290012;8A:01

or 4F-AID:A0000000041010;95-TVR:0000008000;9F10-IAD:0110A04009240000000000000000000000FF;9B-TSI:;91:B2C567CDE15E4C290012;8A-ARC:01 will be rendered as follows:

receiptTagData=
Mode: Online;
PNN:Visa Credit;
APP:VISA CREDIT;
AID:A0000000041010;
TVR:0000008000;
IAD:0110A04009240000000000000000000000FF;
TSI:;
91: B2C567CDE15E4C290012;
ARC:01

The Mode,PNN,APP fields are formed at the terminal.

Please, be advised that most of the transactions will always have pointed values in the receipt tag data field. In case of EMV offline declines, larger set of tags will be included. For EMV offline decline transactions tags from Tag columns are used for receiptTagData (started from 8.1 release)

Tag Tag Name Description
5F2A Tag 5F2A Transaction Currency Code
5F34 Tag 5F34 PAN Sequence Number (Blank if not present)
82 Tag 82 Application Interchange Profile
95 Tag 95 Terminal Verification Results
9A Tag 9A Transaction Date
9C Tag 9C Transaction Time
9F02 Tag 9F02 Amount Authorized (Printed with decimal point)
9F03 Tag 9F03 Other Amount (Printed with decimal point)
9F07 Tag 9F07 Application Usage Control
9F0D Tag 9F0D Issuer Action Code – Default
9F0E Tag 9F0E Issuer Action Code – Denial
9F0F Tag 9F0F Issuer Action Code – Online
9F12 Tag 9F12 Application Preferred Name (Blank if in unprintable format)
9F1A Tag 9F1A Terminal Country Code
9F26 Tag 9F26 Application Cryptogram
9F27 Tag 9F27 Cryptogram Information Data
9F34 Tag 9F34 CVM Results
9F36 Tag 9F36 Application Transaction Data
9F37 Tag 9F37 Unpredictable Number

RSA Encryption  

There are situations, when HTTPS protocol is implemented with self-signed certificates. This might cause some issues if the consuming system can’t mark the self-signed certificate as trusted. In these cases, HTTP protocol can be used to transfer the data instead. In order to secure sensitive data while using HTTP protocol, it can be encrypted using an RSA key. The message format remains the same for both HTTP and HTTPS protocol, but all encrypted values must be preceded by an ‘@‘. RSA encrypted data should be encoded.

For example, sale request, where accountNumber is encrypted, looks like the following one:
https://sandbox-portal.tidypay.com/gates/xurl?requestType=sale&userName=63000&password=1ol3115RIeQ32tsufca7&accountId=63001&terminalId=3&accountType=R&accountNumber=~411111FFFFFF1111%7cD6ruvFgm%2bX6LhNhcsyxp5xPuX5lqB82Sh03%2bOKJ0oR%2fbGbeHbfDb0I%2bZLtMgFIQ%2bPrHq%2ftRyhMYo215zhD1XKDu%2fG6e%2fal5%2bx2T6liFZa8m2kyJfzf6%2fRY22RIlN6wq4HOAzohjiugaAubPBA7wHMzGG%2bY%2fkNgILVXhQPyOj2PK%2bOwUibzhGsNninwSBgkupqPRv5dQGG2hlXkRQO5P%2b%2bEUk3Gfji1Gzi%2fjf3mfa9lCeEcvI17075g2YkXlbPJ6uWeFi7PPYrHCe7Z4580wTrQ6DyRBa1JIn9yyerPr7Ux1iOGC1UuqarvXIh5OZnA%2fD2kyjpRZT%2bUAuR4Neecz6gg%3d%3d&accountAccessory=1118&csc=111&amount=1500&transactionIndustryType=RE&transactionCode=3538011852&isPartialAuthorization=1&entryModeType=M&entryMediumType=NP&terminalCapabilityMode=manual%7cstripe%7cicc%7ccontactless%7c&holderVerificationModeType=NN&transactionId=100000470

You can encrypt any field that you like, so if you want to encrypt the entire message, it will look similar to this:
https://sandbox-portal.tidypay.com/gates/xurl?requestType=@dsyZTnYkhS4Xu5hOy%2f%2fq0dhutJMR4B3Ur1DctPvaZDR8paiK3KLm33LxNPR22ZqRy8ueSJXSGOaotOf29nieQA%3d%3d&userName=@FVWKKvW9nv%2bJeoWHo7KQvMk5TFJUVIuZFc4D7UplepMQwwBXB0bFyEwTWtG5CGMPI19aERTLVYMzuYuEb8vYfw%3d%3d&password=@dnEBzN%2faBWhYEk%2bS3FevSHnvhFBmY8VAD1QTfh99nMv7GS5Jh7odpRFjwhqk2KSmIJRAjgmBCDwTsb4RtRfYng%3d%3d&accountId=@IDsENxdEEaQu1OL3zbJbsts45POwEnl4BHbHeev9cbuIyyYHP%2fmCd0rQSB2V%2fYbDUfsPGKCB1Ilg78EBsZV5OA%3d%3d&terminalId=@OiBIKxlzHPBF%2bAra09kgmhDWnh4OoebXhkhgo40BYiUL1%2fDuB67CvbUO4wQz%2fmWrfOEUzKGdn%2fvAQq6YY25kaQ%3d%3d&amount=@ITbLfr4on1WsDLePzVtIvwt%2bhlVH8NVlqKIHMBHKBFdzElD7GhIjqrswpZqA2NHenbsLiucDibayBfJbpJID5g%3d%3d&transactionIndustryType=@Ki2rnJ0sRwiDvrMJB5xuSoX41OtSTi%2fDS1nK7CCFWGyQVqzUEBmjAgFOAncf8RJozL8IS9%2brhslfLUDh6FLtGw%3d%3d

For security reasons, RSA keys should be rotated regularly - every 18-24 months. Key rotation is initiated by the processor. When a new key is available, 90-day period, where both old and new keys are acceptable, begins. After the 90 days, the old key is purged, and all devices must be updated with the new key before the purge.

Please contact support to request the public RSA key and code samples.

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.

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 Images  

When working with a terminal, there are situations when a merchant/cardholder does not interact with the terminal. These situations are the following:
  • when a terminal is going through a process that cannot be affected by a user. In this case, a processing screen is shown;
  • when the terminal is in standby mode. In this case, an idle screen is shown.

These screens can be used for branding or advertising with the ability to show a merchant’s logos or advertising images respectively. Depending on the type of the screen, the following images can be used:
  • processing screen - only logos can be displayed;
  • idle screen - either advertising images or logos can be displayed:
    • if you have uploaded the advertising images, they are shown on the idle screen as a slideshow (available only for the default terminal theme);
    • if no advertising images are uploaded to the terminal, a default idle screen is shown instead. The default idle screen displays a company’s logo and the Thank you for choosing [company name] phrase, where the logo and the company name are specified within a branding profile of the merchant. Note that if the silver terminal theme is used, only the default idle screen can be shown.

See the sections below to learn how to upload custom logos and advertising images to be shown on a terminal screen.

Logotypes

To brand a terminal, upload a company’s logo in the PNG format via the Branding Profile form on the user interface at a merchant, reseller, portfolio or system level. When the logo is uploaded, a terminal receives it within the merchant-info API response and shows on a screen in the following cases:
  • In the lower right corner of a default idle screen, for example: screenshot.
  • In the lower right corner of a processing screen, for example when connecting to the gateway or displaying information about current processes: screenshot.

If a company’s logo is not assigned within a branding profile, an image with Visa and MasterCard logos is shown by default.

Advertising

To show advertising images on a terminal screen, contact gateway support and provide JPG images of the names and sizes specified in the table below, depending on your terminal model. You can provide one or several sets of advertising images containing up to 30 images of the sizes defined in the table below in each set.

Terminal Model Screen Size Image Name
iSC250 272x480x24bpp 64--x.jpg, where х - sequential number of the image
iCT250, iPP350, iWL25x, iSMP4 320x240x24bpp 16--х.jpg
iSC480 800x640x24bpp 640--х.jpg
iCT220, iPP320, iCM122, iMP350 128x64x1bpp 8--x.jpg
The sets of images are saved in the appropriate zip files by the gateway support for further use.
When the advertising images are uploaded to the terminal by the gateway support team, a terminal receives them during a terminal update and shows on a customized idle screen as a slideshow, 3 seconds per each image, for example: screenshot. If more than one set of advertising images was provided, there is an option to choose the one to be shown on the terminal screen using the advertisingProfile field in Get Configuration Request.

If advertising images are not uploaded, a default idle screen is shown.

Terminal Message  

Terminal Message mechanism is used to pass control messages from the terminal adapter to the terminal. The purpose of terminal message is to pass environment information to the terminal, such as COM port, on which the terminal is connected to the workstation (in cases when USB cable is used to connect them).

Additionally, you can run terminal diagnostics by submitting exec(log-diagnostics) value via the terminalMessage field in a terminal API request. Once submitted, the result of diagnostics can be reviewed via the user interface. See Terminal Diagnostics guide for more information.

This field has no importance in the context of processing.

Terminal Screen Content  

There are operations in the terminal API that allow a user to show custom prompt dialog messages on a terminal screen. The text shown to the cardholder is submitted to a terminal via the content field as formatted text.

The content field may include up to 10,000 characters. The number of text lines per message is not limited and in cases when a message exceeds free space available on a terminal screen, it can be scrolled using a scrollbar.

It is required to use <root> </root> tags at the beginning and end of the text submitted in content field.

Text within the content field can be also formatted using the following HTML tags:

<b> </b> bold text
<i> </i> italic text
<u> </u> underlined text
<p> </p> paragraph (block of text)
<p/> line break

The following attributes can be added to the text above to specify additional properties of the text formatting:
  • size="name of the size" - available values are xxsmall, xsmall, small, medium, large, xlarge, xxlarge;
  • color="number of the color" - follow the link to review the full list of available colors.

Example of the content field, which includes both tags and attributes listed above:
content=<root><b><u size="large">Title of the page</u></b> <p size="medium">Text of the agreement</p>
<p/><u>underline</u>
<p/><b>bold</b>
<p/><i>italic</i>
<p/><p color="4D" size="medium">Test message</p></root>

Terminal Split Payments  

Split payments occur when more than one form of payment is used to pay for a single POS transaction. In some cases, the customer may explicitly request it, but in most cases, this happens as the consequence of the partial authorization. For example, if a $100 transaction is submitted and there are only $60 on the payment card, the remaining $40 has to be covered using a different form of payment. In such cases, you can either use another payment card or pay in cash. See integration notes for more information.

When terminal split transactions are processed, POS submits only one sale request, but several transaction responses have to be retrieved. To handle this situation, the splitTransactionCount and splitTransactionSequenceNumber fields are used. These fields are populated only when a split payment occurs and more than one transaction result is available to be consumed by POS.
  • the splitTransactionCount field contains a total number of payments included in the transaction. Currently, possible values are 2 and 3. It is important to pay attention to this field when a received response is analyzed to differentiate a split transaction from a regular sale transaction.
  • the splitTransactionSequenceNumber field contains a sequence number of the payment within the transaction. For example, for the first processed payment splitTransactionSequenceNumber will be equal to 1, for the second to 2, and for the third to 3.

Note that a terminal returns only the first split transaction response to the POS system. To load the subsequent responses from the terminal, use the find operation. When submitting the find request, supply either the ticketNumber or ticketId value associated with the original transaction or value of the transactionId/transactionCode field associated with the first payment, and the splitTransactionSequenceNumber of the transaction, which response has to be received.

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

Transaction List Attachment  

If the transaction-list in the API response requires an attachment, this indicates the transfer of a large volume of data, similar to a report. In such cases, a temporary file is created to store the transaction-list data in JSON format.
The attachment in the response contains the entire list of transactions in JSON format.

For structuring the data in JSON format, each element of the transaction-list is represented as an object, which may contain nested objects corresponding to different hierarchy levels.

Example of transaction-list in JSON format:



[


  {


    "account": {


      "id": 523007001,


      "name": "Softpos",


      "code": 523007001


    },


    "reseller": {   


      "id": 67100,


      "name": "Softpos company",


      "code": 67100


    },


    "transaction": {


      "submissionType": "R",


      "submissionId": 9751,


      "accountTypeGroup": "PC",


      "activityDate": "04/01/2024",


      "activityTime": "07:24:49",


      "billingAddress": {


        "street": "",


        "city": "",


        "state": "",


        "zipCode": ""


      }


    }


  },


  {


    "account": {


      "id": 523007002,


      "name": "Softpos",


      "code": 523007002


    },


    "reseller": {


      "id": 67200,


      "name": "Softpos company",


      "code": 67200


    },


    "transaction": {


      "submissionType": "R",


      "submissionId": 9752,


      "accountTypeGroup": "PC",


      "activityDate": "04/01/2024",


      "activityTime": "07:24:49",


      "billingAddress": {


        "street": "",


        "city": "",


        "state": "",


        "zipCode": ""


      }


    }


  },


  {


    "account": {


      "id": 523007003,


      "name": "Softpos",


      "code": 523007003


    },


    "reseller": {


      "id": 67300,


      "name": "Softpos company",


      "code": 67300


    },


    "transaction": {


      "submissionType": "R",


      "submissionId": 9753,


      "accountTypeGroup": "PC",


      "activityDate": "04/01/2024",


      "activityTime": "07:24:49",


      "billingAddress": {


        "street": "",


        "city": "",


        "state": "",


        "zipCode": ""


      }


    }


  }


]


Transaction Summary By Day Attachment  

If the transaction-summary-by-day in the API response requires an attachment, this indicates the transfer of a large volume of data, similar to a report. In such cases, a temporary file is created to store the transaction-summary-by-day data in JSON format.
The attachment in the response contains the summary of transactions processed, grouped by day, in JSON format.
For structuring the data in JSON format, each field of the transaction-summary-by-day is represented as an object, which may contain nested objects corresponding to different hierarchy levels.

Example of transaction-summary-by-day in JSON format:



[


  {


    "portfolio": {


      "id": 624000,


      "name": "Softpos"


    },


    "reseller": { 


      "id": 67100,


      "name": "Softpos company"


    },


    "merchant": {


      "id": 52300,


      "name": "Softpos",


      "businessName": "",


      "legalName": "",


      "taxId": "",


      "mcc": "",


      "countryCode": ""


    },


    "account": {


      "id": 523007003,


      "name": "Softpos"


    },


    "terminal": {


      "id": 3,


      "code": "",


      "status": "Active"


    },


    "date": "2024-04-19 00:00:00.0",


    "transaction": {


      "amount": "250",


      "currencyCode": "US",


      "count": ""


    }


  },


  {


    "portfolio": {


      "id": 625000,


      "name": "Softpos"


    },


    "reseller": {


       "id": 67200,


      "name": "Softpos company"


    },


    "merchant": {


      "id": 52400,


      "name": "Softpos",


      "businessName": "",


      "legalName": "",


      "taxId": "",


      "mcc": "",


      "countryCode": ""


    },


    "account": {


      "id": 523007004,


      "name": "Softpos"


    },


    "terminal": {


      "id": 4,


      "code": "",


      "status": "Active"


    },


    "date": "2024-04-19 00:00:00.0",


    "transaction": {


      "amount": "300",


      "currencyCode": "US",


      "count": ""


    }


  },


  {


    "portfolio": {


      "id": 625000,


      "name": "Softpos"


    },


    "reseller": {


      "id": 67300,


      "name": "Softpos company"


    },


    "merchant": {


      "id": 52500,


      "name": "Softpos",


      "businessName": "",


      "legalName": "",


      "taxId": "",


      "mcc": "",


      "countryCode": ""


    },


    "account": {


      "id": 523007005,


      "name": "Softpos"


    },


    "terminal": {


      "id": 5,


      "code": "",


      "status": "Active"


    },


    "date": "2024-04-19 00:00:00.0",


    "transaction": {


      "amount": "500",


      "currencyCode": "US",


      "count": ""


    }


  }


]



Concepts

Tokenization  

General overview of the tokenization concept can be found here

TidyPay 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 credit card or bank account for the first time (as part of sale-auth, sale, credit-auth or credit operation), TidyPay will generate a unique identification number (token) associated with this payment information.

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

Рure 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 with 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 Type 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 assosiated 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.

Terminal Integration  

For terminal integrations, the cloud integration strategy is used. When the cloud is used, a POS interacts with the terminal cloud, which communicates with a terminal using a persistent TCP channel. This channel remains open as long as the terminal is active and no maintenance procedures are carried out. The terminal cloud is a part of the gateway, and for all practical purposes the cloud and the gateway can be viewed as the same thing. They are treated separately in the documentation to simply demonstrate the concept in the more clear way.

Cloud integration works in the following way: a terminal connects to the gateway and holds a persistent channel. POS can then send the information to the gateway indicating, which terminal is to receive API calls. Every transaction request is being processed for about 5 seconds. The gateway routes the API calls to the appropriate terminal using the persistent channel that the terminal previously opened, and the responses are returned in the same way. The speed of transaction processing depends on the Internet speed and stability. Usually, terminals support speed of 10-100 MB.

See this diagram to review the structure of the cloud integration. See this diagram to review transaction processing flow for cloud.

Note: Typically, a password for a service user that works with real-time API consists of 32 characters. However, for terminal API, length of a service user password equals to 20 characters as another 12 characters are used by a terminal and are added automatically when processing a transaction.

Cloud Processing Configuration

In the cloud integration, a terminal and POS system interact via the cloud server which is a part of the gateway. POS exchanges API calls with the cloud while the cloud forwards API calls to the terminal, and sends the response back to the POS. Given this approach, POS system has to remain connected to the gateway for a duration of the entire transaction, which may take more time than regular card not present transactions. It is necessary to take into account the time that cardholder is going to spend to insert the card and enter the PIN, when needed, into the terminal. Therefore, care must be taken from the POS line to allow connection to the gateway on card present transactions directed to the terminal to remain open for up to three minutes. This is emphasized because the default timeout set by most of the programming languages in similar circumstances is under one minute, which is not going to be sufficient most likely for this type of transactions.

Note that it is important to increase timeout for communication with the cloud only. For cases when a large number of terminals is used, system settings should be configured in a way allowing to hold a large number of open connections simultaneously – it is recommended to use non-blocking I/O (NIO), which requires fewer resources than blocking I/O. NIO is used to open a large number of communication channels simultaneously and manage them using one execution thread. If blocking I/O is used, it is required to open a separate execution thread for each channel.

For cloud integration, ports 443 and 8445 are required to be open for incoming and outgoing requests between the cloud server and a local network, to which a terminal is connected. Otherwise, if a facility network blocks these ports, the cloud will not operate. To verify that communications between a local network and the cloud server are allowed, check their IP addresses and associated ports. To retrieve an IP address of the cloud server, please, contact support. See this diagram for a visual representation of the data exchange between a terminal and the cloud server.

Below you can review Java and C# code samples of cloud communication implementation.

Java Sample

 
 
public static void main (String[] argc) throws IOException
 
{		
		String response = doPostRequest ("https://[server-name]/terminals/xurl", 
				"requestType=sale" +
				"&userName=myUser" +
				"&password=myPassword" +
				"&merchantAccountCode=2001" +
				"&terminalCode=001" +
				"&transactionIndustryType=RE" +
				"&amount=500");
 
	}
	//simple implementation of HTTPs based communication
	public static String doPostRequest(String cloudAddress, String data) throws IOException{
 
	    HttpURLConnection conn = null;
	    InputStream stream = null;
	    URL urlLink = new URL(cloudAddress);
	    OutputStreamWriter writer = null;
 
	    conn = (HttpURLConnection)urlLink.openConnection();
	    conn.setDoInput(true);
	    conn.setDoOutput(true);
	    conn.setUseCaches(false);
	    conn.setConnectTimeout(10000);
	    conn.setReadTimeout(60000);
	    conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
	    conn.setRequestMethod("POST");
 
	    writer = new OutputStreamWriter(conn.getOutputStream());
    	    writer.write(data);
            writer.flush();
	    writer.close();
 
    	if (conn.getResponseCode() = = HttpURLConnection.HTTP_OK) {
			stream = conn.getInputStream();
		} else { 
			stream = conn.getErrorStream();
		}
 
		if (stream = = null){
			System.out.println("Response code is " + conn.getResponseCode());
			return "";
		}
 
		return stream2String(stream);	
	}
 
	private static String stream2String(InputStream is) throws IOException{
		StringBuilder sb = new StringBuilder();
		BufferedReader br = new BufferedReader(new InputStreamReader(is));
		String line = null;
		while ((line = br.readLine())!= null){
			sb.append(line);
		}
		return sb.toString();
	}
 


C# Sample 

 
public static void Main (string[] argc)
		{
 
			string response = DoPostRequest ("https://[server-name]/terminals/xurl", 
				"requestType=sale" +
				"&userName=myUser" +
				"&password=myPassword" +
				"&merchantAccountCode=2001" +
				"&terminalCode=001" +
				"&transactionIndustryType=RE" +
				"&amount=500");
 
		}
 
 
		//simple implementation of HTTPs based communication
		public static string DoPostRequest(string cloudAddress, string postData)
		{
			var data = Encoding.ASCII.GetBytes(postData);
 
			HttpWebRequest request = (HttpWebRequest)WebRequest.Create(cloudAddress);
 
			request.Method = "POST";
			request.Timeout = 60000;
			request.ContentType = "application/x-www-form-urlencoded";
			request.ContentLength = data.Length;
 
			using (var stream = request.GetRequestStream())
			{
				stream.Write(data, 0, data.Length);
			}
 
			var response = (HttpWebResponse)request.GetResponse();
 
			Stream dataStream = response.GetResponseStream();
 
			StreamReader reader = new StreamReader(dataStream);
			string responseFromServer = reader.ReadToEnd();
 
			if (reader != null) { reader.Close(); reader.Dispose(); }
			if (dataStream != null) { dataStream.Close(); dataStream.Dispose(); }
			if (response != null) { response.Close(); }
 
			return responseFromServer;
		}
 
 
 

Intent Mechanism  

When you integrate a POS system with the terminal application in Managed mode, the application relies on Android intents to manage communication. When an API request is made, the response can include up to two structures within the intent: `response` and `data`.


All API requests are categorized into two types:

  • Standard Requests (no attachment)
  • Requests with an attachment (e.g., reports)

All API requests, regardless of type, include a `response` data structure. However, the requests with an attachment, which deal with larger data volumes, also include a `data` structure. This `data` structure contains a URI linking to an attachment (with the large data) and is included in addition to the usual `response` structure.


The `response` structure includes a set of fields according to the TidyPay Documentation (gatewayaid.com) specification, depending on the request being made. Besides the standard fields described in the specification, the terminal adds two additional fields in the `response` structure:


  • dataType: indicates the format of the response (details below)
  • dataChecksum: a checksum that can be used to validate the integrity of the attachment, if one is included in `data` structure

The dataType field indicates how to interpret the response:

  • "no data" - there is nothing to analyze, the request returned no information.
  • "error" - the response generates an error. Details can be found in the responseCode and responseMessage fields.

  • "detail" (default type) - the response should be interpreted according to the format described in the TidyPay Documentation (gatewayaid.com) API documentation.

  • "list" - the response includes an attachment with the list of data in JSON format, and the data should be handled accordingly.

Attachment

When a response needs to return a large amount of data, an attachment is produced. A temporary file is created to store this data in JSON format.


The `data` structure in the response provides the URI to this temporary file containing the data. This `data` structure is sent alongside the `response` structure in the API response.






Copyright © TidyPay. All Rights Reserved.
All Logos and Trademarks used or mentioned on this page are copyrighted property of their respective owners and are used for display purposes only.