NMI Payments - Launch payments fast with NMI's developer experience. | Product Hunt
Guides
Explore SandboxPartner PortalMerchant Portal
Start typing to search…

AsyncStatus Polling

Suggest Edit

If you are integrating to the "asynchronous" version of transaction processing, you will need to use this endpoint to determine whether or not the consumer's interaction with the POI device has completed or not and whether or not the transaction was successful. Using the 'async_status_guid' value you received in an asynchronous transaction response, you can send requests and receive a JSON response.

Endpoint

https://secure.networkmerchants.com/api/asyncstatus

Headers

Every API request must be authenticated using HTTP Bearer Authentication header

Authorization: Bearer {MERCHANT_API_KEY}

Poll against an Asynchronous Transaction

Using the GUID returned in the 'async_status_guid' on an asynchronous transaction request, perform a GET to receive back JSON formatted response with the most up to date status of the transaction as the customer is interacting with the POI Device.

GET /api/asyncstatus/:asyncStatusGuid

Parameter

Type

Required

Description

asyncStatusGuid

string

yes

The async_status_guid returned from the transaction response. Example: 04249b3a-02f9-4838-b7b5-2bef4d4e7f7d

responseMethod

string

no

The type of response you wish to see returned. Set to'synchronous' to wait for a final transaction ID. Set to'asynchronous' to receive inFlight async status responses.

Default: 'asynchronous'Values: 'synchronous' or 'asynchronous'

Example: 'synchronous'

Example Request without Response Method:

curl --request GET --header "Authorization: Bearer {MERCHANT_API_KEY}"
            "https://secure.networkmerchants.com/api/asyncstatus/70a6272c-4949-4515-956a-6e5ae4d5a10c"

Example Request with Asynchronous Response Method:

curl --request GET --header "Authorization: Bearer {MERCHANT_API_KEY}"
            "https://secure.networkmerchants.com/api/asyncstatus/70a6272c-4949-4515-956a-6e5ae4d5a10c?responseMethod=asynchronous"

Example Response without Response Method/with Asynchronous Response Method:

While the transaction is in progress or 'in flight', the responses will return with little information other than the platform ID and status.

{
   "transaction": {
       "id": null,
       "success": false,
       "condition": "",
       "authCode": ""
   },
   "platformId": "70a6272c-4949-4515-956a-6e5ae4d5a10c",
   "asyncStatusGuid": "70a6272c-4949-4515-956a-6e5ae4d5a10c",
   "asyncStatus": "inFlight"
}

Example Request with Synchronous Response Method:

curl --request GET --header "Authorization: Bearer {MERCHANT_API_KEY}"
            "https://secure.networkmerchants.com/api/asyncstatus/70a6272c-4949-4515-956a-6e5ae4d5a10c?responseMethod=synchronous"

Example Response with Synchronous Response Method:

When using a query parameter with the value of 'synchronous', the expected response would include the final transaction details with a asyncStatus of poiDeviceInUse, cancelled, cancelledAtTerminal or interactionComplete:

{
   "transaction": {
       "id": 4869813602,
       "type": "sale",
       "success": true,
       "condition": "pendingsettlement",
       "authCode": "A99BUO"
   },
   "platformId": "70a6272c-4949-4515-956a-6e5ae4d5a10c",
   "asyncStatusGuid": "70a6272c-4949-4515-956a-6e5ae4d5a10c",
   "asyncStatus": "interactionComplete"
}

Example responses with and without Response Method:

If the POI Device has an inFlight transaction with another 'async_status_guid', the response for the second transaction requested will return this:

{
    "transaction": {
        "id": null,
        "success": false,
        "condition": "",
        "authCode": ""
    },
    "platformId": "f090f2e5-c96c-eb11-869b-005056b9afb7",
    "asyncStatusGuid": "f090f2e5-c96c-eb11-869b-005056b9afb7",
    "asyncStatus": "poiDeviceInUse"
}

In the event of an approval (sale or credit), the response would change to this:

{
   "transaction": {
       "id": 4869813602,
       "type": "sale",
       "success": true,
       "condition": "pendingsettlement",
       "authCode": "A99BUO"
   },
   "platformId": "70a6272c-4949-4515-956a-6e5ae4d5a10c",
   "asyncStatusGuid": "70a6272c-4949-4515-956a-6e5ae4d5a10c",
   "asyncStatus": "interactionComplete"
}

Note: An 'auth' or 'validate' action would have a different condition. Auths remain in a 'pending' state and require capturing to settle, and Validates are immediately 'complete' upon approval. In the event of a decline, the response would change to this:

{
   "transaction": {
       "id": 4869813602,
       "type": "sale",
       "success": false,
       "condition": "failed",
       "authCode": ""
   },
   "platformId": "70a6272c-4949-4515-956a-6e5ae4d5a10c",
   "asyncStatusGuid": "70a6272c-4949-4515-956a-6e5ae4d5a10c",
   "asyncStatus": "interactionComplete"
}

If the transaction is an EMV transaction, the response will include emvMetaData details for creating custom receipts:

