Follow

GET /smartterminals/requests/{requestId}

BETA:
The following API is still in beta. PayJunction is actively seeking integration partners who need this API to support native applications. If you would like to participate please open a developer support ticket.
This document describes the Polling API which can be used as an alternative to the Webhook API for processing payments on the Smart Terminal with native applications.

For more information please see Do I need to use Webhooks or Polling with Smart Terminals?
NOTE: A requestId is the same as a requestPaymentId.

This query provides the status of a Smart Terminal payment request returned by POST /smartterminals/{smartterminalId}/request-payment or POST /smartterminals/ {smartTerminalId}/request-signature

Query Limits

The status of a Smart Terminal payment request can be queried up to 1 day after it's completed. After this cut-off the requestPaymentId is purged and will return a 404 Not Found when queried. 

To discourage busy polling, requests to this endpoint are limited to 1 request every 2 seconds per requestPaymentId. Consider using Webhook if you want to know when a request status changes without waiting.

Status List

Currently there is no status for when a customer cancels the transaction from the Smart Terminal itself; we are in the process of removing the ability for the customer to cancel. Until then, IN_PROGRESS will continue to be the status returned even if the transaction was cancelled.

More statuses will be added in the future to allow for tighter UI integrations. We recommend code that passively ignores unrecognized statuses to accommodate application updates.

CONNECTING

A connection to the Smart Terminal is pending.

NO_CONNECTION

A connection failed between the webservice and Smart Terminal. 

IN_PROGRESS

The Smart Terminal is attempting to process the transaction.

BUSY

The request cannot be processed because the Smart Terminal is busy. For API versions prior to 2018-06-19 interruptBusyTerminal=false must be sent in the request body to receive this status type. 

required name Default Value Possible Values
  interruptBusyTerminal

false

*2018-06-19 and prior versions, default is true*

true / false

COMPLETE

A request is marked as COMPLETE when the Smart Terminal is done and ready to serve another request. Previously the COMPLETE status was set as soon as the requested resource was created, even if the Smart Terminal was still busy on user input or status screens.

The process is completed and the Smart Terminal is ready to serve another request. Note that COMPLETE doesn't necessarily mean successful; users can cancel the request or it may time out.

When a request completes successfully, a transactionId (for request-payment) or signatureId (for request-signature) points to the created resource.

Example Request

curl -H "X-PJ-Application-Key:88888888-4444-4444-4444-cccccccccccc" \
    -u "login:password" \
    "http://www.payjunctionlabs.com/trinity/api/smartterminals/requests/b58cb128-2e99-4da8-b93e-711f1fc7d5db"

Example Responses

Connecting Example

HTTP Response Code: 200

Note that we do not have a transactionId yet because the payment is not complete.

{
    "status" : "CONNECTING"
}

In Progress Example

HTTP Response Code: 200

In progress (Note that a transactionId/signatureId might be present, but the request is still processing):

{
    "status" : "IN_PROGRESS",
    "transactionId" : 123
}

Complete Example - For a Smart Terminal Payment Request

{
    "status" : "COMPLETE",
    "paymentId" : 123
}

Complete Example - For a Smart Terminal Signature Request

{
    "status" : "COMPLETE",
    "signatureId" : "2f0bfa2c56894a398af741f3ecfc115e"
}

Purged or Invalid requestPaymentId Example

HTTP Response Code: 404

{
    "errors" : [{
        "message" : "404 Not Found"
    }]
}

Rate Limit Example

HTTP Response Code: 429

{
    "errors" : [{
        "message" : "Your request has been rate limited. Please wait longer between subsequent requests."
    }]
}