Follow

POST /smartterminals/{smartTerminalId}/request-payment

Process transactions using the Smart Terminal. 

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

required name format description
* amountBase Money,
Format: X.XX
Good: 1000.00 or 1000
Bad: $1000 or 1,000.00 or 1000.000
Base amount to charge (in dollars).
  amountShipping Money,
Format: X.XX
Ex: 1000.00 or $1,000.00
If you want to track separate shipping amounts use this parameter.
  amountSurcharge Money,
Format: X.XX
Ex: 1000.00 or $1,000.00
If you want to add a surcharge to the transaction then use this parameter.
* terminalId Numeric This field points to the specific merchant account terminal that the transaction will be processed on. For example: main location, second location, sales department, etc. Click Here for instructions to find the Terminal Id(s) for your account.
  showReceiptPrompt true | false

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

* Default value is true if a parameter is not sent.

Additional Fields

required name format description
  invoiceNumber Numeric 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.
  billingIdentifier Max Length 64 Billing customer id. If you have your own customer ID you want to associate with the transaction.
  billingEmail Max Length 125 Billing email.
  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" \
    "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_TRANSACTION

This type of webhook will be received after any Smart Terminal transaction is processed on the account, including transactions processed directly through the PayJunction Virtual Terminal.

{
  "id":"b3cdd8ab-adc9-43a8-a428-a88e7f50a977",
  "created":"2016-04-07T18:03:40.158Z",
  "type":"SMARTTERMINAL_TRANSACTION",
  "data":{
    "requestPaymentId":"422900dc-25bb-4b56-94f4-d7f5c9646e54",
    "smartTerminalId":"88888888-4444-4444-4444-cccccccccccc",
    "transactionId":"8350"
  }
}

TRANSACTION_SIGNATURE

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

{
  "id": "8eed5e50-86ec-4a01-a832-2a026178be9b",
  "created":"2016-04-07T18:04:10.158Z",
  "type":"TRANSACTION_SIGNATURE",
  "data":{
    "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