POST /smartterminals/{smartTerminalId}/request-signature

Capture digital signatures on the Smart Terminal for non-payment requests, such as electronic waivers, release forms, terms and conditions, contracts, etc.

This request is not needed when charging a credit card using the request-payment endpoint. It is used to collect a signature without processing a credit card transaction.

For integrations utilizing webhooks, a subscription to the SMARTTERMINAL_REQUEST webhook event type is required. For integrations using polling, the GET /smartterminals/{smartTerminalId}/requests/{requestId} is used.  

Initiate a new signature request on the selected Smart Terminal.

  • Signature request has to be sent to the Smart Terminal as POST to /smartterminals/ {smartTerminalId}/request-signature
  • {smartTerminalId} is a UUID of a specific Smart Terminal you are requesting signature from. Example: 88888888-4444-4444-4444-cccccccccccc

Parameters

required name format description
* terminalId Numeric This field points to the specific merchant account which the signature will be processed through. For example: main location, second location, sales department, etc. Click Here for instructions to find the Terminal Id(s) for your account.
 *  terms  Max Length 10,000   String of terms text that will be shown on Smart Terminal.

 

Example Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "terminalId=123456" \
    -d "terms='My legal terms text.'" \
    "https://api.payjunction.com/smartterminals/{smartTerminalId}/request-signature"

Example Responses

HTTP 200 - successful request. Response Body: 

{
    "requestId" : "1223e21e-9e51-484d-9612-30a2570a53d4"
}

HTTP 400 - validation error. Response Body: 

{
  "errors": [ 
    {
      "message" : "Terminal does not exist or you do not have permission to access it.",
      "parameter" : "terminalId",
      "type" : "invalid"
    },
    {
      "message" : "This field is required.",
      "parameter" : "terms",
      "type" : "required"
    }
  ]
}

Example Status Responses 

Connecting

{
  "id" : "1478d683-f082-4bb8-bfc9-7ba5141f4629",
  "created" : "2019-12-05T18:03:29.030Z",
  "type" : "SMARTTERMINAL_REQUEST",
  "data" : {
    "requestId" : "8066670c-e046-4446-8d02-2067484b0b9b",
    "status" : "CONNECTING"
  }
}

In Progress

{
  "id" : "82a534c7-ec11-4601-bfcd-2c1049f0b7a1",
  "created" : "2019-12-05T18:03:29.122Z",
  "type" : "SMARTTERMINAL_REQUEST",
  "data" : {
    "requestId" : "8066670c-e046-4446-8d02-2067484b0b9b",
    "status" : "IN_PROGRESS"
  }
}

In Progress - Signature Available

The Smart Terminal is still "busy" but the signature image is available to retrieve using GET /smartterminals/signatures/{signatureId}/image

{
  "id" : "bd9035f6-3feb-4a8b-bf29-3c6cd39f19e4",
  "created" : "2019-12-05T18:03:57.775Z",
  "type" : "SMARTTERMINAL_REQUEST",
  "data" : {
    "requestId" : "8066670c-e046-4446-8d02-2067484b0b9b",
    "signatureId" : "6cb4d5ea5d614c8a9b76aeff13174c5c",
    "status" : "IN_PROGRESS"
  }
}

Complete

The Smart Terminal has cleared the "busy" state and is ready to accept a new transaction or signature request

{
  "id" : "afac9cbe-1f37-4305-9ef3-0d285b8260d3",
  "created" : "2019-12-05T18:04:00.391Z",
  "type" : "SMARTTERMINAL_REQUEST",
  "data" : {
    "requestId" : "8066670c-e046-4446-8d02-2067484b0b9b",
    "signatureId" : "6cb4d5ea5d614c8a9b76aeff13174c5c",
    "status" : "COMPLETE"
  }
}