Real Time (HTTPs) APIs

Version

Current Specification Version: 7.1

View Change History

* Available for testing with host emulator



General Information


Overview  

The purpose of this document is to provide documentation for 3rd parties to integrate with UniCharge processing gateway.

Connectivity information  

The connection URL for the sandbox server is: https://[server-name]/gates/xurl.
Authorization is done via service users. To access the API, a service user is required to be granted with a corresponding privilege. A user can submit API requests using either associated credentials or temporary password generated via authentication operation. To learn more about service users and end-points used for API submission, review Security Management guide.

Request method is POST. The content-type must be set to application/x-www-form-urlencoded.
Request fields are passed within HTTPS request body (including cases with callbacks) and are required to be URL-encoded.
Response fields are passed within HTTPS response body.
Both request and response field values are passed using name1=key1&name2=key2 format.

Supported Operations

General

Sale-Auth   
an operation used to withdraw specific amounts of money from the supplied credit card or bank account. Sale-Auth requires an explicit capture operation in order for the money to be transferred; otherwise, an automatic void is issued.
Sale   
sale-auth and capture in a single process.
Credit-Auth (deprecated)   
an operation used to deposit (return) specific amounts of money to the supplied credit card or bank account. Credit-Auth requires an explicit capture operation in order for the money to be transferred; otherwise, an automatic void is issued.
Credit   
credit-auth and capture in a single process.
Void/Refund   
an operation used to reverse a sale operation. See integration notes for more information.
Capture   
confirms a previously requested authorization (sale or credit).
Account Verification   
an operation used to verify that the account is active and perform AVS verification without actual authorization (0 dollar authorization).
Balance Inquiry   
an operation used to verify balance on debit, prepaid and gift cards.
Convenience Fee   
an operation used to calculate a surcharge to the cardholder to cover the cost of the credit card processing.
Increment   
allows to increase the authorization amount of already authorized transaction (to add payment for additional product or service).
Note: This operation is available only for transactions with transactionIndustryType=RE or LD.

Authentication   
an operation used to generate temporary password to be used in requests associated with HPP. See integration notes for more information.
Fetch   
allows to get a transaction that was made when a terminal was offline (when processingMode=queue or processingMode=request).

Tokenization

Tokenization   
allows conversion of a credit card number or a bank account number into a PCI compliant token value.
Untokenization   
allows manual removal of a token from the system.
Retokenization   
allows updating of an existing token.

Note: This operation is available only for tokens created for real-time processing with TrustCommerce.

Settlement

Close Cycle   
allows a submitter to close currently open retail cycle (batch) for an account, send all captured transactions within the cycle for settlement, see totals within a retail cycle and reverse any void transactions.
Balance Inquiry Cycle   
allows a submitter to validate totals within a retail cycle before calling Close Cycle operation.

Gift/Loyalty Cards

Activate   
allows a merchant to activate a gift card.
Reactivate   
allows a merchant to reactivate a previously deactivated gift card.
Deactivate   
allows a merchant to deactivate an active gift card.
Transfer   
allows to transfer a balance from one card to another card.
Sale-Info   
allows to supply information about a sale transaction, which was processed outside of the gateway, but affects rewards balance of loyalty cards.
Credit-Info   
allows to supply information about a credit transaction, which was processed outside of the gateway, but affects rewards balance of loyalty cards.
Create Alias   
allows to create an alias for a gift card. Similar to token, alias can be used instead of card number for further processing.
Delete Alias   
allows to remove the alias for a gift card.

Callbacks

Callback   
a callback issued to the URL supplied by a submitter for receiving notifications about offline operations.

Reporting

Find   
allows a submitter to retrieve response of a particular transaction using either transactionId or transactionCode value associated with the transaction.
Note:
  • Information about the following transaction types can be accessed via find API request: sale-auth, sale, credit, refund, sale-info, credit-info, account-verification, balance-inquiry, convenience-fee, capture, tokenization
  • Make sure that your user has access to the merchant associated with the transaction that should be retrieved in the response. Otherwise, your request will result in an error.
Merchant Info   
allows the submitter to get the business information about a merchant.

Miscellaneous

Ping   
allows to verify availability of the server and get the current version of the API.
Upload Resource   
allows a submitter to upload resources to the gateway.
Download Resource   
allows a submitter to download resources from the gateway.
Find Terminal   
allows a submitter to receive connection path of the terminal for further update.
Get Profile   
allows a submitter to get information about stored data in cases when profiling/deprofiling is used.
BIN Data   
allows a submitter to extract BIN data from a credit card.
Bank Data   
allows a submitter to extract bank data from a direct debit.
Split Schema   
allows a submitter to create a split schema for subsequent funds distribution between several recipients.

Message Formats


Usage:

R - required in request/always present in response for direct debit transactions and credit card transactions of all levels (I, II, III).
O - optional in request/not always present in response.
C - conditional; conditions of the usage are defined below the corresponding section.
E - echo back from request; if present in request, it is present in response, if it is not present in request, it is not present in response.
R2 - required in request/always present in response for credit card transactions of level II and III only; optional for direct debit and level I credit card transactions.
R3 - required in request/always present in response for credit card transactions of III only; optional for direct debit and level I, II credit card transactions.
SR - required in request/always present in response for split transactions only.
I - for internal use only.
N - not used.
* - required fields in these specific sections are only required if this specific feature is used.