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. This endpoint can also be used to check the status of a Signature request.

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 API endpoint 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 1/2 second per requestPaymentId. Consider using a Webhook if you want to know when a request status changes without waiting.

Example Flow

Request

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

Responses

Connecting

Connection with the specified Smart Terminal is still pending.

{
    "status" : "CONNECTING"
}

Busy Terminal

The request cannot be processed because the Smart Terminal is busy. This is an end state for this request, no need to further monitor it.

For API versions prior to 2018-06-19 interruptBusyTerminal=false must be sent in the request body to receive this status type.

{
    "status" : "BUSY"
}

No Connection

A connection failed between the webservice and Smart Terminal.

{
    "status" : "NO_CONNECTION"
}

Connected, now In Progress

Smart Terminal is performing the requested action.

Note that a transactionId/signatureId might be present, but the request is still processing

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

Transaction Completed

A request is marked as COMPLETE when the Smart Terminal is done and ready to serve another request.

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.

Complete - Smart Terminal Payment Request

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

Complete - Smart Terminal Input Request

{
    "status": "COMPLETE",
    "inputValue" : "8006010230"
}

Complete - Smart Terminal Prompt Request

{
    "status": "COMPLETE",
    "promptButton": "Yes"
}

Complete - Smart Terminal Signature Request

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

Canceled Transaction Request

If the transaction is not processed (canceled, timeout, etc), transactionId field will not be present.

{
    "status" : "COMPLETE"
}

Example - Purged or Invalid requestPaymentId

HTTP Response Code: 404

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

Example - Rate Limit

HTTP Response Code: 429

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