{
   "transaction": {
       "id": 4869813602,
       "type": "sale",
       "success": true,
       "condition": "pendingsettlement",
       "authCode": "A99BUO"
       "emvMetaData": {
            "customerVerificationMethod": "signature",
            "applicationId": "A0000000031010",
            "applicationLabel": "VISA CREDIT",
            "applicationPreferredName": "CREDITO DE VISA",
            "applicationPanSequenceNumber": "02",
            "transactionStatusInformation": "E800",
            "maskedMerchantNumber": "xxxxx1111",
            "maskedTerminalNumber": "xxxx1234"
       }
   },
   "platformId": "70a6272c-4949-4515-956a-6e5ae4d5a10c",
   "asyncStatusGuid": "70a6272c-4949-4515-956a-6e5ae4d5a10c",
   "asyncStatus": "interactionComplete"
}

Vault details will be returned if specified in the transaction request.


    "transaction": {
        "id": "281474978429650",
        "type": "sale",
        "success": true,
        "condition": "pendingsettlement",
        "authCode": "SH14L8",
        "customerVaultId":"9742353903"
    },
    "platformId": "86d84df6-e062-49f6-ba81-4b667839e34e",
    "asyncStatusGuid": "86d84df6-e062-49f6-ba81-4b667839e34e",
    "asyncStatus": "interactionComplete"
}

If there was an error it will be in the asyncstatus response.

{
    "transaction": {
        "id": null,
        "success": false,
        "condition": "",
        "authCode": ""
    },
    "error": {
        "code":300,
        "refid":"58523101",
        "message":"error message will appear here"
    },
    "platformId": "dd1c7f5c-13b5-4098-82c1-73d3e1bb085f",
    "asyncStatusGuid": "dd1c7f5c-13b5-4098-82c1-73d3e1bb085f",
    "asyncStatus": "interactionComplete"
}

If successful, the response HTTP status code is 200 OK.

Errors

The following HTTP status codes will be returned in the event of various errors:

300 - Indicates that an issue occurred whilst trying to get the status of a transaction. This usually happens when a transaction takes more time than usual to be processed. If it keeps re-occurring you should check the device to ensure that it is connected and ready to perform transactions.

  • 400 - No Platform ID or no API Key was sent in the request.
  • 401 - An invalid API Key was sent in the request.
  • 404 - The Platform ID provided was not found.

Response Details

transaction

The transaction object containing a subset of information

transaction.id

The gateway transaction ID that can be used for querying.

transaction.success

Will return true or false depending on the final result of the transaction.

true -indicates a successful transaction (approved)

false - indicates a failed transaction (declined). The response will return false also in the event of an error, a cancelled transaction, or when the customer has not yet finished interacting with the POI Device.

transaction.condition

The final condition of the transaction.

pendingsettlement - for successful Sales and Credits

pending - for successful Auths complete - for successful Validates canceled - for voided transactions failed - for declined transactions

authCode

If the transaction was successful, the auth code will be returned.

customerVaultId

If the transaction request included Customer Vault parameters, the Customer Vault ID will be returned.

emvMetaData object

If the transaction was an EMV/Chip Card insert, additional transaction receipt data will be returned.

emvMetaData.customerVerificationMethod

A CVM is a means of checking that the user of a card is the genuine cardholder. The returned value will indicate how the customer was verified.

  • signature- The customer either signed digitally or was asked to sign a physical receipt. This CVM indicates the signature should be collected and confirmed by the POS operator.offlinePin - The customer entered their pin on the POI Device and it was verified by the chip.
  • onlinePin- The customer entered their pin on the POI Device and it was verified by the Card Issuer.
  • offlinePinSignature - The customer entered their PIN on the POI Device and they signed digitally or a physical receipt.
  • none- The customer could not be verified by the POI Device.

emvMetaData.applicationId

Identifies the EMV application that the POI Device used on the transaction as described in ISO/IEC 7816-5. Example: A000000003101001.

emvMetaData.applicationLabel

The human readable name associated with the AID according to ISO/IEC 7816-5. Example: Visa International.

emvMetaData.applicationPreferredName

The human readable name associated with the applicationId in the cardholder’s local language. This value will not always be present.

emvMetaData.transactionStatusInfo

A collection of indicators that the POI Device will set to show what processing steps have been performed on the current transaction (e.g. Cardholder Verification, Data Authentication). Example: E800.

error object

If the transaction experienced an error, the code, refid, and message will be returned.

error.code object

The static error code '300' indicates that an issue occurred whilst trying to get the status of a transaction. This usually happens when a transaction takes more time than usual to be processed. If it keeps re-occurring you should check the device to ensure that it is connected and ready to perform transactions.

error.refid object

The unique identification for the error. This value can be provided to support for further troubleshooting.

error.message object

The human readable message describing the issue with the transaction.

asyncStatusGuid

The current GUID being polled against.

asyncStatus

The current status of the transaction on the POI Device itself.

  • inFlight - This means the customer is still interacting with the POI Device. There may or may not be a transaction created at this point.
  • poiDeviceInUse - This means there is a transaction in progress or 'in flight' with the same POI Device using another 'async_status_guid'
  • cancelled - This means the transaction was cancelled with a general error. No transaction was created.
  • cancelledAtTerminal - This means the cancel button on the POI Device was pressed. No transaction was created.
  • cancelledByApi - The transaction was cancelled by API request. Please start a new transaction.
  • cancelledByTimeout - The transaction was cancelled due to no interaction with the device. Please start a new transaction.
  • interactionComplete - This means the transaction has completed, and POI Device interaction has ceased. A new transaction can be started on this device.

Updated 6 days ago

What’s Next