Batch (sFTP) APIs
Integration Notes
Bank Information Subscription
In certain countries, in order to execute a bank transfer, prior authorization has to be obtained from a financial institution that is going to process transactions. Both BACS and SEPA systems require such preliminary mandate registration. To register a mandate, subscription file has to be sent. Subscription file with mandates allows a merchant to provide the information about the accounts that are going to be used subsequently for transaction processing. If mandates associated with respective accounts fail to be processed, subsequent transactions will be declined.
Time delay between the moment when an account is registered and when the first transaction is allowed, varies from system to system. Thus, it will be 6 days after account registration for BACS and 5 days for SEPA.
When an account is registered in BACS or SEPA system, an identifier of a mandate is returned within transactionId field as a part of the subscription response file. For further usage, the received value must be submitted within subscriptionCode field as a part of subsequent real-time API requests or batch files.
The peculiarities of request file submission and response file receiving for subscription files with mandates are the following:
Time delay between the moment when an account is registered and when the first transaction is allowed, varies from system to system. Thus, it will be 6 days after account registration for BACS and 5 days for SEPA.
When an account is registered in BACS or SEPA system, an identifier of a mandate is returned within transactionId field as a part of the subscription response file. For further usage, the received value must be submitted within subscriptionCode field as a part of subsequent real-time API requests or batch files.
The peculiarities of request file submission and response file receiving for subscription files with mandates are the following:
| SEPA | BACS | |
|---|---|---|
| Subscription request file | 1 business day prior to effective date | 6 business days prior to effective date |
| Subscription response file | Same day subscription request was submitted | 5 business days after subscription request was submitted |
| Processing file | 6 business days prior to effective date | 1 business day prior to effective date |
Batch Encryption
For customers that do not use a built-in tokenization functionality and would like to process files containing raw card data (either for processing or for account update), an additional layer of encryption - PGP - can be used to remain compliant with PCI regulations. In order to use PGP encryption, a public key must be requested from the integration support. Any PGP encryption software can be used.
For security reasons, PGP keys should be rotated regularly - every two years. Two keys are used during the key rotation process - current key and newly generated key. Key rotation procedure goes as follows:
For security reasons, PGP keys should be rotated regularly - every two years. Two keys are used during the key rotation process - current key and newly generated key. Key rotation procedure goes as follows:
- One month prior to the required rotation time, new private key gets generated by the integration team. A respective public key is derived from the private key and distributed to a client with the request to replace the current public key with the new one.
- Both keys, current and new one, can be used during 30-day rotation period. Current key is the primary key, and a new key is the secondary one.
- At the end of the rotation period, secondary key replaces the current key, thereby becoming the primary key and completing the rotation. The old primary key cannot be used from this moment.
Batch Tokenization
When a batch file is processed, it is recommended to use tokens instead of actual account numbers. In such cases, the file is placed into the inbox folder and processed in a regular way. However, in circumstances when unencrypted account numbers (credit card numbers, bank account numbers) are placed into a file, it is recommended to put the file in invault folder as opposed to inbox folder.
Tokenization process is subsequently applied on all of the files in invault folder. All card numbers are converted into tokens and replaced with respective records in a request file, and the new request file (containing tokens only) is automatically placed in inbox folder for regular processing. Files will automatically be removed from invault folder after processing.
There are cases, when it is necessary to tokenize account numbers without actually charging the accounts. In such cases batch tokenization format can be used. Information about tokenization message format can be found in integration notes.
Tokenization process is subsequently applied on all of the files in invault folder. All card numbers are converted into tokens and replaced with respective records in a request file, and the new request file (containing tokens only) is automatically placed in inbox folder for regular processing. Files will automatically be removed from invault folder after processing.
There are cases, when it is necessary to tokenize account numbers without actually charging the accounts. In such cases batch tokenization format can be used. Information about tokenization message format can be found in integration notes.
Cross-reference Fields
The system provides an ability to specify values that can be used for cross-referencing of entities between the gateway and a submitter’s system. The fields that can be provided by an integrated external system are listed below:
*In some cases, the submitting system is going to have two different identifiers for a given transaction: one, shown to the end user on the UI, and the other one, a system identifier (very often a database-generated artificial ID). In such cases, the user-visible ID (which is used in the business context) should be submitted in the regular fields (in transactionCode or customerAccountCode), while internal ID (artificial ID), should be sent as transactionInternalCode or customerAccountInternalCode.
| Entity | Field Name | Description |
|---|---|---|
| Transaction | transactionCode | Identifier of the transaction within an external system that submits the transaction for processing. |
| transactionInternalCode* | Unique internal identifier of the transaction within an external system that submits the transaction for processing. Can be used as a supplement to a transactionCode. | |
| Customer | customerAccountCode | Identifier of a customer within the submitter’s system that submits the transaction for processing. |
| customerAccountInternalCode* | Unique internal identifier of a customer within the submitter’s system that submits the transaction for processing. Can be used as a supplement to a customerAccountCode. | |
| Item | itemCode | Identifier of a purchased product or service within an external system that submits the transaction for processing. |
| Charge | chargeCode | Identifier of the charge within an external system that submits the transaction for processing. |
*In some cases, the submitting system is going to have two different identifiers for a given transaction: one, shown to the end user on the UI, and the other one, a system identifier (very often a database-generated artificial ID). In such cases, the user-visible ID (which is used in the business context) should be submitted in the regular fields (in transactionCode or customerAccountCode), while internal ID (artificial ID), should be sent as transactionInternalCode or customerAccountInternalCode.
Direct Debit
Direct debit is the process of funds transfer from one bank account to another. Currently, the following direct debit systems are supported within the system: ACH for US and Canada, BACS for UK, SEPA for EU and Direct Entry for Australia and New Zealand. For direct debit transactions, two fields are required: bank identification number, submitted as accountAccessory, and bank account number, submitted as accountNumber. To format these fields correctly, please use guidelines below depending on the country.
You are required to submit the first two digits of a routing number within the following ranges:
If an invalid routing number is submitted to the gateway, the following error code/ message is returned: F22 (AccountAccessory is not well-formatted):
US ACH
For ACH transaction processing in the US, a routing number is used within the accountAccessory field, and its format is a nine-digit number. Along with the length of the field, the first two digits of the routing number value are validated to verify whether the bank account number, associated with the transaction, originates from the US. This reduces the probability of merchant’s fraud.You are required to submit the first two digits of a routing number within the following ranges:
- 00;
- 01 through 12;
- 21 through 32;
- 61 through 72;
- 80.
If an invalid routing number is submitted to the gateway, the following error code/ message is returned: F22 (AccountAccessory is not well-formatted):
- for realtime transactions, the error is returned within an API response;
- for batch transactions, the information about the error is provided in the processing response file.
Canada ACH
For ACH (EFT) transaction processing in Canada, three fields are required: three-digit institution number, five-digit branch number, and account number. For processing purposes of Canadian ACH, the institution number and branch number are combined in a single routing number value using the rules below.- The Canadian routing number is comprised of three parts: a leading zero (0), three-digit institution number (YYY) and five-digit branch number (XXXXX), which go respectively all together with no dashes: 0YYYXXXX. Please, note that the institution number (YYY) should never be all zeros (000). See this link for complete list of institution numbers.
- The XXXXX-YYY format with a dash between the branch number and the institution number is only valid for paper-type transactions, such as checks. Thus, if a check reads XXXXX-YYY, the corresponding EFT code will be 0YYYXXXXX.
EU SEPA
For SEPA transaction processing in the European Union, bank identification number is submitted in BIC format and bank account number is submitted in IBAN format.- Bank identification number consists of 8-11 characters and is comprised of four parts: four-letter institution code or bank code, two-letter country code, two-letter or two-digit location code and three-letter or three-digit branch code. Last three characters are optional. See this link to have better understanding of BIC format.
- Account number consists of up to 34 alphanumeric characters and is comprised of three parts: two-letter country code, two check digits and a long and detailed bank account number. See this link to have better understanding of IBAN format.
UK BACS
For BACS transaction processing in the United Kingdom, format of these fields is the following:- Bank identification number is formatted as sort code, which is a six-digit number, formatted as three pairs of numbers. For example, 12-34-56. See this link for complete list of sort codes.
- Account number consists of 8-10 digits.
Australia/New Zealand Direct Entry
For Direct Entry transaction processing in Australia, format of these fields is the following:- Bank identification number is submitted in BSB format. It consists of 6 digits and is comprised of two parts: two-digit bank code and four-digit branch number. For example, 033088. See this link for complete list of Australian bank codes and this link for complete list of New Zealand bank codes.
- Account number consists of up to 17 characters.
Duplicate Validation
Batch processing mechanism includes validation logic that detects potential file/batch duplicates. If within fifteen days after a file/batch was submitted, another file/batch is received with the same transaction count and transaction amount, the file/batch is sent into approval queue for manual review and will either be canceled or approved depending on circumstances. The file/batch will not be processed until approval is granted.
Dynamic Descriptor
An important feature that many merchants require, - is the support for a custom-defined soft descriptor. Depending on the processor, this feature can be supported as a static value, associated with an underlying merchant ID, or as a dynamic value, that can be specified for each transaction processed.
For credit cards, the descriptor is a single value length of 25 characters; for direct debit, the descriptor is comprised of two fields: Merchant Name (13) and Item Descriptor (10), the values should be separated with two colons (:), e.g:
[descriptor]::[merchantName]
When transactions are processed through PSP or an aggregator, it is common to include an identifier of the underlying payment processor or aggregator through a prefix, which is, usually, 3 or 6 characters in length. The prefix is added to the name of the merchant and is generally separated from it by an asterisk (*).
For each transaction processed through a processor, which supports dynamic descriptor feature, submitter can supply the value of the descriptor in the following format:
[item-descriptor]:[prefix]*[merchant-name]
Note that a processor can require a specific set of symbols to be present or absent in the descriptor. To avoid any issues, one of such symbols, asterisk (*), is replaced with a space ( ) in batch API requests.
Each part of the descriptor is optional; if respective value is not supplied at the transaction level (as part of the request), the default value will automatically be taken from the profile (if it is configured). When deciding on which value to supply, please make sure that maximum allowed length for each component is respected.
If the descriptor is not formatted correctly, the system is going to make the best attempt to properly truncate the values and process the transaction. A special warning will be issued and returned to the submitter (as warningCode field) explaining how descriptor should be adjusted in the future submissions.
Different payment card associations (Visa/MC/Discover) have different processing rules and timelines. While a Visa transaction is funded within 24h and cardholders may see the transactions in their online account almost instantly after an authorization happens (depending on their issuing bank), Amex takes 3 days to fund and sometimes it may take up to 3 days to see the transaction settled into the account and to have the transactions show up in online cardholder’s account. Please note that this delay depends on Amex processing rules only and can't be changed in the settings of the gateway.
Depending on the processor, dynamic descriptor mechanism can be supported at the authorization time or at the settlement time. In cases when the mechanism is supported at the settlement time, the descriptor gets supplied only after the transaction is settled. This means that a transaction will show up on cardholder's bank account with a generic descriptor (in pending authorizations section), while in a day (or 2-3 days later in case of Amex) it will be displayed with the proper descriptor.
While all issuing banks will show at least the descriptor characters when the transaction is presented to the card holder, some can show more information (such as merchant name, phone, merchant state). It doesn't depend on the settings of the gateway and is specific to an online banking system of a particular issuing bank.
For all processors that support descriptor, processors configuration profile contains fields allowing to specify the default value that is used in a transaction if descriptor was not explicitly provided within the request. For those cases when you don't want to supply descriptor and you don't want any default values from the profile to be used (basically, you don't want to supply any descriptor information to the processor), you can send the value "-::-" in the descriptor field. This will indicate to the system that no descriptor information should be supplied to the processor and whatever descriptor is associated with the respective MID at the processor's end will be used.
For credit cards, the descriptor is a single value length of 25 characters; for direct debit, the descriptor is comprised of two fields: Merchant Name (13) and Item Descriptor (10), the values should be separated with two colons (:), e.g:
[descriptor]::[merchantName]
When transactions are processed through PSP or an aggregator, it is common to include an identifier of the underlying payment processor or aggregator through a prefix, which is, usually, 3 or 6 characters in length. The prefix is added to the name of the merchant and is generally separated from it by an asterisk (*).
For each transaction processed through a processor, which supports dynamic descriptor feature, submitter can supply the value of the descriptor in the following format:
[item-descriptor]:[prefix]*[merchant-name]
Note that a processor can require a specific set of symbols to be present or absent in the descriptor. To avoid any issues, one of such symbols, asterisk (*), is replaced with a space ( ) in batch API requests.
Each part of the descriptor is optional; if respective value is not supplied at the transaction level (as part of the request), the default value will automatically be taken from the profile (if it is configured). When deciding on which value to supply, please make sure that maximum allowed length for each component is respected.
If the descriptor is not formatted correctly, the system is going to make the best attempt to properly truncate the values and process the transaction. A special warning will be issued and returned to the submitter (as warningCode field) explaining how descriptor should be adjusted in the future submissions.
Different payment card associations (Visa/MC/Discover) have different processing rules and timelines. While a Visa transaction is funded within 24h and cardholders may see the transactions in their online account almost instantly after an authorization happens (depending on their issuing bank), Amex takes 3 days to fund and sometimes it may take up to 3 days to see the transaction settled into the account and to have the transactions show up in online cardholder’s account. Please note that this delay depends on Amex processing rules only and can't be changed in the settings of the gateway.
Depending on the processor, dynamic descriptor mechanism can be supported at the authorization time or at the settlement time. In cases when the mechanism is supported at the settlement time, the descriptor gets supplied only after the transaction is settled. This means that a transaction will show up on cardholder's bank account with a generic descriptor (in pending authorizations section), while in a day (or 2-3 days later in case of Amex) it will be displayed with the proper descriptor.
While all issuing banks will show at least the descriptor characters when the transaction is presented to the card holder, some can show more information (such as merchant name, phone, merchant state). It doesn't depend on the settings of the gateway and is specific to an online banking system of a particular issuing bank.
For all processors that support descriptor, processors configuration profile contains fields allowing to specify the default value that is used in a transaction if descriptor was not explicitly provided within the request. For those cases when you don't want to supply descriptor and you don't want any default values from the profile to be used (basically, you don't want to supply any descriptor information to the processor), you can send the value "-::-" in the descriptor field. This will indicate to the system that no descriptor information should be supplied to the processor and whatever descriptor is associated with the respective MID at the processor's end will be used.
Effective Date
Transactions with effective date (transaction date) in the past as well as in the future can be processed. Any transactions with dates in the past are processed with the effective date of today, while any future dated transactions are processed on the specified effective date in the future. The only limitation is that a single file should not mix transactions with past, current and future effective dates. In other words, all transactions in the file must be either in the past, effective today or effective in the future.
Legacy Names
Legacy Field Names
To unify field names within the APIs and the user interface of the gateway, the following reference field names have been changed:| Deprecated Field Name | New Field Name |
|---|---|
| merchantCode | merchantId |
| merchantAccountCode | accountId |
| terminalCode | terminalId |
| referenceNumber | transactionId |
| providerReferenceNumber | providerTransactionId |
| originalReferenceNumber | originalTransactionId |
| aggregateReferenceNumber | aggregateTransactionId |
| submissionCode | submissionId |
Both deprecated and new names are currently supported by the system. The deprecated names will be supported until October, 30th, 2019. All new integrations should be done with the new names only.
Note that if #merchantAccountCode tag is indicated in the Tag List section within the associated merchant settings, the system will return files with the deprecated names. If #accountId tag is indicated in the Tag List, the system will return files with the new names.
Legacy File Names
To unify names of the files returned within the batch API, the following files names have been changed:| Deprecated Field Name | New Field Name |
|---|---|
| returns.20170919.2000.zip | 20170919.2000.returns.zip |
| returns.au.20170919.2000.zip | 20170919.2000.returns.au.zip |
| returns.subscriptions.20170919.2000.zip | 20170919.2000.returns.subscriptions.zip |
Both deprecated and new names are currently supported by the system. The deprecated names will be supported until the end of 2018. All new integrations should be done with the new names only.
Note that if #returns-old tag is indicated in the Tag List section within the associated merchant/reseller/portfolio settings, the system will return files with the deprecated names. If the tag is absent in the Tag List, the system will return files with the new names.
Merchant Charges
Merchant charges are designed for resellers/software platforms to be able to deduct funds on their behalf from the remittances of the merchants. One of the most typical use is to collect franchising fees. Charges can be submitted in the respective files.
To submit charges for processing, charges file is used. When a submitted file is processed by the system, a corresponding response file, which specifies whether the charges were accepted for processing or were rejected due to the validation issues, is returned. Charges that were accepted are subsequently withheld from a merchant. When these charges are processed, indicated amounts of funds are deposited to a reseller and a charge payments file is generated automatically and delivered to a submitter. This file contains a list of payments that were collected from merchants on behalf of a reseller as a result of remittance process. In cases when the indicated merchant does not have sufficient funds on the bank account, additional payments associated with a charge will be collected in the future and included in the subsequent charge payments files.
To submit charges for processing, charges file is used. When a submitted file is processed by the system, a corresponding response file, which specifies whether the charges were accepted for processing or were rejected due to the validation issues, is returned. Charges that were accepted are subsequently withheld from a merchant. When these charges are processed, indicated amounts of funds are deposited to a reseller and a charge payments file is generated automatically and delivered to a submitter. This file contains a list of payments that were collected from merchants on behalf of a reseller as a result of remittance process. In cases when the indicated merchant does not have sufficient funds on the bank account, additional payments associated with a charge will be collected in the future and included in the subsequent charge payments files.
Multiple Merchants in a Single File
Generally, a batch file is going to contain an information for a single merchant (multiple accounts). However it is possible to process multiple merchants in a single file. Request file may contain several merchants, if all of these merchants are linked to the same reseller.
For example, if it is needed to process transactions for merchants 3000, 4000, 5000, then they can be aggregated in a single multiple merchant file and processed under merchant 6000 (created for the purposes of aggregation).
For example, if it is needed to process transactions for merchants 3000, 4000, 5000, then they can be aggregated in a single multiple merchant file and processed under merchant 6000 (created for the purposes of aggregation).
Notices of Change (NOCs)
When ACH transactions in the US and Canada are processed, the realtime approval information is not available like it is for credit cards. For this purpose many companies will verify accounts against blacklists and, if an account is not blacklisted, return an approval response by default. Subsequently, when any types of returns come back from the bank, they are forwarded over to the transaction's submitter/merchant.
Under some circumstances (for instance, bank mergers), a bank may need to update information about account such as bank account number, routing number or name on the account. It is done through 'notice of change' mechanism, which is similar to the mechanism used to deliver ACH returns, and it's important not to confuse the two. While ACH return implies that a payment was not honored, notice of change implies a payment was processed successfully, but some information (which is provided within the NOC) should be updated in any future payment requests for this account.
Within the response file transaction type for ACH return is 'N' and transaction type for NOCs is 'U'.
Under some circumstances (for instance, bank mergers), a bank may need to update information about account such as bank account number, routing number or name on the account. It is done through 'notice of change' mechanism, which is similar to the mechanism used to deliver ACH returns, and it's important not to confuse the two. While ACH return implies that a payment was not honored, notice of change implies a payment was processed successfully, but some information (which is provided within the NOC) should be updated in any future payment requests for this account.
Within the response file transaction type for ACH return is 'N' and transaction type for NOCs is 'U'.
Record ID
To identify an object within the system, the gateway assigns its own unique identifier when the object is created. In the context of transaction processing, identifiers of previously created objects, such as merchant (accountId, merchantId) and a terminal (terminalId), are submitted as a part of an API request. Identifiers of objects created as a result of the transaction processing, such as a transaction itself (transactionId), are returned within an API response.
When a transactionId is returned, depending on the context, values of these fields can be preceded by the prefixes listed in the table below:
When a transactionId is returned, depending on the context, values of these fields can be preceded by the prefixes listed in the table below:
| Field | Prefix | Description | Example |
|---|---|---|---|
| transactionId | without prefix | Reference to a sale, sale-auth or credit transaction. | transactionId=123456 |
| transactionId | with @ prefix | Reference to an original sale-auth transaction that was captured. Returned only within a capture response file in the following format: @transactionId=[transactionId of the original sale-auth transaction]. | @transactionId=123456 |
Payment Aggregation
Account number aggregation is the mechanism, allowing aggregation of multiple incoming transactions, that have the same account information, into a single transaction, that is physically processed. It is primarily used to reduce processing cost.
There are two terms associated with account number aggregation: aggregated transaction and aggregate transaction.
Any transaction that is submitted for processing but is actually processed as part of another transaction, is called an aggregated transaction. Any transaction that includes in its amount other (aggregated) transactions and is physically processed with a bank, is called an aggregate transaction.
Each aggregated transaction is going to include a reference back to the aggregate transaction. This reference is implemented using three fields: aggregateReferenceNumber, aggregateTransactionCode and aggregateTransactionInternalCode. Anyone of them can be used to link aggregated transaction to its respective aggregate.
The aggregation process also comes into play when chargebacks and ACH returns are received for an aggregate transaction with several underlying aggregated transactions. In such cases, the system generates separate ACH returns or chargebacks for each aggregated transaction.
Please note, that aggregate transaction is always the transaction that came from the submitter, and no new transaction is created as part of the aggregation process. Another way to identify aggregated transactions is to throw processedAmount field. If processedAmount is zero, this transaction was aggregated. If processedAmount is greater that the value of amount field of this transaction, this transaction is aggregate.
For example, three transactions in the amount of $10 each with the same account number are received. Two of them are aggregated (processedAmount is $0), and one of them becomes the aggregate transaction with the amount of $30 (processedAmount is $30). The $30 transaction is subsequently processed. Should return or chargeback for this $30 transaction ever occur, two additional ACH returns or chargebacks will be generated for the original two aggregated transactions. In the end the submitter will receive three ACH returns or chargebacks with the amount of $10 each.
There are two terms associated with account number aggregation: aggregated transaction and aggregate transaction.
Any transaction that is submitted for processing but is actually processed as part of another transaction, is called an aggregated transaction. Any transaction that includes in its amount other (aggregated) transactions and is physically processed with a bank, is called an aggregate transaction.
Each aggregated transaction is going to include a reference back to the aggregate transaction. This reference is implemented using three fields: aggregateReferenceNumber, aggregateTransactionCode and aggregateTransactionInternalCode. Anyone of them can be used to link aggregated transaction to its respective aggregate.
The aggregation process also comes into play when chargebacks and ACH returns are received for an aggregate transaction with several underlying aggregated transactions. In such cases, the system generates separate ACH returns or chargebacks for each aggregated transaction.
Please note, that aggregate transaction is always the transaction that came from the submitter, and no new transaction is created as part of the aggregation process. Another way to identify aggregated transactions is to throw processedAmount field. If processedAmount is zero, this transaction was aggregated. If processedAmount is greater that the value of amount field of this transaction, this transaction is aggregate.
For example, three transactions in the amount of $10 each with the same account number are received. Two of them are aggregated (processedAmount is $0), and one of them becomes the aggregate transaction with the amount of $30 (processedAmount is $30). The $30 transaction is subsequently processed. Should return or chargeback for this $30 transaction ever occur, two additional ACH returns or chargebacks will be generated for the original two aggregated transactions. In the end the submitter will receive three ACH returns or chargebacks with the amount of $10 each.
Retry Fee
There is a feature allowing a merchant to apply a surcharge on approvals that result from retry process (see integration notes for more information on retry process).
If retry fee is defined, it will be added to the transaction amount when a reattempt of a previous decline is made. In case of successful decline recycling (approval), the amount of the surcharge (retry fee) will be passed back in the standard response through retryFee field. This fee is not cumulative, and will be added to the original amount only once, no matter how many reattempts are made.
If retry fee is defined, it will be added to the transaction amount when a reattempt of a previous decline is made. In case of successful decline recycling (approval), the amount of the surcharge (retry fee) will be passed back in the standard response through retryFee field. This fee is not cumulative, and will be added to the original amount only once, no matter how many reattempts are made.
Retry Process
The system provides support for a retry process, by the means of which certain card declines can be retried for one or several times after the initial attempt. This is often done for declines that indicate a temporary issue with the payment source that might get resolved on the subsequent retry (for example, insufficient balance). Transactions with response codes configured for reattempt will be automatically selected by the system and re-tried, based on retry terms defined for any particular submitter (Merchant). All retry responses are returned to the submitter in the same way as direct debit returns and chargebacks. For direct debit returns transactions, transactionId corresponds to originalTransactionId .
All responses (initial and retry results) will be sent back to the submitter using standard interchange protocol. Transactions that are still part of the reattempt process (and thus will have additional responses, possibly approvals reversing previous declines) are marked with isRebillEnabled flag (set to 1). The submitter should decide how these transactions are to be handled - whether the initial decline is recognized right away or whether the final response (with isRebillEnabled set to 0) is to be awaited.
If a transaction is a reattempt initiated by the gateway, it will use the same transaction ID. However, the sequence number indicating the attempt of that transaction will be appended at the end of the transaction ID using colon as a separation. For example, the first reattempt for transaction with transactionId 12312312 will have transactionId 12312312:1, the second retry will have transactionId 12312312:2, etc.
All responses (initial and retry results) will be sent back to the submitter using standard interchange protocol. Transactions that are still part of the reattempt process (and thus will have additional responses, possibly approvals reversing previous declines) are marked with isRebillEnabled flag (set to 1). The submitter should decide how these transactions are to be handled - whether the initial decline is recognized right away or whether the final response (with isRebillEnabled set to 0) is to be awaited.
If a transaction is a reattempt initiated by the gateway, it will use the same transaction ID. However, the sequence number indicating the attempt of that transaction will be appended at the end of the transaction ID using colon as a separation. For example, the first reattempt for transaction with transactionId 12312312 will have transactionId 12312312:1, the second retry will have transactionId 12312312:2, etc.
| Type of transaction | Transaction ID Format | Examples |
| Client-initiated transactions (when account number or token is used) | [originalTransactionId] | 123123123 |
| Client-initiated tokenization operation (tokenization transaction) | T[originalTransactionId] | T123123123 |
| Gateway initiated transactions (or reattempt transactions) | [originalTransactionId]:sequence number of retry | 123123123:2 |
| Chargebacks | A[originalTransactionId] | A123123123 |
Sequence Number
The sequenceNumber field can be used either in the request or in the response, although the designation of the field differs in the following cases:
- If submitted within the request file, it is used to indicate a sequential number of an installment payment. In this case, the field is used in conjunction with the sequenceCount field, which provides information about a total number of installment payments expected for this particular cardholder.
- If retrieved within the response file, it is used to indicate a sequential number of a received chargeback or reversal. For the first chargeback/reversal, the value of the sequenceNumber field equals to 1, and this value is going to be incremented each subsequent round. The value can be used to avoid misinterpretation of a new chargeback/reversal as a duplicate of a previously processed chargeback/reversal.
Service Fees
Quite often, companies that process transactions on behalf of other organizations may require to explicitly indicate that the payment amount includes a certain part that constitutes service fees. For example, when $105 sale is processed, $5 represent service fees that the company submitter wants to withhold when deposits will get remitted to the organization on behalf of which the transaction was done (e.g. organization gets $100 and submitter keeps $5 service fee).
In order to accommodate these needs, Sale operation provides feeAmount field, which should contain the amount of the processing fee that the submitter wants to withhold from remittance. Note: based on merchant configurations, actual processing/interchange fee will be deducted either from the amount remitted to the organization beneficiary or from the service fee amount of the submitter.
In order to accommodate these needs, Sale operation provides feeAmount field, which should contain the amount of the processing fee that the submitter wants to withhold from remittance. Note: based on merchant configurations, actual processing/interchange fee will be deducted either from the amount remitted to the organization beneficiary or from the service fee amount of the submitter.
Stored Credentials
There can be cases when a payment card is going to be used for recurring/installment transactions, which can be processed either in real-time or as batch files. Some card brands require identification of an original authorization when recurring transactions are processed. The idea of that is when a cardholder was accepting the agreement, an initial transaction was processed either as card-present or with CSC included, and subsequent recurring transactions, which are processed as card-not-present without CSC, are assumed to be a continuation of the initial or previous transaction. This is needed to manage risk and fraud, resulting in fewer chargebacks and an improved cardholder experience.
To process a recurring/installment transaction, follow the steps below:
In the table below you can see, which fields are required to submit in the request and which are returned in the response when using the stored credentials mechanism:
To process a recurring/installment transaction, follow the steps below:
- Submit a processing request file. All transactions submitted within a processing request file are considered to be recurring/installment.
- Once the response file is returned, every transaction has the networkTransactionId field value included. This value must be used in every transaction associated with the first one to indicate that a transaction is a continuation of a recurring sequence and follows a recurring/installment transaction that has already been processed by the system before. Note that each networkTransactionId value is associated with a certain sequence of recurring/installment transactions and not with an account number of a cardholder.
- Submit the received networkTransactionId field value in the originalNetworkTransactionId field within the subsequent recurring/installment transactions.
- If you want to start a new sequence of recurring/installment transactions, you have to submit a new processing request file without the originalNetworkTransactionId field included in the transactions, as described in step 1.
In the table below you can see, which fields are required to submit in the request and which are returned in the response when using the stored credentials mechanism:
| Transaction Sequence | Network Transaction ID |
Original Network Transaction ID |
|---|---|---|
| First transaction (request) | ||
| First transaction (response) | x | |
| Subsequent transactions (request) | x | |
| Subsequent transactions (response) | x | |
Transaction Groups
Transaction groups is a concept, used by batch validation process, which validates deviations in amounts between recurring batches on any two subsequent months. Merchants, that are not interested in this validation logic, should ignore the concept of the transaction group.
Transactions can be logically divided into groups. To assign a transaction to a group, it is sufficient to specify transactionGroupCode when sale or credit request is made. When incoming batch is validated and compared to the transactions processed in the previous month, transaction group is taken into account.
For example, if a merchant sends 2 files per month (on or around 1st and on or around 15th), and the transactions sent on the 1st are marked as "1st billing", while transactions sent on the 15th are marked as "15th billing", the validation mechanism will match (and calculate deviation) current month's "1st billing" with last month's "1st billing" and current month's "15th billing" with last month's "15th billing". When deviation exceeds allowable threshold, the batch is automatically placed in review queue.
Transactions can be logically divided into groups. To assign a transaction to a group, it is sufficient to specify transactionGroupCode when sale or credit request is made. When incoming batch is validated and compared to the transactions processed in the previous month, transaction group is taken into account.
For example, if a merchant sends 2 files per month (on or around 1st and on or around 15th), and the transactions sent on the 1st are marked as "1st billing", while transactions sent on the 15th are marked as "15th billing", the validation mechanism will match (and calculate deviation) current month's "1st billing" with last month's "1st billing" and current month's "15th billing" with last month's "15th billing". When deviation exceeds allowable threshold, the batch is automatically placed in review queue.
Data Export
Data Export
The system has a capability to deliver various data exports using FTP file exchange mechanism (the same mechanism is used to process batch files). The reports can be generated by merchant and by portfolio.
For additional information about the folder structure see integration notes.
Currently, the following data exports are available:
- When reports are generated by merchant, each report contains the information for a single merchant, and is placed in the /data folder of the respective merchant.
- When reports are generated by reseller, they are be placed in the /data folder of the respective reseller, and contain the information of all merchants associated with this reseller.
- When reports are generated by portfolio, they are placed in the /data folder of the respective portfolio, and contain the information of all merchants associated with this portfolio.
For additional information about the folder structure see integration notes.
Currently, the following data exports are available:
| Report name | Format | Configuration | Description |
|---|---|---|---|
| Transaction Export Summary | transaction-export_YYYYMMDD.csv: YYYYMMDD - the date when the report was exported | Merchant level | The purpose of this report is to export transaction totals for all transaction types and brands for a particular account. It can be used to reconcile processing totals across multiple systems. |
| Deposit Export | deposit-export_YYYYMMDD.csv: YYYYMMDD - the date when the report was exported | Portfolio level | The purpose of this report is to simplify the reconciliation of transactions and deposits across multiple systems. It includes Transaction Export report data and deposit information. |
| Deposit List | depositList.[entityCode].YYYYMMDD.1.csv: entityCode - identifier of a reseller/portfolio for which the report is exported; YYYYMMDD - the date when the report was exported; 1 - the file sequence number of a file. As this report is exported three times a day, the sequence number range can be from one to three. | Portfolio level Reseller level | The purpose of this report is to export a list of amounts deposited to and withdrawn from the merchants associated with a particular reseller or portfolio. |
| Merchant Statement Export | merchantStatementExport.[entityCode].YYYYMMDD.1.1-200.zip: entityCode - identifier of a reseller/portfolio for which the archive with a collection of statements is exported; 1 - a sequence number of a file; 1-200 - quantity range defining the number of the PDF statements contained in a ZIP archive | Portfolio level Reseller level | The purpose of this report is to export merchant statements received from a processor for the merchants associated with a particular reseller or portfolio. The report is exported as a ZIP archive with the statements in PDF. The number of the included statements is limited to 200 files. When the maximum number of the PDF files is reached, a new archive is generated. |
| Merchant Statement List | merchantStatementExport.[entityCode].YYYYMMDD.1.1-200.zip: entityCode - identifier of a reseller/portfolio for which the archive with a collection of statements is exported; 1 - a sequence number of a file; 1-200 - quantity range defining the number of the PDF statements contained in a ZIP archive | Portfolio level Reseller level | The purpose of this report is to export merchant statements received from a processor for the merchants associated with a particular reseller or portfolio. The report is exported as a ZIP archive with the statements in PDF. The number of the included statements is limited to 200 files. When the maximum number of the PDF files is reached, a new archive is generated. |
Tokenization Concept
Tokenization
See What is it? page for more information about Tokenization.
TidyPay provides a simple and convenient tokenization mechanism for merchants that deal with recurring payments and want to avoid storage of customer’s payment information (credit card and bank account numbers) within their own system. When a merchant uses any given credit card or bank account for the first time (as part of authorization, sale or credit operation), TidyPay will generate a unique identification number (token) associated with this payment information. If in the future, the merchant wants to issue another operation (e.g. another sale) on the same credit card or bank account, it is sufficient to pass to TidyPay just the value of the previously generated token and omit all of the account information fields.
TidyPay provides a simple and convenient tokenization mechanism for merchants that deal with recurring payments and want to avoid storage of customer’s payment information (credit card and bank account numbers) within their own system. When a merchant uses any given credit card or bank account for the first time (as part of authorization, sale or credit operation), TidyPay will generate a unique identification number (token) associated with this payment information. If in the future, the merchant wants to issue another operation (e.g. another sale) on the same credit card or bank account, it is sufficient to pass to TidyPay just the value of the previously generated token and omit all of the account information fields.
Token Structure (Extended)
As well as simple token structure, extended structure enables integrators to easily derive information needed for reporting or system maintenance from the token itself.
For example, XVC01S0000000099990000014426594111001111.
For example, XVC01S0000000099990000014426594111001111.
| # | Name | Type | Description |
| 1 | Token Format | String(1) | Identifier of the extended format (always X). |
| 2 | Account Type | Enum(2) | Type of account. See possible values for more information. |
| 3 | Sequence Number | String(2) | For bank accounts only. Sequence number assosiated with the underline account number for cases when account number is not unique. For example, the same account number is used in different banks. |
| 4 | Tokenization Origin | Enum(1) | Identifies the system, underlines system, that generates the stock. See possible values for more information. |
| 5 | Bank Identifier | String(7) | Identifier of a bank that issue the credit card or that holds a bank account. |
| 6 | Reserved for Future Use | String(1) | |
| 7 | Account Number | String(16) | Tokenized account number. |
| 8 | First Four Digits | String(6) | The first four digits of credit card or bank account number (the last two digits of this value are reserved). |
| 9 | Last Four Digits | String(4) | The last four digits of credit card number or bank account number. |
Token Structure (Simple)
A token generated by the gateway is comprised of 3 logical parts:
For example, a card number 4111111111111111 will be tokenized as VC84632147254611111111, where:
This structure enables integrators to easily derive information needed for reporting or system maintenance from the token itself.
- two-letter account type (see possible values for more information);
- tokenized account number;
- the last 4 digits of the actual account number.
For example, a card number 4111111111111111 will be tokenized as VC84632147254611111111, where:
- VC is the Visa account type;
- 8463214725461111 is a tokenized account number;
- 1111 are the last 4 digits of the actual card number.
This structure enables integrators to easily derive information needed for reporting or system maintenance from the token itself.
Profiling
In this case token is associated with an internal account profile, which in addition to account number can contain other account information (for example, holder name, expiration date, routing number, address information). When transaction request is submitted, fields from the profile can be automatically used if they were not specified as part of the request. The disadvantage of the profiling approach is that profiles have to be updated if the customers’ information is changed, in particular the following fields:
- accountAccessory
- holderName
- isOrganization
- street
- city
- state
- zipCode
- countryCode
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.