Real Time (HTTPs) APIs
Version
Current Specification Version: V8.2.0
General
Tokenization
Settlement
Gift/Loyalty Cards
Callbacks
Reporting
Miscellaneous
General Information
The connection URL for the sandbox server is: https://secure-stage.csipay.com/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.
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
-
Format
- Core Infо
- Account Information
- Transaction Information
- Cross-References
- Extended Logic
- Billing Address Information
- Shipping Address Information *
- Level II Transaction Information *
- Level III Transaction Information *
- Restaurant Industry *
- PIN Debit/EBT cards *
- Interac *
- HPP Fields *
- Transit Fields
- Voice Authorization *
- 3D Secure *
- Healthcare Industry *
- Petroleum *
- Lodging *
- Identity Verification *
- Terminals
- Check 21
- Car Rental
The Sale Auth operation authorizes a specified amount on a cardholder's account for later capture and processing. This two-step payment process first reserves funds (authorization) and later transfers them to the merchant account (capture). If a capture operation is never performed, the authorization will automatically void.
This approach is ideal for businesses that need to verify fund availability before finalizing transactions, such as hotels, rental services, e-commerce with delayed shipping, or situations where the final amount might change (like adding tips in restaurants).
> **Note:** You must have a valid merchant account set up with processing credentials to use this endpoint.
> **Warning:** For ACH transactions (bank accounts), authorization does not guarantee funds availability due to the nature of ACH processing.
> **Tip:** Authorizations typically expire after 7 days but this can vary depending on the cardholder's issuing bank. To ensure funds capture, implement timely capture operations in your application workflow.
This approach is ideal for businesses that need to verify fund availability before finalizing transactions, such as hotels, rental services, e-commerce with delayed shipping, or situations where the final amount might change (like adding tips in restaurants).
> **Note:** You must have a valid merchant account set up with processing credentials to use this endpoint.
> **Warning:** For ACH transactions (bank accounts), authorization does not guarantee funds availability due to the nature of ACH processing.
> **Tip:** Authorizations typically expire after 7 days but this can vary depending on the cardholder's issuing bank. To ensure funds capture, implement timely capture operations in your application workflow.
-
Format
- Core Infо
- Account Information
- Transaction Information
- Cross-References
- Extended Logic
- Billing Address Information
- Shipping Address Information *
- Level II Transaction Information *
- Level III Transaction Information *
- Restaurant Industry *
- PIN Debit/EBT cards *
- Interac *
- HPP Fields *
- Transit Fields
- Voice Authorization *
- 3D Secure *
- Healthcare Industry *
- Petroleum *
- Lodging *
- Identity Verification *
- Terminals
- Check 21
- Car Rental
The Sale operation allows developers to process payments by authorizing and capturing funds in a single API call. This streamlined approach is ideal for immediate payment scenarios where authorization and settlement need to happen together, such as e-commerce checkouts, point-of-sale transactions, and subscription billing.
This endpoint supports both card-present and card-not-present transactions, as well as ACH (direct bank) payments. It can handle standard retail transactions, recurring payments, installment plans, and specialized payment flows for industries including restaurants, healthcare, petroleum, and lodging.
> **Note:** Before implementing this endpoint, ensure you have a merchant account set up and proper API credentials. If processing ACH transactions, subscribe to NOC and return webhooks to receive real-time updates on bank account changes and transaction returns.
> **Tip:** This endpoint supports tokenization, allowing you to securely store payment information for future transactions. When a successful transaction is processed, a token is returned in the response that can be used for subsequent charges without requiring the full payment details again.
> **Warning:** When implementing this endpoint, ensure you're following PCI compliance requirements. For card-not-present transactions, using address verification (AVS) and card security code (CSC) validation is strongly recommended to reduce fraud risk.
This endpoint supports both card-present and card-not-present transactions, as well as ACH (direct bank) payments. It can handle standard retail transactions, recurring payments, installment plans, and specialized payment flows for industries including restaurants, healthcare, petroleum, and lodging.
> **Note:** Before implementing this endpoint, ensure you have a merchant account set up and proper API credentials. If processing ACH transactions, subscribe to NOC and return webhooks to receive real-time updates on bank account changes and transaction returns.
> **Tip:** This endpoint supports tokenization, allowing you to securely store payment information for future transactions. When a successful transaction is processed, a token is returned in the response that can be used for subsequent charges without requiring the full payment details again.
> **Warning:** When implementing this endpoint, ensure you're following PCI compliance requirements. For card-not-present transactions, using address verification (AVS) and card security code (CSC) validation is strongly recommended to reduce fraud risk.
-
Format
- Core Infо
- Account Information
- Transaction Information
- Cross-References
- Extended Logic
- Billing Address Information
- Shipping Address Information *
- Level II Transaction Information *
- Level III Transaction Information *
- Restaurant Industry *
- PIN Debit/EBT cards *
- Interac *
- 3D Secure *
- Healthcare Industry *
- Petroleum *
- Lodging *
- Identity Verification *
- Terminals
- Check 21
- Car Rental
credit-auth and capture in a single process.
This operation allows development teams to reverse previously processed transactions. The endpoint serves two primary purposes depending on the transaction's settlement status:
When a transaction needs to be reversed but has not yet been settled with the payment processor, use a **void** request. Voids typically have no financial impact on the cardholder and cancel the original authorization. When a transaction has already been settled and needs to be reversed, use a **refund** request. Refunds initiate a new transaction that returns funds to the cardholder.
Applications can also perform partial reversals by specifying an amount less than the original transaction. This is useful for order modifications where only part of the transaction needs to be reversed.
> **Note:** The same API endpoint handles both void and refund operations, with the operation type specified in the requestType field.
> **Tip:** For more information about transaction reversal operations, refer to the "Capture, Void and Refund Operation" integration guide.
When a transaction needs to be reversed but has not yet been settled with the payment processor, use a **void** request. Voids typically have no financial impact on the cardholder and cancel the original authorization. When a transaction has already been settled and needs to be reversed, use a **refund** request. Refunds initiate a new transaction that returns funds to the cardholder.
Applications can also perform partial reversals by specifying an amount less than the original transaction. This is useful for order modifications where only part of the transaction needs to be reversed.
> **Note:** The same API endpoint handles both void and refund operations, with the operation type specified in the requestType field.
> **Tip:** For more information about transaction reversal operations, refer to the "Capture, Void and Refund Operation" integration guide.
The Capture operation finalizes a previously authorized transaction, transferring funds from the customer's account to the merchant. This operation is essential in the two-step payment flow (authorize-then-capture) commonly used by businesses that need to verify funds availability before completing a transaction.
After authorizing a payment with a sale-auth transaction, you must perform a capture operation to actually collect the funds. This gives you time to fulfill orders, adjust amounts (like adding tips), or cancel the transaction if needed. Without capturing, authorized transactions are automatically voided after a period (typically 7 days, though this varies by issuing bank).
> **Note:** The capture amount cannot exceed the original authorization amount. For partial captures, you can specify a lower amount than originally authorized.
> **Tip:** For restaurant transactions requiring tips, you must run the original transaction with `transactionIndustryType=RS` and then include the tip amount when capturing. For example, if the original sale-auth was $10.00 and the tip is $1.00, your capture amount should be $11.00, with the specific tip amount ($1.00) in the `tipAmount` parameter.
> **Warning:** Authorizations typically expire after 7 days, but this can vary by issuing bank. It's best practice to capture funds as soon as possible after fulfillment to avoid authorization expiration.
After authorizing a payment with a sale-auth transaction, you must perform a capture operation to actually collect the funds. This gives you time to fulfill orders, adjust amounts (like adding tips), or cancel the transaction if needed. Without capturing, authorized transactions are automatically voided after a period (typically 7 days, though this varies by issuing bank).
> **Note:** The capture amount cannot exceed the original authorization amount. For partial captures, you can specify a lower amount than originally authorized.
> **Tip:** For restaurant transactions requiring tips, you must run the original transaction with `transactionIndustryType=RS` and then include the tip amount when capturing. For example, if the original sale-auth was $10.00 and the tip is $1.00, your capture amount should be $11.00, with the specific tip amount ($1.00) in the `tipAmount` parameter.
> **Warning:** Authorizations typically expire after 7 days, but this can vary by issuing bank. It's best practice to capture funds as soon as possible after fulfillment to avoid authorization expiration.
an operation used to verify that the account is active and perform AVS verification without actual authorization (0 dollar authorization).
an operation used to verify balance on debit, prepaid and gift cards.
The Convenience Fee API enables applications to calculate and apply surcharges or service fees to payment transactions. This endpoint is specifically designed to determine the appropriate fee amount before processing a payment, allowing development teams to implement compliant fee structures and improve revenue management.
When integrated into a payment flow, this API helps businesses cover processing costs through two primary mechanisms: service fees for government and education sectors, and surcharges for credit card transactions. The calculated fee amount can be seamlessly incorporated into subsequent payment requests, providing transparency to end users about additional costs.
> **Note:** This operation is particularly valuable for platforms serving government entities, educational institutions, and merchants in regulated industries who need to offset processing costs while maintaining compliance with card brand rules.
> **Warning:** Surcharging is highly regulated by card brands, federal and state governments. It is not permitted on debit cards. Contact support before implementing surcharges to ensure compliance with all applicable regulations.
> **Tip:** For service fee implementation requiring two separate transactions (one for the service amount and one for the fee), include the returned `feeAmount` in your subsequent sale request. This enables the system to process both transactions appropriately. Contact support to configure your account for this implementation pattern.
When integrated into a payment flow, this API helps businesses cover processing costs through two primary mechanisms: service fees for government and education sectors, and surcharges for credit card transactions. The calculated fee amount can be seamlessly incorporated into subsequent payment requests, providing transparency to end users about additional costs.
> **Note:** This operation is particularly valuable for platforms serving government entities, educational institutions, and merchants in regulated industries who need to offset processing costs while maintaining compliance with card brand rules.
> **Warning:** Surcharging is highly regulated by card brands, federal and state governments. It is not permitted on debit cards. Contact support before implementing surcharges to ensure compliance with all applicable regulations.
> **Tip:** For service fee implementation requiring two separate transactions (one for the service amount and one for the fee), include the returned `feeAmount` in your subsequent sale request. This enables the system to process both transactions appropriately. 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.
Tokenization
The tokenization operation enables development teams to securely convert sensitive payment card numbers and bank account numbers into PCI-compliant tokens. This operation addresses the critical need for applications to store and reference payment methods without maintaining sensitive cardholder data in their own systems, significantly reducing PCI compliance scope and security risks.
Applications can use this endpoint to implement "cards on file" functionality, allowing customers to save payment methods for future use without the application storing actual card numbers. The returned tokens can be used in all subsequent payment operations, providing the same functionality as the original payment data while maintaining security compliance.
The operation supports both credit cards and bank accounts, with optional verification to ensure account validity before tokenization. Integration teams can implement this as a standalone service or incorporate it into broader payment workflows, depending on their application requirements.
> **Note:** Valid API credentials with tokenization permissions and a configured merchant account are required. Development teams should review PCI compliance requirements and understand that while tokenization reduces scope, proper handling of sensitive data during transmission remains critical.
> **Tip:** This operation supports both direct API integration and hosted payment page implementation. For detailed implementation guidance, see the Processing Management Guide for HPP integration and Business Entities Guide for understanding merchant account relationships.
> **Warning:** By default, all payment data sent to the platform is automatically tokenized. Applications should implement proper error handling and consider using verification mode for production environments to avoid tokenizing invalid payment methods.
Applications can use this endpoint to implement "cards on file" functionality, allowing customers to save payment methods for future use without the application storing actual card numbers. The returned tokens can be used in all subsequent payment operations, providing the same functionality as the original payment data while maintaining security compliance.
The operation supports both credit cards and bank accounts, with optional verification to ensure account validity before tokenization. Integration teams can implement this as a standalone service or incorporate it into broader payment workflows, depending on their application requirements.
> **Note:** Valid API credentials with tokenization permissions and a configured merchant account are required. Development teams should review PCI compliance requirements and understand that while tokenization reduces scope, proper handling of sensitive data during transmission remains critical.
> **Tip:** This operation supports both direct API integration and hosted payment page implementation. For detailed implementation guidance, see the Processing Management Guide for HPP integration and Business Entities Guide for understanding merchant account relationships.
> **Warning:** By default, all payment data sent to the platform is automatically tokenized. Applications should implement proper error handling and consider using verification mode for production environments to avoid tokenizing invalid payment methods.
allows updating of an existing token.
Note: This operation is available only for tokens created for real-time processing with TrustCommerce.
Settlement
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.
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.
-
Format
- Core Infо
- Account Information
- Transaction Information
- Cross-References
- Extended Logic
- Billing Address Information
- Shipping Address Information *
- Level II Transaction Information *
- Level III Transaction Information *
- Restaurant Industry *
- PIN Debit/EBT cards *
- Voice Authorization *
- 3D Secure *
- Healthcare Industry *
- Petroleum *
- Lodging *
- Identity Verification *
- Check 21
- Car Rental
allows to supply information about a sale transaction, which was processed outside of the gateway, but affects rewards balance of loyalty cards.
-
Format
- Core Infо
- Account Information
- Transaction Information
- Cross-References
- Extended Logic
- Billing Address Information
- Shipping Address Information *
- Level II Transaction Information *
- Level III Transaction Information *
- Restaurant Industry *
- PIN Debit/EBT cards *
- Voice Authorization *
- 3D Secure *
- Healthcare Industry *
- Petroleum *
- Lodging *
- Identity Verification *
- Check 21
- Car Rental
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
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.
allows the submitter to get the business information about a merchant.
Miscellaneous
allows a submitter to upload resources to the gateway.
allows a submitter to download resources from the gateway.
allows to migrate a physical device from one accountId/terminalId to another accountId/terminalId.
allows a submitter to get information about stored data in cases when profiling/deprofiling is used.
allows a submitter to extract BIN data from a credit card.
allows a submitter to extract bank data from a direct debit.
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. |
Copyright ©
Constellation Payments. 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.