Real Time (HTTPs) APIs

Version

Current Specification Version: V9.1.4

View Change History

General

Tokenization

Settlement

Gift/Loyalty Cards

Callbacks

Reporting

Miscellaneous

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

When submitting an API request, you can use either UniPay server URL or the Sanitizing Data Filter (Unibroker) server URL as an endpoint.
Requests that contain tokenized card numbers/bank account numbers can be submitted directly to {Unipay} server.
To reduce PCI exposure, requests with non-tokenized (raw) account data should be passed through the sanitizing data filter server. Otherwise, L04 error will be returned (Processing of raw account data is not allowed through the specified API end-point for the current user).
If you don’t have a specific reason, we recommend sending all the requests to the same endpoint (data filter).
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

Get-Configuration

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

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.

Migrate Terminal

allows to migrate a physical device from one accountId/terminalId to another accountId/terminalId.

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.