Real Time (HTTPs) APIs
Version
Current Specification Version: V8.2.2
General
Tokenization
Settlement
Gift/Loyalty Cards
Callbacks
Reporting
Miscellaneous
General 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 TidyPay 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 TidyPay 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
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.
-
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
sale-auth and capture in a single process.
-
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.
an operation used to reverse a sale operation. See integration notes for more information.
confirms a previously requested authorization (sale or credit).
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.
an operation used to calculate a surcharge to the cardholder to cover the cost of the credit card processing.
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
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 ©
TidyPay. 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.