AsyncStatus Polling

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

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.idThe gateway transaction ID that can be used for querying.

transaction.successWill 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 Creditspending - 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.

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

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

emvMetaData.customerVerificationMethodA 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.applicationLabelThe human readable name associated with the AID according to ISO/IEC 7816-5. Example: Visa International.

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

emvMetaData.transactionStatusInfoA 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 objectIf the transaction experienced an error, the code, refid, and message will be returned.

error.code objectThe 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 objectThe unique identification for the error. This value can be provided to support for further troubleshooting.

error.message objectThe human readable message describing the issue with the transaction.

platformIdDEPRECATED: The current GUID being polled against.

asyncStatusGuidThe current GUID being polled against.

asyncStatusThe 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.