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

Sale-Auth

Authorize payment method for later capture and processing.
- Amounts are specified in cents (e.g., $10 = 1000).
- Authorizations reserve funds without transferring them; capture must be performed to complete the transaction.
- For direct debit, authorization does not guarantee funds availability.
- Authorizations typically expire after 7 days, but duration may vary by issuing bank.
- If capture is not performed, the authorization is automatically voided.
- Suitable for scenarios requiring verification before finalizing payment (e.g., reservations, pre-orders, gratuity adjustments).

Get-Configuration

Sale

Authorize and capture transaction in a single operation, supporting both credit cards and direct debit methods.
- Input amounts in cents (e.g., $5 = 500).
- For direct debit, use NOC and return webhooks to stay updated on payment issues and compliance.
- Payment data is tokenized automatically for PCI compliance.
- For card-not-present payments, include AVS and CVV for fraud protection.
- Returns a transaction token that allows reuse of payment details for future charges.

Credit

Process a credit transaction to disburse funds directly to customers' or vendors' payment cards or bank accounts.
- Credit transactions regulated by network rules varying by card brand and country.
- Specific permissions may be required on account for credit transactions to bank accounts or cards.
- Combines authorization and capture in single process for efficient fund transfer.
- Ideal for disbursements, refunds, payouts, and loyalty rewards.
- Works with any payment method recipient uses.
- Tokenized payment methods enhance security and simplify repeat payments to same recipient.

Void/Refund

Cancel pending transaction or issue refund based on settlement status.
- Use void for unsettled transactions to cancel authorization without fund transfer.
- Use refund for settled transactions to return funds to the cardholder.
- Both operations use the same API endpoint, specified in the requestType field.
- For partial reversal, specify amount less than the original transaction.
- Choose correct operation type to ensure accurate financial reconciliation.

Capture

Capture previously authorized funds to complete payment processing after transaction verification or order fulfillment.
- Capture amount cannot exceed original authorization amount.
- Authorizations typically expire after 7 days (varies by issuing bank).
- Uncaptured sale-auth transactions automatically void within the system.
- Partial captures allowed by specifying lower amount than authorized.
- For restaurant tips, use transactionIndustryType=RS in original sale-auth and include total with tip at capture.
- Finalizes two-step payment flow, transferring funds to merchant account.

Account Verification

Verify payment account information to confirm validity and reduce transaction failures before storing payment methods.
- For Direct Debit with WEB industry type, NACHA rules require account validation before first use
- Credit cards receive $0 authorization; bank accounts validate routing and account numbers only
- Account verification alone does not guarantee blocking of future transactions on invalid accounts
- Returns token in response for both verification and storage in single call
- RT00 response indicates valid routing number but unverified account for bank accounts
- For implementation examples and validation scenarios, see Account Verification Guide

Balance Inquiry

Validate batch totals to ensure accurate settlement process before closing the batch cycle.
- Verifies transaction totals and counts within an open batch before settlement.
- Implement as part of end-of-day reconciliation to prevent settlement discrepancies.
- Must be used before closing batch for settlement processing.

Convenience Fee

Calculate and apply convenience fees to support cost recovery while maintaining compliance.
- Surcharging highly regulated by card brands, federal and state regulations - not permitted on debit cards.
- Contact support before implementing surcharges to ensure compliance with all regulations.
- Service fees may require special account configuration.
- Supports service fees for government/education and surcharges for credit cards.
- Returns calculated feeAmount that must be included in payment request.
- For two-transaction service fee pattern, include returned amount in next sale with combined total.
- System automatically processes service amount and fee as separate transactions.
- Contact support to configure account for two-transaction implementation pattern.

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

Generate a temporary password to securely authenticate hosted payment page integrations and API requests.
- Multiple failed attempts with expired passwords may lock the service user account.
- Temporary password remains valid for 15 minutes.
- Required for API authentication when collecting payment through hosted payment pages.
- Prevents exposure of permanent credentials in browser environments.
- Implement proper error handling for expired credentials.
- Helps avoid security vulnerabilities from credential caching.

Fetch

allows to get a transaction that was made when a terminal was offline (when processingMode=queue or processingMode=request).

Tokenization

Tokenization

Convert payment data to secure token for future transactions.
- Requires valid API credentials with tokenization permissions and a configured merchant account.
- All credit card and bank account data sent is automatically tokenized.
- For production, use account-verification requests before tokenization to ensure payment method validity.
- Tokens allow storing payment methods without storing sensitive data directly, reducing PCI scope and risk.
- Supports "cards on file" functionality for future payments.

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

Close the transaction batch to initiate settlement for all captured transactions, providing batch totals and processing void reversals.
- Service user credentials must have appropriate permissions to close cycles.
- All captured transactions within batch will be submitted for settlement upon execution.
- Closes currently open retail cycle regardless of transaction source (API or batch upload).
- Processes transactions from both API calls and batch upload files.
- Use at end of business day to ensure timely processing and settlement.

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

Retrieve transaction details using transaction identifiers to access complete transaction history and response data.
- API credentials must have access rights to merchant associated with requested transaction.
- Service users must be properly configured with appropriate permissions.
- Requires either system-generated transactionId or your own transactionCode.
- Supports sale, auth, credit, refund, verification, and inquiry operations.
- Use for reconciliation, customer support inquiries, and audit trails.
- Store `transactionCode` values in your system for easier cross-referencing.

Merchant Info

Retrieve merchant business profiles, including company details, contact information, and account configurations.
- Requires proper authentication credentials with appropriate permissions.
- Service users must be configured with appropriate access levels.
- Returns complete business profile data for specified merchant.
- Includes registration information, contact details, and service configurations.
- Use to onboard new merchants or verify existing configurations.

Miscellaneous

Ping

Verify API availability and retrieve the current API version.
- No parameters required for this operation.
- Returns basic connectivity status and current API version.
- Use for health checks and monitoring system uptime.
- Helpful for troubleshooting connectivity issues.
- Useful for continuous system monitoring and validating integration setup.

Upload Resource

allows a submitter to upload resources to the gateway.

Download Resource

Retrieve transaction signatures and associated metadata to build complete audit records.
- Only works with transactions from signature-capable terminals.
- Returns error for standard API transactions or terminals without signature support.
- Uses processing API endpoint, not terminal API endpoint.
- Ensure secure storage of signature files for compliance and dispute resolution requirements.

Migrate Terminal

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

Get Profile

Retrieve tokenized cardholder data by accessing complete profile associated with a token.
- Requires specific permissions - contact support to enable profiling functionality.
- Available only when profiling is activated on account.
- Applies exclusively to payment methods tokenized after activation.
- Works with both payment cards and bank accounts previously tokenized.
- Access additional customer data (billing address) without storing sensitive information.
- Improves security while maintaining access to necessary customer information.

BIN Data

allows a submitter to extract BIN data from a credit card.

Bank Data

Retrieve bank information associated with direct debit payments, including institutional address and phone number.
- Requires proper authentication credentials with appropriate permissions.
- Service users must be correctly configured for API integration.
- Extracts complete bank data from direct debit transactions.
- Provides institutional information for verification and reporting.
- Use to verify payment details, enhance customer communication, or pre-fill payment forms.

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.