Follow

Webhooks

Available Webhooks

Webhooks can be subscribed to via the PayJunction REST API. At the time of writing this guide, there are currently two types of webhooks which can be subscribed to:

  • SMARTTERMINAL_TRANSACTION
  • TRANSACTION_SIGNATURE

Webhooks, like all parts of the API, are tied to the PJMID for an account in PayJunction. If a merchant processes through two different PJMIDs your service will have to subscribe to webhook events for both accounts to receive all data. Multiple webhook subscriptions can be posted to PayJunction for each account and type of webhook if needed.

SMARTTERMINAL_TRANSACTION

This webhook is triggered any time that a transaction is processed through a PayJunction account via the Smart Terminal, regardless of whether the transaction was initiated via the PayJunction REST API or another service, such as our Virtual Terminal web interface.

Example SMARTTERMINAL_TRANSACTION Webhook Payload

{ "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" } }

TRANSACTION_SIGNATURE

This webhook is triggered any time that a transaction is signed on a PayJunction account. As with the SMARTTERMINAL_TRANSACTION webhook, this is sent regardless of whether the transaction was initiated via the PayJunction REST API or another service, such as our Virtual Terminal web interface.

Example TRANSACTION_SIGNATURE Webhook Payload

{ "id": "a7b7f967-d519-4b4c-a5b8-e97347966993", "created": "2016-12-05T18:18:58.674Z', "type": "TRANSACTION_SIGNATURE", "data": { "transactionId": "137" } }

Important Considerations

WEBHOOKS ARE SOURCE AGNOSTIC

As mentioned previously, webhooks are emitted regardless of the source that initiated the transaction or event. This means if you are only interested in processing webhooks for transactions initiated by your software or service you will need to keep track of the requestPaymentId value to match up with the same parameter returned in the SMARTTERMINAL_TRANSACTION data payload and drop any requests with unrecognized requestPaymentId values. TRANSACTION_SIGNATURE webhooks can be referenced by the transactionId.

RESPOND TO A WEBHOOK WITH A SUCCESSFUL HTTP STATUS CODE

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.)
To prevent a flood of redundant webhook data, make sure your listening service responds with a 2xx HTTP status code to tell PayJunction the webhook was consumed successfully.

WEBHOOKS MAY BE RECEIVED MORE THAN ONCE

If the response from the listening service is not received in a timely manner, it is possible to receive the same webhook notice more than once. It is important to consider this when building your listening service and databases.