Introduction
The purpose of this guide is to provide the insight into the most common issues around realtime/
batch transaction processing that may occur while working with the gateway. The guide explains the context of every described issue and the way how to troubleshoot each problem using user interface and rarely database. So once you faced the issue, described here, just follow troubleshooting steps to resolve it in a right way.
Intended Audience
This guide will be useful for administrative users that want to know how to deal with common processing issues.
Overview
The guide is designed to help to troubleshoot the most common problems. It assumes that you have familiarized yourself with the following materials:
The guide is designed in the following way:
- it is divided into typical issues that might arise;
- each section, defining the issue, starts with the overview of a problem;
- overview is followed by the list of the skills that you have to absolutely have;
- skills section is followed by the specific rules that need to be applied as you do your reasoning;
- rules are followed by procedures that are recommended to follow to be able to diagnose the issue in the most efficient fashion. The procedure can include references to SQL query that you need to be able to execute (therefore, we assume that you have basic knowledge of SQL language);
- the procedures also include directions how to properly submit the request to the support team so help can be provided in a most highly efficient manner.
Use Cases
In this section we will review the most common cases that need to be resolved within the gateway.
Note that to resolve the issues below,
Monitoring perspective is advised to be used.
Duplicate Realtime/Batch Transactions
There can be cases when one or more transactions are suspected to have duplicates within the system.
Rules
- Search should be performed across all merchants in the system. This will allow to locate transactions associated with a customer within the entire system as sometimes duplicates may be caused by a transaction submission to different merchants. If search is performed through the user interface, make sure that all merchants are selected within your merchant selection on the perspective that you work with (review respective tutorial in Skills section). If search is performed in the database, make sure that you do not put any conditions that would limit the range of merchants that the search is performed on (asterisk (*) symbol should be used in a query).
- If you can’t find a customer by their full name, try to search by the last name only.
- If a duplicate transaction was located, transaction codes and transaction time of the suspected duplicates should be compared. If these values are different, it means that a merchant submitted the transaction twice for this customer.
Procedures
To investigate and resolve this issue, the following information should be present:
- Сustomer Name / Last Name
- Last 4 digits of a credit card or bank account
- Token
- Transaction date
- Transaction amount
Customer name and last 4 digits of a credit card or bank account will allow to locate all transactions associated with this customer. Also, those values are needed to get a respective token for further search if needed.
On the user interface, the research can be performed using Transactions form, which is available at three places:
The following steps should be followed to investigate and resolve the issue:
1) To locate transactions by a customer’s name and last 4 digits of a credit card or bank account:
- Locate all transactions associated with a provided customer’s name and last 4 digits of a credit card or bank account. See respective tutorial in Skills section.
- If duplicates were located, compare their transaction codes and transaction time. See Rules section for reference.
If no transaction was located,
further research should be performed with a token associated with a payment option.
2) To locate transactions by a token associated with a customer:
- If a token was not initially supplied, it should be extracted from the transaction details of any transaction associated with a customer’s payment option (View Transaction form should be used).
- Locate all transactions associated with a provided customer’s token. See respective tutorial in Skills section.
- If duplicates were located, compare their transaction codes and transaction time. See Rules section for reference.
If no transaction was located,
further search should be performed in the database.
3) To locate transactions by a token associated with a customer in the database:
- The search has to be performed within unicharge database in the charge_transaction table.
- For making search by token, your query will look similar to this:
SELECT * FROM charge_transaction WHERE
TOKEN='token value'
- If no records were found by token, continue your search with last 4 numbers of a card or account number and customer’s name. Your query will look similar to this:
SELECT * FROM charge_transaction WHERE
ACCOUNT_NUMBER_LAST4=’LAST 4 digits OF a card/bank account VALUE’ AND HOLDER_NAME LIKE ‘%{holder’s name}%’
- If duplicates were located, compare their transaction codes and transaction time. See Rules section for reference.
If no duplicates were found within the system, the
issue should be addressed to a processor for further investigation.
4) To investigate the issue on a processor’s side:
Provide a processor with all necessary information. The following information should be supplied:
- Merchant ID (comes from Provider profile)
- Сustomer Name
- Last 4 digits of a credit card or bank account
- Transaction date (including time)
- Transaction amount
If you have performed all of the suggested procedures and still believe that the duplicates are present,
address the issue to the gateway support.
5) To address the issue to the gateway support:
Provide the support team with full information. The following information should be supplied:
- Transaction ID/Reference Number
- Merchant ID
- Holder Name
- Transaction amount
- All queries that you ran
Batch File Mistakenly Processed Twice
There can be cases when a
batch file is submitted for processing twice by mistake and all associated customers are billed twice. In this case a batch file with credits reversing incorrectly processed sale transactions needs to be submitted. The system allows to do this using the user interface.
Rules
- If you don’t know a merchant code of a merchant that has the issue with duplicate batch submission, perform your search across all merchants. See respective tutorial in Skills section.
- If credits are issued correctly, a new sub-batch is generated. All sale transactions included in the newly-created sub-batch will have Refund status.
- If a duplicate file contains sale transactions, these transactions will be reversed as refunds. Refund transactions from the initial batch will not be affected in any way – no new credits or sales will be created.
- No response file is generated for a new sub-batch with credits.
Procedures
To investigate and resolve this issue, the following information should be available:
- Submission date
- Batch ID
- Merchant code (all merchants as a search criteria can be used)
On the user interface, credits can be issued using Sub-batch form, which is available at three places:
The following steps should be followed to resolve the issue:
1) To issue
credits for a duplicated
batch file:
- Locate a sub-batch that includes duplicate transactions by its submission date/name/batch ID/merchant code. See respective tutorial in Skills section.
- Locate a newly-created batch and review the status of included transactions. See respective tutorial in Skills section and Rules section for reference.
If
no sub-batch was created or the status of the transactions in a newly-generated sub-batch is
not Refund,
address the issue to the gateway support.
2) To address the issue to the gateway support:
Provide the support team with full information. The following information should be supplied:
- Submission date
- Sub-batch ID
- Merchant code
- The result of the query that will locate all sub-batches associated with a duplicate batch. The query should look similar to this:
SELECT * FROM sub_batch WHERE
batch_fk = ‘batch ID VALUE’;
Request/Response/Returns File Downloading
There can be cases when a request/response/returns file that includes particular transactions is needed. The system allows to download a request/response/returns file using the user interface.
Rules
- If you don’t know a merchant code of a merchant that has the issue with twice submitted batch files, perform your search across all merchants. See respective tutorial in Skills section
- If no request/response/return file and no transactions associated with them were located using entered search criteria, then no file was initially submitted into the system
Procedures
To investigate and resolve this issue, the following information should be present:
- Transaction Code
- Transaction ID
- Request/response/return file name
- Submission date
- Merchant ID (all merchants as a search criteria can be used)
The research can be performed using FTP Gates/File Store forms that are available at two places:
The following steps should be followed to resolve the issue:
1) To download a request/response/return file:
- Locate a processed file by its file name/submission date/merchant ID/transaction code of a transaction included in it and download it. See respective tutorials and rules in Skills and Rules sections.
In case when
no request/response file was found,
verify that the system has no transactions associated with this file.
2) To locate transactions associated with a particular file:
- Locate a transaction associated with a file by its Transaction ID. See respective tutorial and rules in Skills and Rules sections.
If
no transaction was located,
further search should be performed in the database.
3) To locate a transaction by its Transaction ID in the database:
- The search has to be performed within unicharge module in the charge_transaction table.
- The query will look similar to this:
SELECT * FROM charge_transaction WHERE
REFERENCE_NUMBER='transaction ID value'
If
a transaction is present in the database while being absent on the user interface,
address the issue to the gateway support.
4) To address the issue to the gateway support:
Provide the support team with full information. The following information should be supplied:
- Transaction IDs
- The result of the query ran to locate transactions
File needs to be cancelled with/without response
There can be cases when a file was mistakenly submitted and it needs to be cancelled from further processing. In this case, the system allows to cancel a
batch in two ways – with or without response.
The system has a capability to cancel a file from the user interface. However, there might be situations when that logic fails to execute for whatever reason, and there is still a risk of a file getting processed. We are going first to review a standard procedure and then learn additional procedure that can be used in case when user interface manipulations did not produce desired outcome, and our file still might get processed.
Rules
- If a batch/sub-batch is in Pending status, it can be cancelled. All other statuses do not allow to cancel a batch/sub-batch
- You can cancel the entire batch or separate sub-batches included in it. For example, you can cancel processing only of card or direct debit transactions
- You can cancel a batch file in two ways: with a response file or without a response file to be generated
- If a batch was cancelled with response file, all included transactions will be returned with X01 (Cancelled by a Customer) response
- If a batch was cancelled with no response, merchant will not be notified about a file being submitted
- If all steps on having a batch/sub-batch cancelled were followed correctly, file’s status turns to Cancelled
Procedures
To resolve this issue, the following information should be present:
- Batch file name
- Submission date
- Merchant ID (all merchants as a search criteria can be used)
A batch can be cancelled using Batch List forms which is available at the following places:
A
sub-batch can be cancelled using Sub Batch List form which is available at the following places:
- Console perspective => Submissions => Batches => Batch List => View Batch
- Merchant perspective => Submissions => Batches => Batch List => View Batch
- Monitoring perspective => Sub Batch
The following steps should be followed to resolve the issue:
1) To cancel a
batch file:
- Locate a batch file by its name/submission date/merchant ID and cancel it. See respective tutorial in Skills section.
If only
a part of a batch file – card or direct debit transactions – needs to be cancelled,
canceling should be done on sub-batch level.
2) To cancel a
sub-batch:
- Locate a sub-batch by its name/submission date/merchant ID and cancel it. . See respective tutorial in Skills section.
If a status of a
batch/sub-batch was not turned to Cancelled, a file needs
to be cancelled in the database.
3) To cancel a batch in the database (no response will be generated):
- The status update has to be performed within unicharge database in the sub_batch table.
- The query will look similar to this:
UPDATE sub_batch SET REVIEW_CL='CANCELLED', STATUS='PROCESSED'
WHERE batch_fk=‘batch ID VALUE’;
If a
status of a batch was not changed to
Cancelled,
address the issue to the gateway support.
4) To address the issue to the gateway support:
Provide the support team with full information. The following information should be supplied:
- Batch ID
- Sub-batch IDs (if not the entire file needs to be cancelled)
- Query that was run
Direct debit verification file/notification was not received
There can be cases when a bank/processor or recipients have not received an direct debit verification file. In this case, the system allows to verify the status of verification file and resubmit it if needed.
We are going first to review a standard procedure of verifying a status of a verification file within the system and overview reasons of why verification can be not delivered or not present within the system.
Rules
- Verification of both direct debit and remittance file can be done in three ways:
- via phone call to the bank – gateway owner makes a call to provide file totals
- via email notification sent to the bank – gateway generates an email with a verification file totals and sends it to the bank or processor
- via a file generated and sent by the system – gateway generates a verification file with totals and uploads it along with an initial
batch file to the bank’s or processor’s SFTP
- If for some reason, a verification file was not received by the list of intended recipients, its status can be verified on the user interface. If a status of a verification file is Processed, it means that the file is present within the system and was supposed to be sent to the recipients listed in the processor’s profile
- If the file is available at the gateway, further investigation as to the reasons of why it was not received should be done. To confirm that the file was sent, logs have to be checked. Use server.log for this purpose. To make search effectively, search should be performed by one or more recipients’ emails. If it is located, the email was sent out of the gateway
- Reasons of why an email with totals was not received can be the following:
- an email went to the spam folder
- an email service that sends out emails of that kind does not work
- There can be cases when a verification file is not present within the system. Reasons of why a verification file is not present can be the following:
- direct debit processing cannot be done due to a weekend or a holiday
- an issue is present within the gateway
Procedures
To resolve the issue with a verification file not being received, the following information should be present:
- Batch file name
- Submission date/timestamp
- Merchant ID (all merchants as a search criteria can be used)
An direct debit verification file can be checked and resubmitted at the following places:
Logs can be checked at the following place:
- System perspective => Logs => Browse
The following steps should be followed to resolve the issue:
1) To check whether a verification file is present within the system:
- Locate a verification file by its name/submission date/merchant ID and check its status. See respective tutorial and rule in Skills and Rules sections
If a verification file is
not present within the system, go to the
section 3.
If a verification file
is present within the system,
server logs should be reviewed to check whether it was sent to the list of recipients
2) To check the logs within the system:
- Locate a respective log that should be browsed. See respective tutorial and rule in Skills and Rules sections
If an
email is shown as
sent, recipients should be asked to
verify a spam folder to locate the email. If an
email is
not sent,
availability of an email service should be checked. This should be addressed to the support team (go to
section 4).
3) If a
verification file is not present within the system and you know for sure that it should be,
logs needs to be checked:
- Locate a respective log that should be browsed. See respective tutorial and rule in Skills and Rules sections
After the
logs are verified, the
issue should be addressed to the support team.
4) To address the issue to the gateway support:
Provide the support team with full information. The following information should be supplied:
- Batch file name
- Submission date/timestamp
- Log extract that was browsed
Unknown System Error is Received
There are can be cases when a user enters some data incorrectly for some reason. This data may cause the S20 system error, which means that there is an issue that needs additional investigation on what triggered the error. To get a detailed information about the nature of the problem, an event ID is used. This ID is populated along with an error code and message.
Rules
- Event ID is available at two places: in an API response in square brackets and on the user interface in the bottom left of the error window
- Event ID contains the number of a node and the time (in milliseconds) when an exception was received. This data allows to search for the detailed information in the server logs
Procedures
To investigate and resolve this issue, the following information should be available:
- Error code and error message
- Event ID
- Transaction ID
On the user interface, a transaction can be located by an event ID using the Error Logs Search form, which is available at the following places:
Logs can be checked at the following place:
The following steps should be followed to investigate and resolve the issue:
1) To identify the transaction by an event ID:
- Locate the event ID in either API response or the user interface. See a respective rule in the Rules section.
- Copy the event ID.
- Locate the transaction by its event ID.
- Copy the transacion ID.
- Copy the exact of the transaction.
2) To analyze the logs:
- Download the server log. See a respective tutorial in the Skills section.
- Locate the error by the timestamp and transaction ID.
- Identify the stack trace associated with the transaction and analyze it to find the nature of the error.
If the analysis of the stack trace does not help identify the reason of the error,
address the issue to the gateway support.
3) To address the issue to the gateway support:
Provide the support team with full information. The following information should be supplied:
- Transaction request/response
- Transaction ID
- Event ID
- Stack trace
