Follow

Transaction Processing Workflow

Keyed, Swiped & Recharged (Instant) Transactions

These types of transactions work in a traditional manner: an HTTP request is sent to the PayJunction API and a response indicating if the transaction was successful or not is immediately received.

TIP: Some HTTP libraries will throw an exception if the HTTP status code sent back is not a 'successful' status code. For example, if the wrong API credentials are supplied, a response of "401 Unauthorized" is returned by the PayJunction API server. This is also the code if the wrong Application Key is sent. It is therefore important to capture the body of the response when catching the exception to see the specific error message.

Example POST request

NOTE: POST data must be sent in the x-www-form-urlencoded format, i.e. "param1=value1&param2=value2". Depending on the HTTP library used, you might either need to manually create the string or set the Content-Type header to "application/x-www-form-urlencoded" to tell the library how to format the data.

REQUEST (API Client->PayJunction Server):

POST https://api.payjunctionlabs.com/transactions
cardNumber=4444333322221111&cardExpMonth=12&cardExpYear=2020&baseAmount=1.00&terminalId=654321

RESPONSE (PayJunction Server->API Client):

201 Created 
{ "transactionId": "124", "uri": "https://api.payjunctionlabs.com/transaction/124", ... , "response": { "approved": false, "code": "05", "message": "Do Not Honor", ... }, ... }

In both of our above examples, the client sends an HTTP request to the PayJunction server and the server responds with the requested information or an error response if there was an issue.

Example GET request

REQUEST (API Client->PayJunction Server):

GET https://api.payjunctionlabs.com/transactions/123

RESPONSE (PayJunction Server->API Client):

200 OK
{ "transactionId": "123", "uri": "https://api.payjunctionlabs.com/transactions/123", ... , "response": { "approved": true, "code": "00", "message": "Approved", ... }, ... }

Smart Terminal Transactions

NOTE: Documentation for submitting Smart Terminal transaction requests

Transactions processed via the Smart Terminal are handled differently from other transaction requests. In other transaction processing requests, the card information is sent directly to the PayJunction API for processing. However, with the Smart Terminal, we are instead requesting that the hardware unit handle the processing of the transaction.

For security and EMV compliance, we can't just allow any service to communicate with the Smart Terminal, so all communication needs to be with PayJunction's cloud service. Therefore, we send a request to the Smart Terminal to process a transaction and we get the transaction information afterwards. To accomplish this, we send a payment request notification to the PayJunction API and receive a webhook back from PayJunction when the transaction is complete:

First, we start by making the payment request:

REQUEST (API Client->PayJunction Server):

POST https://api.payjunctionlabs.com/smartterminals/88888888-4444-4444-4444-cccccccccccc/request-payment
{ "amountBase": "1.00", "terminalId": "654321", "invoiceNumber": "10000201256" }

RESPONSE (PayJunction Server->API Client):

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

At this point, PayJunction handles the communication with the Smart Terminal which then prompts the cardholder to make their payment. Once the payment has been either approved or declined, PayJunction sends a notification to the webhook listener url subscribed to webhooks of type SMARTTERMINAL_TRANSACTION:

REQUEST (PayJunction Server->Webhook Listener):

POST https://your.server.address.com/webhooks/smartterminal-transaction
{ "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":"126" } }

RESPONSE (Webhook Listener->PayJunction Server):

201 Created

A few things to take note of:

  • The requestPaymentId value is the same in the original payment request and in the webhook payload’s data object. This is how we know which Smart Terminal payment request the webhook is in reference to.
  • We received a transactionId parameter and value in the webhook payload's data object.
  • There is no status information supplied for the transaction indicating whether it was approved or declined.
  • We responded to the webhook with a 2xx status code to tell PayJunction the webhook was successfully received and processed. Read the Important Considerations section under Webhooks for more details.

We know at this point that the payment request was completed on the Smart Terminal, but we still need to get the actual details of the transaction to see if it was approved or if it was declined and for what reason. In our scenario we are assuming that the webhook listener is able to communicate to the API client on the server backend that the webhook was received and to pull the transaction details using the transactionId token:

REQUEST (API Client->PayJunction Server):

GET https://api.payjunctionlabs.com/transactions/126

RESPONSE (PayJunction Server->API Client):

200 OK
{ "transactionId": "126", "uri": "https://api.payjunctionlabs.com/transactions/126", ... , "response": { "approved": true, "code": "00", "message": "Approved", ... }, ... }

You might be wondering why the transaction details are not included in the webhook payload. While PayJunction encourages you to set up a shared secret for webhooks to verify the data payload is coming from PayJunction, there is no authentication performed. Therefore, to protect our merchants' data, the GET request is required.

TIP: First time working with webhooks in a local development environment? We've got you covered.