The Smart Terminal now supports keyed transactions. Simply provide the keyed parameter with value ALLOW when sending the payment request, then press the yellow backspace key on the Smart Terminal keypad when prompted to "Insert, Swipe or Tap".

Required API Version: 2019-07-30

At this time, automatic transaction declines for AVS mismatch is unavailable when a transaction is keyed into a Smart Terminal. These transactions will be processed as if the match type for AVS was set to BYPASS until a future update is released.

The Smart Terminal now supports refunds by setting the action parameter to REFUND when submitting a payment request.

Before implementing refunds in your Smart Terminal integration, make sure to read this section of the following article for important information to avoid accidentally refunding the wrong amount: Refunding and Voiding Transactions

Initiate a transaction on the Smart Terminal. The Smart Terminal will automatically determine if the customer needs to insert the chip card, swipe the card, enter a PIN or collect a signature.

Before you begin:

• You need to provide a webhook callback URL where the POST request will be sent after the Smart Terminal transaction is complete.
• A callback URL has to be provided for each merchant. All APPROVED and DECLINED Smart Terminal transactions for the merchant will send data to the callback URL, including Smart Terminal transactions initiated from the Virtual Terminal application.
• Upon posting, a callback URL should return a successful status (i.e. 200, 202, 204) to indicate the webhook was successfully consumed. If a successful status is not received, the POST will try again until a successful response code is received.

Step 1: POST request

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

Parameters

All amount* fields have a max value of 1,000,000. Amounts higher than 1,000,000 will cause a validation error.

Additional Fields

Production Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "amountBase=1.00" \
    -d "terminalId=123456" \    
    -d "invoiceNumber=654321" \
    -d "showReceiptPrompt=true" \
    "https://api.payjunction.com/smartterminals/{smartTerminalId}/request-payment"

Sandbox Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_LABS_APP_KEY" \
    -d "amountBase=1.00" \
    -d "terminalId=123456" \
    -d "invoiceNumber=654321" \
    -d "showReceiptPrompt=true" \
    "https://api.payjunctionlabs.com/smartterminals/{smartTerminalId}/request-payment"

Response

On successful request, returns HTTP Response "200 OK".

Response Body:

{
    "requestPaymentId" : "422900dc-25bb-4b56-94f4-d7f5c9646e54"
}

On validation error, returns 400. Example:

{
  "errors": [
    {
      "message": "This field is required.",
      "parameter": "amountBase",
      "type": "required"
    },
    {
      "message": "This field is required.",
      "parameter": "terminalId",
      "type": "required"
    }
  ]
}

Step 2: Webhook

• When transaction is complete a POST request is sent to a callback URL you provided

Example of Webhook Data

SMARTTERMINAL_REQUEST

This type of webhook can be received multiple times as state changes occur during the processing of the request. This webhook is triggered by either a transaction request, a standalone signature request, or any future request types released for the Smart Terminal.

Because SMARTTERMINAL_REQUEST allows for the loose tracking of a Smart Terminal's state during a request, it is recommended for most integrations. Even if you start with the simpler SMARTTERMINAL_TRANSACTION subscription, the goal should be to move to SMARTTERMINAL_REQUEST to provide the best experience for your customers as possible.

{
  "created": "2018-02-20T20:30:01.756Z",
  "data": {
    "requestId": "422900dc-25bb-4b56-94f4-d7f5c9646e54",
    "status": "CONNECTING"
  },
  "id": "835a3fe6-a7e2-4872-9206-1ed28c4476e6",
  "type": "SMARTTERMINAL_REQUEST"
}

To see all possible status types, please see the main article for SMARTTERMINAL_REQUEST.

TRANSACTION_SIGNATURE

This type of webhook will be received after any transaction in PayJunction captures a signature. This includes Smart Terminal, Virtual Terminal, Hosted Payments and API transactions.

{
  "id": "8eed5e50-86ec-4a01-a832-2a026178be9b",
  "created":"2016-04-07T18:04:10.158Z",
  "type":"TRANSACTION_SIGNATURE",
  "data":{
    "transactionId": "8350"
  }
}

Description of Fields

Connection Timeout & Retry Limits

• PayJunction expects to be able to connect to integrators within 5 seconds, and for integrators to respond within 15 seconds of receiving a webhook event. If your service takes longer than that to complete, the connection will be terminated and the event will be re-queued and sent at a later date.
• Failed webhook retry delay:
  • Attempts 2-5: 30 second delay
  • Attempts 6-10: 5 minute delay
  • Attempt > 10: 1 hour delay (After 3 days we will no longer attempt to send the webhook event and it will be deleted.)

Best Practices:

• Respond to webhooks quickly. If processing a webhook takes long enough that the request times out, PayJunction will attempt to send the webhook again. If processing a webhook will take a long time, immediately returning a 2xx Http Status code will help ensure correct behavior with PayJunction webhooks.
• Any action processing webhooks should be idempotent. Due to the nature of our webhook processing, a webhook may be sent more than once.  Using the "id" of the post data you can ensure that you only process an event once.

Please Note

1. Webhooks are not guaranteed to be delivered in order. If you "request-payment" on Smart Terminal A, then request-payment on Smart Terminal B, you are not guaranteed to receive the webhook from Smart Terminal A before the webhook from Smart Terminal B.
2. Every request to "request-payment" will interrupt the current state of the Smart Terminal. Normally this would only happen for an "idle" Smart Terminal. However, if the Smart Terminal was in the middle of a transaction, the current transaction may be interrupted.  This might have unintended side effects, and should be done with caution.
3. Each call to "request-payment" is not guaranteed to be followed with a webhook. This can happen for many reasons, for example:
   • The transaction may be canceled by the customer on the Smart Terminal
   • The Smart Terminal payment screen may have timed out
   • There are connection issues for the Smart Terminal, and the Smart Terminal did not respond to the "request-payment" request
   • Another "request-payment" message was sent to the same Smart Terminal.
4. If you have not received a webhook in approximately 90 seconds, you likely won't receive one