Table of Contents
- Overview
- Failed Confirm Retry
- Force TMS Button
- Transaction State Monitoring
- Regular Transaction Reconciliation
- Use CTIP
- Logging
- Staged Rollout
- Root Certificates and Revocation Checking
Overview
This article walks through the top integration recommendations NMI suggests integrating into your solution. If you have any questions about the topics in this article, please reach out to NMI support and one of our agents will be happy to assist you in your inquiries.
Important Information
Goods/services should only be provided to the end customer if an “Approved” result code is returned for an authorization and confirmation. This means both the authorisation and confirmation have successfully been processed and therefore the funds for the transaction will be sent for settlement to the merchant. If an approval isn’t received for the confirmation, it means there was an issue with the confirmation and the transaction will not be sent for settlement. The merchant will not receive the funds for this transaction until you receive an “Approved” result code for the confirmation. We recommend waiting for an approval for both the authorization and the confirmation stage before providing goods/services to an end customer. Providing goods/services to an end customer after the authorisation has approved but before the confirmation is approved will put the transaction at risk of not being funded to the merchant.
Failed Confirm Retry
ChipDNA SDKs have a two-step process for completing a transaction. Transactions first need to be authorized for a specific amount, and once the authorization is approved, the transaction must be confirmed in order for the transaction to be settled into the merchant account. Transactions that are not confirmed will not be settled and the merchant will not receive funds for the transaction.
One common issue integrators see around the confirm transaction process is that their integration does not check for failed confirm requests due to the device not having an internet connection or other communications problem. It is essential that failed confirm requests be retried until a result of Approved or Declined is returned. Please see the code examples below on how this could be carried out. The merchant will not receive funds until both an Approved authorization and confirmation is received.
Windows & Linux
If the TransactionResult of a confirmation attempt returns with the value of RetryFailedRequest, you must create a process that retries the failed request until the TransactionResult returned is either Approved or Declined.
if (response.GetValue(ParameterKeys.TransactionResult, out result))
{
Console.WriteLine("Confirmed Transaction Result: {0}", result);
if (result.Equals("RetryFailedRequest"))
{
//IMPORTANT TODO: Integrator should build out a process that retries failed Confirm requests
Console.WriteLine("This Confirm request has failed and will need to be retried in order for the transaction to be sent for settlement.");
}
}
Mobile: Android (API Release >= 2.05)
if (response.containsKey(ParameterKeys.Error)) {
log("Errors: " + response.getValue(ParameterKeys.Error));
if (response.getValue(ParameterKeys.Error).contains("ServerCommunicationError"))
{
//IMPORTANT TODO: Integrator should build out a process that retries failed Confirm requests
log("This Confirm request has failed and will need to be retried in order for the transaction to be sent for settlement.");
}
}
Mobile: iOS (API Release >= 2.05)
if ([[response valueForKey:CCParamError] isEqualToString:@"ServerCommunicationError"]) {
//IMPORTANT TODO: Integrator should build out a process that retries failed Confirm requests
[self log:@"This Confirm request has failed and will need to be retried in order for the transaction to be sent for settlement."];
}
Force TMS Button
The payment configuration of an EMV transaction is delivered, amongst other essential configuration and updates, via the TMS (Terminal Management System) platform. Many problems can be resolved by ChipDNA downloading an up-to-date copy of its configuration from the TMS platform.
Whilst ChipDNA WinLin solutions automatically attempt to perform a TMS update every 24-48 hours, we would recommend integrating a method to allow a merchant to perform a manually forced TMS update, typically hidden in an accessible menu so should the need arise an update can be performed to apply new settings. We recommend this be labeled as "Force TMS".
Please note that ChipDNA Mobile solutions do not automatically perform TMS updates, and the occurrence of such updates is the responsibility of the integrator to configure.
Please see the following Knowledge Garden articles on how to implement and integrate a forced TMS procedure:
Windows & Linux
Mobile (Release >= 2.05)
Mobile (Release <= 1.19)
Transaction State Monitoring
All transactions must be explicitly confirmed or voided. It is the responsibility of the integrator to track the state of a transaction, ensuring that when an authorization processed it is either confirmed or (if not intended for settlement) voided.
It is imperative that integrators track the state of transactions all the way through the transaction lifecycle to ensure transactions are not left in limbo. If a transaction is not explicitly confirmed then the transaction will not be settled and the underlying merchant will not be funded for the transaction. A merchant may have exchanged goods or services with a customer but will not receive payment.
Flush Transaction Queue (Offline Transaction Support)
Monitoring the state of offline transactions is especially important if your integration uses any offline or deferred authorization capabilities. Communication and other issues may result in offline or deferred transactions pending locally rather than being uploaded to the payment gateway. If this happens then merchants will not receive funds for the transactions that have been processed offline.
The integrator should implement functionality to manually send any authorizations stored offline to our payment gateway and confirm any uncommitted transactions.
It is also recommended to build in logic to limit the number of offline/deferred authorizations performed. This is to prevent a large number of transactions being stuck offline resulting in the merchant not being funded and losing money.
Windows/Linux
The integrator should implement functionality to confirm all transactions and any transactions in the request queues.
It is the responsibility of the integrator to ensure the transaction state is tracked and transactions are submitted to our platform for settlement. Any failed confirmation attempts should be logged and retried until our platform states the operation was approved or declined.
In ChipDNA Windows/Linux, the integrator can call the GetTransactionInformation() method along with the transaction user reference to retrieve the transaction state. If a transaction is not committed/confirmed or is partially committed/confirmed the transaction should be confirmed explicitly with the ConfirmTransaction() method.
Mobile API (Release >= 2.05)
The new mobile API is more in-line with the ChipDNA Windows/Linux solution by separating out the Authorization and the Confirm message. Please ensure you monitor the offline transaction statistics (see below section) to ensure all of your transactions are being pushed up to our platform successfully. It is the responsibility of the integrator to ensure all transactions have been submitted to our platform for settlement and are confirmed. If a confirm fails, the integration needs to retry the confirm until the platform approves or declines it.
Mobile API (Release <= 1.19)
The heritage API automatically confirms transactions for you. Please ensure you monitor the offline transaction statistics (see below section) to ensure all of your transactions are being pushed up to our platform automatically. It is the responsibility of the integrator to ensure all transactions have been submitted to our platform for settlement and are confirmed/committed.
Offline Transaction Statistics (Reporting)
ChipDNA Windows/Linux and ChipDNA Mobile both contain request queues that can be used by the integrator to track the state of an offline transaction. This queue will contain information on the total number of requests and the total amount stored on the device for both pending transactions and failed transactions. If any of these queues are non zero then it means that transactions or operations around transactions are pending locally and have not been uploaded to the payment gateway. This may indicate a problem with connectivity and means the client is out of synchronization with the payment gateway.
Without flushing these queues, merchants may not see transactions funded by their Processor or these transactions reflected correctly in WebMIS. We recommend a cautious approach to queue management and if more than x operations exist in TotalRequestCount then the device should stop processing transactions via ChipDNA until the problem is resolved.
ChipDNA Windows/Linux
ChipDNA Windows/Linux utilizes the RequestQueueStatus class to provide information on stored transactions, confirmations, and voids. The following information is available:
CreditConfirmRequestCount - The number of confirmed refund requests in the queue. CreditRequestCount - The number of refund requests in the queue. CreditVoidRequestCount - The number of voided refund requests in the queue. DebitConfirmRequestCount - The number of confirmed auth requests in the queue. DebitRequestCount - The number of auth requests in the queue. DebitVoidRequestCount - The number of voided auth requests in the queue. TotalRequestCount - The total number of requests in the queue.
Mobile API (Release >= 2.05)
It is important the integrator manages the transactions in both the pending and failed queue to ensure all transactions either get submitted to our platform for settlement or get discarded from the device if no longer required.
Mobile API (Release <= 1.19)
It is important the integrator manages the transactions in both the pending and failed queue to ensure all transactions either get submitted to our platform for settlement or get discarded from the device if no longer required.
Regular Transaction Reconciliation
It is extremely important that the merchant regularly reconciles any transactions processed to ensure the full transaction amounts and the number of transactions are being funded into their account as expected.
Bank Submission Report
With WebMIS, it is possible to run a bank submissions report. This will contain all transactions that have been sent by NMI to the bank for settlement. For more information on how to run this report, please refer to this Knowledge Garden article.
All Transactions Report
Within WebMIS, you can also run a transaction report that will break down every single transaction that has been sent by your integration to our platform. This report is useful should you need a more detailed overview of all of the transactions you’ve performed. For more information on how to do this, please refer to this Knowledge Garden article.
If specific transactions are not appearing on WebMIS, this could be due to one of the following:
- There are transactions stored in your local queue (ChipDNA)
- There was an error where our platform denied the transaction request which should have returned an error in the response e.g. using an incorrect terminal ID
- The transaction was declined locally by the terminal
ChipDNA Report
When integrating ChipDNA, we strongly advise creating your own reporting for all transactions attempted. If the bank submission report isn’t as expected, the merchant can then compare the transactions performed via ChipDNA (the expected amount to settle) against a report from your acquirer/processor (the actual amount settled).
Should you have any concerns during reconciliation, please ensure you raise this with NMI support as soon as possible so we can investigate the potential causes.
Use CTIP
With every new release of ChipDNA Windows/Linux, Android, and iOS, we now include the Creditcall Terminal Integration Process (CTIP) document. CTIP has been implemented to ensure integrators maintain a consistent quality of ChipDNA for Windows/Linux and ChipDNA Mobile integrations. Various test cases are documented to cover common requirements when integrating our ChipDNA solutions.
All new integrations should be fully tested against CTIP. When updating your solution, you should retest with CTIP to ensure regressions haven’t been introduced. When changing ChipDNA version, CTIP should be used again.
If you require any further clarification, please contact NMI support.
Logging
ChipDNA Windows/Linux
ChipDNA Windows/Linux creates a log file where the ChipDNA Server is located/stored. This will be within the "/../ChipDNA Server/logs" directory. The log contains useful information when trying to debug issues from device connectivity to the flow of transactions. It is important that the ChipDNA log files are easily accessible should any issues occur that NMI needs to investigate. We'd suggest having the ability to remote into the machine and access the log file remotely rather than needing someone locally on-site to retrieve the log and get it sent over.
ChipDNA Mobile
ChipDNA Mobile provides error and process codes. We'd recommend implementing your own device logging, as mobile devices often differ from one to another, and making it easily accessible. This should include any method calls, callbacks/events, error codes and process codes to assist any investigations we need to make. Please also ensure transaction information is logged, such as the masked card details, transaction amount, approval status, etc.
Staged Rollout
Ensure any new integrations or changes to existing integrations are suitably tested in a closed, staging environment before any major rollout (please reference the CTIP section above for how to test your integration thoroughly). Follow the testing procedure and ensure repeatability before moving to an isolated and small live environment, where you (the integrator/customer) can react to, and investigate, any unforeseen issues, mitigating the potential for any losses.
Continued testing against the CTIP whilst moving forward with a staged rollout will ensure smooth operation, mitigating against potential issues, and provide an excellent user experience.
Root Certificates and Revocation Checking
ChipDNA solutions require our current live services root certificate to be installed on the host device and that revocation checks can be performed against the relevant services.
ChipDNA Windows/Linux
1) Firstly, ensure you test connectivity to the NMI gateway by opening the following URL in Internet Explorer, which should display POOL_UP if successful:
https://tms.cardeasexml.com/ultradns
https://live.cardeasexml.com/ultradns
2) Ensure the DigiCert Root Certificate is installed in the certificate store. For more information on how to do this on Windows and Linux, please check the relevant linked articles.
3) The Revocation Cache can become corrupted and this would occur when the file is being written to and ChipDNA is closed unexpectedly (such as the PC shutting down, or ChipDNA Server is force-closed). To resolve the issue on the machine, please contact NMI support and provide log files so we can investigate for you and provide further instructions on how to resolve.
4) Ensure firewalls are not blocking either the CRL or OCSP URLs. Certificate Authorities (CAs) are required to track any SSL Certificates they revoke. After the Certificate Authority (CA) revokes an SSL Certificate, the serial number of the certificate is added to a Certificate Revocation List (CRL).
Online Certificate Status Protocol (OCSP) has largely replaced the use of CRLs to check if a certificate has been revoked. Instead of downloading a file (CRL), a client will query the issuing CA's OCSP server using the certificate's serial number and the response will indicate whether the certificate has been revoked or not.
5) Check whether you need to proxy CRL and OSCP requests on a strict network. The configuration below can be added to the ChipDNA Server config to set up a proxy for the Revocation Checks. This will allow you to perform the Revocation Checking through our platform instead of connecting to the IPs directly. This is supported in ChipDNA v1.18+. Please note ChipDNA 2.04+ automatically proxies the revocation checks through our platform.
<ChipDnaServer version="1.0.0">
<CrlProxy uri="https://live.cardeasexml.com/crl.cex" timeout="10000">true</CrlProxy>
<OcspProxy uri="https://live.cardeasexml.com/ocsp.cex" timeout="10000">true</OcspProxy>
For more information on failing revocation checks, please refer to this Knowledge Garden article.
ChipDNA Mobile
1) Firstly, ensure you test connectivity to the NMI gateway by opening the following URL in your default operating system internet browser, which should display POOL_UP if successful:
https://tms.cardeasexml.com/ultradns
https://live.cardeasexml.com/ultradns
Mozilla Firefox, Google Chrome, and Apple Safari have their own certificate store, and therefore, aren't suitable for this test.
2) Ensure the DigiCert Root Certificate is installed in the certificate store. Please note that iOS devices manage all certificates themselves through the iOS Trust Store. More information on the iOS Trust Store can be found here.