Table of Contents
- Overview
- Differences between CardEase and ONE
- Operation Flow
- HTTP Headers
- URI Path
- HTTP Methods
- Recovery Action
- Request and Response Elements
Overview
NMI Direct Connect has enhanced gateway connection messaging to assist with communication issues. The messaging better synchronises the integrating application with our platform. Therefore, should the integrators network drop, the transaction result has a higher chance of being returned to the integrating application. Failing this, the transaction will automatically be voided allowing the integrator to carry out a retry.
When processing transactions through NMI Direct Connect, additional messaging below needs to be implemented to better handle loss of communications during a transaction. There are three types of messages summarised below. The stages should be used for both first and second stage operations such as Authorizations, Confirms, Voids. If a response message cannot be obtained following a request then an exception will be thrown with the appropriate recovery action (e.g. void, retry or no action required) when using an SDK containing the enhanced messaging. If doing a direct XML integration, this will need to be handled by your application as documented below.
Differences between CardEase and ONE
There are differences between how Enhanced Gateway Connection Messaging is implemented depending on which of our two platforms you are integrated into. Please pay close attention to this symbol ⚠ throughout this document, in places that it is indicated you will need to adjust your implementation to the platform in which you are integrated with.
Operation Flow
| Stage | Description | Example |
|
Stage 1a Perform Operation Token HEAD Request |
⚠ A token is requested from the platform by performing a HEAD request to
|
CardEaseV2-TerminalID ------------------------------> ⚠ '**API Key or Terminal ID**' |
|
Stage 1b Successfully process Operation Token Response |
The operation token is retrieved from the response headers. It will be required for the subsequent stages. |
CardEaseV2-OperationToken <------------------------------ AfGXdJbTXBHnu2UAUFaddPXxl3SW |
|
Stage 2a Perform Operation POST Request |
⚠ The operation (e.g. an auth, void, confirm, refund etc.) request is performed by performing a POST request to /gwdirect.cex (ONE) or /generic.cex (CardEase), with additional headers set. |
CardEaseV2-TerminalID ------------------------------> ⚠ '**API Key or Terminal ID**' |
|
Stage 2b Successfully process response |
A NMI Direct Connect response will If a response cannot be obtained |
NMI Direct Connect Response <------------------------------ <?xml version="1.0" encoding="us-ascii"?> <Response type="CardEaseXML" version="1.5.0">... |
|
Stage 2c
|
If the integrating application doesn’t receive a response from Stage 2b (e.g. communication issue) our platform can be queried for the response at set intervals by performing a GET request to /operation.cex. |
CardEaseV2-TerminalID ------------------------------> ⚠ '**API Key or Terminal ID**' |
|
Stage 3a Perform Operation Notification POST Request |
Our platform must be notified that the operation response was successfully received by sending a POST request of “OK” (2 bytes) in the body to /operation.cex
|
CardEaseV2-TerminalID ------------------------------> ⚠ '**API Key or Terminal ID**' |
|
Stage 3b Process Operation Notification |
If the notification operation is successful, a message-body of OKwill be returned with a HTTP status code of 200. |
<------------------------------ 'OK' |
HTTP Headers
All stages make use of custom HTTP headers within the request and responses to our platform. The following describes the headers required for each request made by the integrating application.
| Header | Request Stage | Description | Example |
| CardEaseV2-TerminalID | All | ⚠ NMI API Key (ONE) or NMI Terminal ID (CardEase). | ⚠ '**API Key or Terminal ID**' |
| CardEaseV2-TransactionGUID | 2/3 | The CardEase reference GUID. Only required if performing a follow-up operation (e.g. Void, Confirm, Refund by Reference etc.). | d1012e66-76d a-e711-a166- 0050569277e2 |
| CardEaseV2-OperationToken | 2/3 | A signed token returned in the Stage 1b response headers. | AfGXdJbTXBHn u2UAUFaddPXx l3SW01wR57tl AFBWnXT1xaOh 1oA11Uh4AAAA dPe1ZdNREeaK aAAiGWntSH5R NLg= |
| CardEaseV2-OperationGUID | 2/3 | A GUID returned within the response for the current operation being performed. When performing a secondary operation such as a Void or Confirm, it needs to be included within the request header. | d1012e66-76d a-e711-a166- 0050569277e2 |
URI Path
The enhanced messaging operations use the /operation.cex URI path combined with the HTTP methods and above HTTP headers.
URL for staging: https://test.cardeasexml.com/operation.cex
URL for production: https://live.cardeasexml.com/operation.cex
HTTP Methods
| HTTP Method | Description |
| HEAD | Stage 1a – Request to /operation.cex to retrieve the operation token |
| POST |
⚠ Stage 2a – Request to Stage 3a – Request to |
| GET | Stage 2c - Poll request to /operation.cex
|
Recovery Action
In the event of a communication failure, a recovery action should be returned as follows:
| Stage | Request Type | Result Code | Recovery Action |
| 1 & 2 | Partial Confirm Confirm Update Void Event |
Retry | |
| 3 | Authorization Offline Authorization Refund Voice Referral Notification |
Result Code != Approved or PartialApproval |
None Only need to try and void if the original transaction was approved/partially approved |
| 3 | Authorization Offline Authorization Refund Voice Referral Notification |
Result Code == Approved or PartialApproval |
Void |
| 3 | Partial Confirm Confirm Update Void Event |
Retry |
Request and Response Elements
Stage 1a – HEAD Request Operation Token
You must first retrieve a token from our platform which will be used to track the current operation from start to finish. This token is known as the Operation Token.
Request
| HTTP Request Header | Value | Requirement |
| CardEaseV2-TerminalID |
⚠ NMI API Key (ONE) or NMI Terminal ID (CardEase) |
Mandatory |
| CardEaseV2-TransactionGUID | Original GUID | Mandatory for follow-up operations |
Response
| HTTP Request Header | Value | Requirement |
| CardEaseV2-OperationToken | Operation Token | Always |
| CardEaseV2-OperationGUID | Operation GUID | Always |
Submit the HTTP HEAD request to the “/operation.cex” URI path.
Stage 1b - Retrieve Operation Token
If no response is received or the token could not be retrieved, you will need to retry the operation.
Stage 2a – Perform POST Operation
The second stage is to perform an operation such as an Auth, Void or Confirm as documented in section 6 – protocol. The only difference being extra HTTP headers included within the request and responses from our platform.
Request
| HTTP Request Header | Value | Requirement |
| CardEaseV2-TerminalID |
⚠ NMI API Key (ONE) or NMI Terminal ID (CardEase) |
Mandatory |
| CardEaseV2-OperationToken | Operation Token | Mandatory |
| CardEaseV2-TransactionGUID | Original GUID | Mandatory for follow-up operations |
| CardEaseV2-TransferMode | polled | Mandatory If this header is not set then the platform will default to not polled |
| CardEaseV2-TransferModePullIntervalTimeout | 5000 Min: 2000 Max: 45000 |
Optional If this header is not set then the platform will default to 5 seconds |
Submit the HTTP POST request to the /gwdirect.cex (ONE) or /generic.cex (CardEase), URI path.
If no request is sent (failed whilst submitting the request), no recovery action is required for an authorization. If performing a secondary operation such as a Confirm or Void, the request needs to be retried.
“CardEaseV2-TransferMode:polled” notifies our platform that the integration application will be polling the platform and expects a request within 5 seconds by default. The polling interval set is an integer such as “10000” for 10 seconds.
Please note - the interval for the polling must not change during the operation. We recommend using the default 5 seconds or 10 seconds at the very least.
Stage 2b – Retrieve Operation Response
If no communication issues occur, our platform will return a response within the message-body containing operation information. You need to notify our platform the response was successfully received (Stage 3).
If retrieving a response was not successful then you must poll the platform to query for the response (Stage 2c).
Stage 2c – GET Request Poll for Response
You should poll the platform for at least 30 seconds and up to 45 seconds before the operation times out on the platform.
Request
| HTTP Request Header | Value | Requirement |
| CardEaseV2-TerminalID |
⚠ NMI API Key (ONE) or NMI Terminal ID (CardEase) |
Mandatory |
| CardEaseV2-OperationToken | Operation Token | Mandatory |
Submit the HTTP GET request to the “/operation.cex” URI path.
Our platform needs to be polled at the interval set within the CardEaseV2-TransferModePullIntervalTimeout header that was set in Stage 2a. If the connection is still open but the operation response is not yet available on our platform, an empty message-body will be returned with the HTTP status code 200. The polling should continue until the message-body containing operation information is returned, a HTTP status code of 200 is no longer returned or 45 seconds has passed.
A HTTP status code of 404 NotFound will be returned if the operation request doesn’t exist on the platform or if stage 3 (below) has been performed for the operation in question.
You need to notify our platform if the response was successfully received (Stage 3).
Stage 3a – Perform Operation Notification POST Request
The third stage is to notify the platform that the operation response was successfully received. If our platform does not receive this notification then the operation will be reversed.
Request
| Body | HTTP Request Header | Value | Requirement |
| OK | CardEaseV2-TerminalID |
⚠ NMI API Key (ONE) or NMI Terminal ID (CardEase) |
Mandatory |
| OK | CardEaseV2-OperationToken | Operation Token | Mandatory |
Submit the HTTP POST request to the “/operation.cex” URI path.
Stage 3b – Process Operation Notification Response
If the notification operation is successful, a message-body of OK will be returned with a HTTP status code of 200 OK. After receiving this response, any further attempts to notify our platform for the current operation will fail and you will receive a HTTP status code of 404 NotFound.
If a HTTP status code 200 OK is not returned, a Void request needs to be sent to our platform using the GUID returned in the initial operation header CardEaseV2-OperationGUID. The Void needs to be sent once communications are available to ensure the integrating application remains in sync with our platform and the transaction is in a Voided state. See section 6 – protocol for more information on performing Voids.