Offer all the payment features your
customers want with a fast integration
that limits your PCI scope.



  • Production Server

    For processing live transactions

  • Test Server

    For development

Most Commonly Referred to Articles

POST /smartterminals/{smartTerminalId}/request-payment

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


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

required name format description

Forces the Smart Terminal to either process a charge or a refund. Defaults to CHARGE if not provided in the request.

* amountBase Money,
Format: X.XX
Ex: 1000.00
Base amount to charge (in dollars).
  amountShipping Money,
Format: X.XX
Ex: 1000.00
If you want to track separate shipping amounts use this parameter.
  amountSurcharge Money,
Format: X.XX
Ex: 1000.00

Click here to learn how to use PayJunction's surcharge feature

Alternatively, this field can be used to send other additional amounts that can be added to transactions in a compliant manner.

  amountSurchargeTax Money,
Format: X.XX
Ex: 1000.00

Click here to learn how to use PayJunction's surcharge feature

Tax amount applied on the surcharge.

  amountTax Money,
Format: X.XX
Ex: 1000.00
Used to send the Tax amount as a separated value to PayJunction.
* terminalId Numeric This field points to the specific batch which the transaction 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.
  showDebitCreditPrompt true | false

If true, a debit/credit prompt will be displayed on the Smart Terminal before the customer chooses the payment method. This prompt forces the payment to be processed on the network that the customer selected. Available if the Account supports PIN Debit.

true - Displays the debit/credit prompt.
false - Disables the debit/credit prompt.

* Default behavior is to use the setting in the PayJunction VT, set by the merchant.

  showReceiptPrompt true | false

Use that Parameter to have the Smart Terminal skip the email receipt prompt.

true - Displays the receipt prompt.
false - Disables the receipt prompt.

* Default behavior is to use the setting in the PayJunction VT, set by the merchant.

  showSignaturePrompt true | false

Enables or disables the signature prompt on the SmartTerminal (defaults to true).

true - Displays the screen to collect a signature when necessary.
false - Skips the screen to collect a signature.

* Default behavior is to use the setting in the PayJunction VT, set by the merchant.

  allowTips true | false

Enables or disables the option for a card holder to include a tip amount for the transaction.

* Default behavior is to use the setting in the PayJunction VT, set by the merchant.

  keyed ALLOW | FORCE


Pressing the yellow backspace key on the Smart Terminal will bring up a keyed entry form, allowing the user to directly enter card information for Card-Not-Present transactions.


Sends the Smart Terminal directly into keyed entry mode and bypasses Card-Present transactions (insert, dip, or swipe). This is used for transactions where the user knows at the outset that they will be manually entering card information like call centers.

TIP: Use this feature to reduce PCI scope for Keyed transactions.

Additional Fields

required name format description
  billingFirstName Max Length 16 Billing first name. Including this will overwrite the First Name from the card.
  billingLastName Max Length 32 Billing last name. Including this will overwrite the Last Name from the card.
  billingEmail Max Length 125 Billing email.
  billingIdentifier Max Length 64 Billing customer id. If you have your own customer ID you want to associate with the transaction.
  invoiceNumber Max Length 32 An invoice number to include in the transaction details.
  purchaseOrderNumber Max Length 32 Purchase order number. If you would like to mark this transaction with your own PO for accounting.
  shippingIdentifier Max Length 64 Shipping customer id. If you have your own customer ID you want to associate with the transaction.
  shippingEmail Max Length 128 Shipping email address.
  note Max Length 2048 A note field for you to annotate the transaction.

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" \

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" \


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


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",

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


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",
    "transactionId": "8350"

Description of Fields

name format description
id Webhook UUID Unique webhook identifier. Generated once for each transaction event. If there are multiple urls waiting for webhooks, the same event (with the same id) will be sent to all waiting urls.
created Date Date and time when webhook event was first created by the system. This is not a received date.
type String Webhook event type. SMARTTERMINAL_TRANSACTION indicates the completion of a Smart Terminal transaction and is being sent when the transaction has been APPROVED or DECLINED. This includes transactions initiated from the Virtual Terminal.
data Json Map Contains data relevant to the specified event. SMARTTERMINAL_TRANSACTION event has requestPaymentId, smartTerminalId and transactionId data fields.
data.requestPaymentId Request Payment UUID UUID of the payment request that was submitted.
data.smartTerminalId Smart Terminal UUID UUID of a Smart Terminal the transaction was run on.
data.transactionId Numeric Id of the newly completed transaction. The transaction may be APPROVED or DECLINED. Use the GET /transactions/{transactionId} endpoint to check the status of the completed transaction.

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