Zip and Country Codes|
Development
Reference Materials
General
Tokenization
Settlement
Gift/Loyalty Cards
Callbacks
Reporting
Miscellaneous
The purpose of this document is to provide documentation for 3rd parties to integrate with UniCharge processing gateway.
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.
General
Authorize a payment amount on a customer's card or bank account for later capture and processing. This two-step payment process gives you flexibility to verify fund availability prior to finalizing a transaction. This is commonly used for reservations, pre-orders, or when final amounts might change.
> **Note:** Authorizations reserve funds without transferring them, requiring a separate capture operation to complete the transaction. Amounts are specified in cents, not dollars (e.g., $10.00 = 1000).
> **Warning:** For direct debit (bank account) payments, authorization does not guarantee funds availability due to the nature of direct debit processing. Authorizations typically expire after 7 days, though this period may vary based on the cardholder's issuing bank. If a capture is never performed, the authorization will be automatically voided.
> **Tip:** This approach is ideal for businesses that need verification before finalizing transactions, such as hotels, car rentals, delayed-shipping e-commerce platforms, or adding gratuities to restaurant payments. See the Capture Guide for implementing timely capture operations.
Process customer payments by authorizing and capturing funds in a single operation. This endpoint enables SaaS platforms to charge customers immediately for purchases, subscriptions, or services while automatically processing payments made through credit cards or through direct debits from bank accounts.
> **Note:** All transaction amounts must be specified in cents (e.g., $5.00 = 500 cents). This endpoint automatically tokenizes payment data for PCI compliance.
> **Warning:** For direct debit payments, subscribing to NOC and return webhooks is strongly recommended. They provide real-time updates on account status changes and return notices, helping avoid payment delays, additional fees, and compliance issues with direct debit network rules.
> **Tip:** The returned transaction token can be used for future charges without re-entering payment details. For card-not-present transactions, include the AVS and CVV (CSC) validation to help mitigate fraud risk. See Payment Processing Guide for complete implementation details.
Process a credit transaction to disburse funds directly to customers' or vendors' payment cards or bank accounts - ideal for disbursements, refunds, payouts, and loyalty rewards.
> **Note:** This operation combines authorization and capture in a single process to ensure that funds are transferred efficiently to the recipient regardless of the payment method used.
> **Warning:** Credit transactions are regulated by network rules that vary by card brand and country. Specific permissions may be required on your account to process credit transactions to bank accounts or cards.
> **Tip:** Using tokenized payment methods for credit transactions enhances security and simplifies repeat payments to the same recipient. See the Credit Transaction Implementation Guide for best practices.
Reverse completed transactions to cancel payments or issue refunds based on settlement status. Submit a void request for unsettled transactions or a refund request for settled transactions. Voids cancel the original authorization without resulting in a fund transfer, while refunds return funds to the cardholder.
> **Note:** Both operations use the same API endpoint with operation type specified in the requestType field. To perform a partial reversal, specify an amount less than the original transaction.
> **Warning:** The choice between a void and a refund depends on whether the transaction has been settled. Use void for unsettled transactions and refund for settled transactions to ensure proper financial reconciliation.
> **Tip:** For comprehensive implementation guidance, including transaction lifecycle management, refer to the "Capture, Void and Refund Operation" integration guide.
Capture previously authorized funds to complete payment processing after transaction verification or order fulfillment. This finalizes the two-step payment flow, transferring funds from the customer's account to your merchant account.
> **Note:** The capture amount cannot exceed the original authorization amount. For partial captures, you may specify a lower amount than the one initially authorized.
> **Warning:** Authorizations typically expire after 7 days, but can vary depending on the cardholder's issuing bank. If a capture operation is never performed, the sale-auth transaction will automatically be voided within the system.
> **Tip:** For restaurant transactions requiring tips, specify transactionIndustryType=RS in the original sale-auth request and include the total amount with tip during capture. See Payment Processing Guide for complete implementation details.
Verify payment account information to confirm validity, reduce the risk of failed transactions, and improve customer conversion rates before storing payment methods without initiating a charge.
> **Note:** For credit cards, this performs a $0 authorization. For bank accounts (Direct Debit), this validates routing and account numbers without monetary authorization.
> **Warning:** NACHA rules require merchants processing Direct Debit (ACH) transactions with transactionIndustryType=WEB to validate bank account numbers prior to first use. Account verification alone does not guarantee that future transactions on invalid accounts will be blocked.
> **Tip:** Returns token in response, allowing both verification and token storage in a single call. For bank accounts, an RT00 response indicates valid routing numbers but unverified accounts. See the Account Verification Guide for implementation details.
Validate batch totals to ensure an accurate settlement process before closing the batch cycle.
> **Note:** Used within an open batch to verify transaction totals and transaction counts before closing the batch for settlement processing.
> **Tip:** Implement this operation as part of the end-of-day reconciliation process to prevent settlement discrepancies. See Security Management Guide for information about service user integration requirements.
Calculate and apply convenience fees to support cost recovery while maintaining compliance. This operation determines appropriate surcharges or service fees before processing payments, enabling transparent handling of processing expenses.
> **Note:** Supports two fee types: service fees for government/education sectors and surcharges for credit card transactions. Returns the calculated feeAmount that must be included in the corresponding payment request.
> **Warning:** Surcharging is highly regulated by card brands, as well as federal and state regulations and is not permitted on debit cards. Contact support before implementing surcharges to ensure compliance with all applicable regulations. Service fees may require special account configuration.
> **Tip:** For service fee implementation requiring two separate transactions, include this returned amount in your next sale request with the combined total amount. We'll automatically process both the service amount and fee amount as separate transactions. Contact support to configure your account for this implementation pattern.
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.
Generate a temporary password to securely authenticate hosted payment page integrations and API requests.
> **Note:** The temporary password remains valid for 15 minutes and is required for API authentication when collecting payment information through hosted payment pages.
> **Warning:** Attempting to use an expired temporary password may result in the service user account being locked after multiple failed authentication attempts. Always implement proper error handling for expired credentials.
> **Tip:** Use this operation as part of your security implementation to avoid exposing permanent credentials in browser environments where credential caching could introduce security vulnerabilities.
allows to get a transaction that was made when a terminal was offline (when processingMode=queue or processingMode=request).
Tokenization
Convert sensitive payment card and bank account numbers into PCI-compliant tokens to securely store payment methods for future transactions, eliminating the need to store sensitive data in your system.
> **Note:** As a Level I PCI Compliant platform, the platform stores the actual card or bank account numbers, allowing you to reference them with tokens for future processing. Valid API credentials with tokenization permissions and a configured merchant account are required.
> **Warning:** By default, all credit card and bank account data sent to our servers is automatically tokenized. For production environments, we recommend using account-verification requests to validate payment methods before tokenization, ensuring the payment method is valid before being stored.
> **Tip:** Use tokenization to implement "cards on file" functionality, significantly reducing the scope of your PCI compliance obligations and associated security risks. For optimal implementation, see the Processing Management Guide for HPP integration options and Business Entities Guide for understanding merchant account relationships.
allows manual removal of a token from the system.
allows updating of an existing token.
Note: This operation is available only for tokens created for real-time processing with TrustCommerce.
Settlement
Close the transaction batch to initiate settlement for all captured transactions, providing batch totals and processing any void reversals.
> **Note:** This operation closes the currently open retail cycle (batch) for an account, sending all transactions for settlement regardless of their source (whether API transactions or batch upload files).
> **Warning:** Service user credentials must have appropriate permissions to close cycles. All captured transactions within the batch will be submitted for settlement when this operation is executed.
> **Tip:** Use this operation at the end of your business day to ensure timely processing and settlement of all transactions. See the Batch Processing Guide for complete implementation details.
allows a submitter to validate totals within a retail cycle before calling Close Cycle operation.
Gift/Loyalty Cards
allows a merchant to activate a gift card.
allows a merchant to reactivate a previously deactivated gift card.
allows a merchant to deactivate an active gift card.
allows to transfer a balance from one card to another card.
allows to supply information about a sale transaction, which was processed outside of the gateway, but affects rewards balance of loyalty cards.
allows to supply information about a credit transaction, which was processed outside of the gateway, but affects rewards balance of loyalty cards.
allows to create an alias for a gift card. Similar to token, alias can be used instead of card number for further processing.
allows to remove the alias for a gift card.
Callbacks
a callback issued to the URL supplied by a submitter for receiving notifications about offline operations.
Reporting
Retrieve transaction details using transaction identifiers to access complete transaction history and response data.
> **Note:** Retrieve original transaction responses using either the system-generated `transactionId` or your own `transactionCode`. One of these is required. Supports multiple transaction types, including sale, auth, credit, refund, verification, and inquiry operations.
> **Warning:** Your API credentials must have access rights to the merchant associated with the requested transaction. Service users must be properly configured with appropriate permissions to avoid access errors.
> **Tip:** Use this operation for reconciliation, customer support inquiries, and audit trails. Be sure to store your `transactionCode` values in your system for easier cross-referencing when retrieving transaction details later.
Retrieve merchant business profiles, including company details, contact information, and account configurations.
> **Note:** This operation returns complete business profile data for the specified merchant, including registration information, contact details, and service configurations.
> **Warning:** Access to merchant information requires proper authentication credentials with appropriate permissions. Ensure service users are configured with the appropriate access levels as outlined in the Security Management Guide.
> **Tip:** Use this endpoint to onboard new merchants or verify existing configurations. See the Response tab in the documentation for a complete list of returned fields.
Miscellaneous
Verify API availability and retrieve the current API version.
> **Note:** This operation doesn't require any parameters and returns basic connectivity status and the current API version.
> **Tip:** Use this operation for health checks, monitoring system uptime, or troubleshooting connectivity issues. This is useful for continuous system monitoring and validating your integration setup.
allows a submitter to upload resources to the gateway.
Retrieve transaction signatures and associated metadata to build complete audit records.
> **Note:** This operation only works with transactions processed through signature-capable terminals. If the transaction was processed via the standard API or a terminal without signature support, an error will be returned.
> **Warning:** This operation differs from other terminal-related calls as it uses the processing API endpoint rather than the terminal API endpoint. Use the following processing API endpoints: Production – https://secure.zift.io/gates/xurl? / Sandbox – https://sandbox-secure.zift.io/gates/xurl?
> **Tip:** Ensure secure storage of signature files to support compliance and dispute resolution requirements.
allows to migrate a physical device from one accountId/terminalId to another accountId/terminalId.
Retrieve tokenized cardholder data by accessing a complete profile associated with a token. This applies to payment cards or bank accounts that were previously tokenized.
> **Note:** This operation is available only when profiling is activated on your account and applies exclusively to payment methods tokenized after activation.
> **Warning:** The get-profile operation requires specific permissions. Contact support to enable profiling functionality on your account before implementing this feature.
> **Tip:** Use this operation to access additional customer data (such as billing address) without storing sensitive information in your own system, improving security while maintaining access to necessary customer information.
allows a submitter to extract BIN data from a credit card.
Retrieve bank information associated with direct debit payments, including the associated address and phone number of the institution.
> **Note:** This operation extracts complete bank data from direct debit transactions, providing essential institutional information for verification and reporting.
> **Warning:** Access to this operation requires proper authentication credentials with appropriate permissions. Service users must be correctly configured to support API integration.
> **Tip:** Use this information to verify payment details, enhance customer communication, or pre-fill payment forms. See Security Management Guide for service user setup.
allows a submitter to create a split schema for subsequent funds distribution between several recipients.
| 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. |
| 