Device Based Transaction Error Codes
| Request Code | Status Code | Error Message | Endpoint | Cause |
|---|---|---|---|---|
| PUT | 500 | 404 - {\"error\":\"Unknown devicekey sa_ |
/deviceTransactions/ |
The secure source key in the Maven-UI for this location/OID does not match the source key set up for the device in Merchant Portal-UI. Maven saves the source key info to the organization table. But Merchant Portal saves the source key info to the remote devices table. They must match. And in Maven-UI the "use for emergepay" flag on the source key must be set and match the source key that was set on the device. |
| PUT | 500 | "409 - {\"error\":\"Device is currently offline\",\"errorcode\":21145} | /deviceTransactions/ |
The transaction was started with a call to the VTS with an incorrect device name in the request body. So the device is "offline". OR The device hasn't been used in > 20 minutes. The device went into hibernation mode. This requires the user to press the green button on the device to wake it back up (does not initiate a boot sequence) |
| PUT | 400 | "message": "Unable to retrieve settings for device name: |
/deviceTransactions/ |
The transaction was started with an incorrect device name in the request body. OR The device hasn't been added for this merchant at all. The merchant is created in Maven-UI but the device is not set up on Merchant Portal. The user needs to add a Cloud Controller and MP200L device using the Terminal Configuration page on that website. |
| PUT | 500 | "message": "A credential value is required" | /deviceTransactions/ |
Maven-UI has the source key set without the "use for emergepay" box checked |
| PUT | 500 | "message": "OID to SourceKeyId lookup Error [from TSL] - No SourceKeyId found" | /deviceTransactions/ |
Device was in hibernate mode when PUT call was done for device initialization? |
| PUT | 409 | "message": "Unable to start the device" | /deviceTransactions/ |
The device was already initialized to run a transaction when another device initialization call was made to the same device. |
| PUT | 504 | Endpoint request timed out | /deviceTransactions/ |
We theorize that the EPsl was being deployed at the time of the request to initialize the device. This caused a API gateway timeout on AWS |
| PUT | 424 | "message": "Failed validation", "target": "device_name", | /deviceTransactions/ |
The transaction was started with an empty string for the device name in the request body. |
| PUT | 424 | "message": "field value is missing", "target": "device_name", "recoverable": true | /deviceTransactions/ |
The transaction was started with "signature_capture" true and "signature_required" true but no device name was specified in the startTransaction call |
| GET | 409 | "message": "Unable to retrieve transaction response. Transaction was either not started or hasn't completed." | /deviceTransactions/ |
The caller is attempting to retrieve device transaction results before the transaction has run (card has not be swiped or the transaction is in the process of being run by the gateway) |
| GET | 200 | resultMessage:"Terminal configuration error" | /deviceTransactions/ |
When polling the device endpoint for the transaction result you see a resultStatus of "false" and a message of: transactionResponse: uniqueTransId: "9230018ce44d4c068bc9f66a52cc8ba8-00000000000000000000000000000000" batchNumber:"" resultMessage:"Terminal configuration error" resultStatus:"false" approvalNumberResult:"000000" amountProcessed:"0.00" amount:"0.02" This is due to the account getting deactivated on First Data. Reach out to Tim to have the account reactivated. We have no idea why the accounts are getting deactivated. |
| GET | 500 | "message": "Key: |
/deviceTransactions/ |
The caller issue a GET request to the device endpoint /device/v1/devicetTransactions/ |
| GET | 404 | "message": "Invalid Transaction Token", "target": "xtoken", "recoverable": true | /deviceTransactions/ |
The caller issue a GET request to the device endpoint /device/v1/devicetTransactions/ |
| GET | 403 | "message": |
/deviceTransactions/ |
The caller issue a GET request to the device endpoint /device/v1/devicetTransactions/ |
| PATCH | 500 | "message": "Request key is required" | /deviceTransactions/ |
The caller attempted to convertToKeyed before the transaction was sent to the device |
| PATCH | 500 | "message": "409 - {\"error\":\"Request can not be cancelled\",\"errorcode\":21142}" | /deviceTransactions/ |
The caller is attempting to convert to a keyed transaction after the card has been swiped and the transaction is in flight to USAePay for processing. A subsequent GET call to /deviceTransactions/ |
| PATCH | 409 | "message": "Unable to convert device transaction to keyed." | /deviceTransactions/ |
The caller is attempting to convert to keyed after the transaction is complete (approved/declined/cancelled/converted) |
| DEL | 500 | "message": "Request key is required" | /deviceTransactions/ |
The caller attempted to cancel a device transaction on the DTS endpoint before it had been sent to the device |
| DEL | 409 | "message": "Unable to perform requested function" | /deviceTransactions/ |
The caller attempted to cancel a device transaction after the transaction had completed (approved/declined/cancelled/converted) |
| DEL | 404 | "message": "Invalid Transaction Token", "target": "xtoken", "recoverable": true | /deviceTransactions/ |
The caller issue a DELETE request to the device endpoint /device/v1/devicetTransactions/ |
| DEL | 500 | "message": "Key: |
/deviceTransactions/ |
The caller issue a DEL request to the device endpoint /device/v1/devicetTransactions/ |
| DEL | 403 | "message": |
/deviceTransactions/ |
The caller issue a DEL request to the device endpoint /device/v1/devicetTransactions/ |
| POST | 403 | "message": |
/orgs/{oid}/transactions/acknowledgements/{externalTranId} | The caller issued a POST request to the POS ack endpoint when they should have sent a PUT request |
| POST | 403 | "message": |
/orgs/{oid}/transactions/acknowledgements/{externalTranId} | The caller issued a PUT to the POS ack endpoint but did not include the externalTranId in the URL of the request |
| PUT | 500 | The recorded transaction is missing the gatewayTransRefNum which is necessary to run the transaction | /orgs/{oid}/transactions/tokenizedRefund /orgs/{oid}/transactions/tokenizedPayment |
The caller is using a uniqueTransId in the tokenizedRefund that comes from a creditSale/creditReturn that was declined/canceled. There is not gatewayTransRefNum record in the Azure database for emergeapy to go use to look up a CipCardTokenId to run a tokenized payment. |
| GET | 400 | "message": "The recorded method for this transaction is not | /transactions/ | startTransaction was called with the method of urlPage || modal || hostedFields, but the subsequent call to get the HTML stream was incorrectly calling the endpoint for another transaction type |
|
| GET | 200 | "resultMessage": "Transaction request has timed out" | /transactions/| startTransaction was called and the device was initialized and waiting for Swipe/Insert/Tap but no card was run. The transaction timed out after 3 minutes |
|
| GET | 200 | "resultMessage": "Command timeout (B001) | /transactions/| startTransaction was called and USAePay did not complete the transaction |
|
| POST | 400 | "message": "Unrecognized field", "target": "device_name", | /orgs/{oid}/transactions/start | The endpoint is called for a CreditSaveCard transaction which doesn't support devices. The error message is relating that a device_name in the request body is not a recognized field for a CreditSaveCard transaction |
| DEL | 400 | "message": "Device transactions cannot be canceled from this endpoint" | /virtualterminal/v1/transactions/ |
The device transaction is started and you cannot try to cancel it by sending a DEL request to the VTS endpoint. You need to send it to the Device (DTS) endpoint instead. /deviceTransactions/ |