Receiving API Notifications
Write callbacks within your application to handle Transactive event notifications and use the webhooks endpoint to register/define them with the Transactive API.
For each event of interest, specify the following details, in particular the URL of your callback endpoint that handles it.
- Name - user-supplied
- EventType - the event of interest
- URL - the internet location of your callback endpoint
- Enabled - if enabled
A single callback can handle all of your webhooks (whatever implementation strategy works for you), however every event of interest requires a separate webhook definition (there is no wildcarding on our side).
Example webhook definition JSON
|Accepted||Payment has been successfully submitted to Transactive without validation errors.|
|Rejected||Payment has been rejected for validation errors, either business (insufficient funds) or technical (invalid characters).|
|Submitted||Payment has been successfully transmitted to a banking system for clearing.|
|Executed||Payment has been accepted and acknowledged by a banking system.|
|Reversed||Payment has been rejected by the banking system which executed it, and its associated funds have been returned to the original account.|
|Stopped||Payment is stalled within Transactive, most likely from being submitted too many times.|
|Held||Payment has been held for review
Handling Webhook Requests
Expect to handle the following data in the body of every webhook request:
- EventId - Id of the event
- EventType - type of event
- PaymentId - the payment related to the event
- PaymentType - type of payment
- Timestamp - date and time the event occurred
Example webhook request body JSON
Webhook calls are not signed, and contain no sensitive information. It is up to receiving callbacks to securely query Transactive to get additional event or payment details.
Definition of Success
A Webhook is considered successful by Transactive if it receives an HTTP 200 response from its associated callback URL.
It is possible for a Webhook callback to never succeed. Polling should be used as a backup strategy if you must know that an event has occurred.
In the event that a callback URL does not respond with an HTTP 200 response, Transactive will retry up to the system-wide limit of 5 retries.
IMPORTANT: Your callbacks must be able to recognize and ignore duplicate Webhook requests.