Receiving API Notifications

Registering Callbacks

Write callbacks within your application to handle Transactive event notifications and use the webhooks endpoint to register/define them with the Transactive API.

Webhook Definition

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

{
"Name": "BigWebhook",
"URL": "https://fooltd.com/myincomingpaymenthook",
"Enabled": true,
"EventType": "Accepted"
}

Available Events

Type Description
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.

Handling Webhook Requests

Webhook Payload

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

{
"EventId": "21yvYJo5QoohZpernmeLsG",
"EventType": "Accepted",
"PaymentId": "21yvYJo5QoohZpernmeLsG",
"PaymentType": "Payout",
"Timestamp": "2016-07-14T15:39:57.049Z"
}

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.

Retry Frequency

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.