INTEGRATION
CHARGES
DISPUTES & FRAUD
Event Notifications
The Silverflow API offers agents a mechanism to subscribe to data events and get notifications of these events delivered to an HTTP(S) endpoint operated by the agent. Event notifications hold just enough information to identify the source, the type of event, the subject identifier and a timestamp. The actual event data is not included. To get the corresponding event data an (authenticated) API call should be used to retrieve the entity referenced in the notification. Data Event Subscriptions are managed through the Event Subscriptions endpoint. Event Subscriptions can be created, updated and archived. Once any of these operations have been completed successfully, a test event will be sent to the target URL provided.
Event Envelope
In an effort to standardise event exchange and improve interoperability between event producers and consumers the CloudEvents initiative has defined a specification for event description. Silverflow uses the CloudEvent envelope for event notification delivery. The listing below shows a sample event notification:
Sample Event Notifications
When an event subscription has been created, modified or deleted, a test event will be sent directly to the target URL provided in the request. The listing below shows a sample test event notification:
Sample Test Event Notifications
Event Notification Versioning
Over time the payload of event notifications may change to support new functionality. The API identifies two types of changes: breaking and non-breaking changes. Non-breaking changes are additions to the payload. As with all API responses these may be added at any time without prior notice. Clients must be able to handle these additions without breaking. Breaking changes are changes to either the structure or the existing attribute names. These changes will break existing clients and would require them to implement the changes. To ensure reliable event delivery and processing on the client side, an Event Subscription will always receive event notifications in the version it had when creating the Event Subscription. Updating an Event Subscription, changing the description
or the targetUrl
attributes will not change the version. However, new Event Subscriptions will always automatically get the latest version of the event notification. This version cannot be changed after creation.
Event Sources
The Silverflow platform supports several sources for event notifications. Please see the API Reference for the most up to date list of event sources.
Reconciliation Events
The Silverflow platform sends the following events from the https://silverflow.com/reconciliation
source:
Type | When |
com.silverflow.reconciliation.detailBatch | A batch of new Reconciliation Details is available through the Reconciliation Details endpoint |
com.silverflow.reconciliation.dailySettlementTotal | New information is available through the Daily Settlement Totals endpoint |
com.silverflow.reconciliation.reconciliationCycleEnd | Cycle |
com.silverflow.reconciliation.networkFundsTransferCompleted | Object Network Funds Transfer with key |
Example com.silverflow.reconciliation.detailBatch
event:
Example com.silverflow.reconciliation.dailySettlementTotal
event:
Example com.silverflow.reconciliation.reconciliationCycleEnd
Mastercard event:
Example com.silverflow.reconciliation.reconciliationCycleEnd
Visa event:
Example com.silverflow.reconciliation.networkFundsTransferCompleted
Visa event:
Currency Rate Events
The Silverflow platform sends the following events from the https://silverflow.com/currencyRates
source:
Type | When |
com.silverflow.currencyRates.update | A new Currency Rate has arrived for specified Card Network that will be active as of effective date |
Example com.silverflow.currencyRates.update
event:
Fraud Notifications Events
The Silverflow platform sends the following events from the https://silverflow.com/fraudNotifications
source:
Type | When |
com.silverflow.fraudNotification.received | A new Fraud Notification has arrived for specified a charge |
Example com.silverflow.fraudNotification.received
event:
Clearing Events
The Silverflow platform sends the following events from the https://silverflow.com/clearing
source:
Type | When |
com.silverflow.clearing.offlineRefundOutcome | An offline refund has been cleared or abandoned. |
Example com.silverflow.clearing.offlineRefundOutcome
event:
Notification Delivery
Event notifications will be delivered to the agent-operated HTTP(S) endpoint specified by target URL of the corresponding Event Subscription. The delivery request uses the following settings:
Setting | Value |
Method |
|
Content-Type |
|
Below is a sample request that the target URL must process:
The delivery is considered successful if an HTTP response with status code in the 2xx
range is received.
Note that the delivery process will follow HTTP redirects
301
,302
,303
,307
and308
for a maximum of 5 times.
Retries
Any returned HTTP status code outside of the 2xx
success range (so 4xx
and 5xx
), connection timeout (30 seconds) or connection failure are considered a delivery failure. When a delivery fails the event notification will be rescheduled for delivery. Rescheduling uses an incremental backoff algorithm to determine the next delivery time. The first delay is 60 seconds
. The following retries are double that of the preceding with a maximum of 12 hours
. Notifications will be attempted to be delivered a total of 36 times
over a period of roughly 320 hours
. When the message cannot be delivered successfully within this timeframe it will be discarded.
At Least Once
Each event notification will be delivered at least once. Under certain (rare) conditions a single event notification may be delivered more than once.If unique events are required they can be deduplicated using their event.id
attribute.
Out of Sequence
Event notifications, including notifications for a single entity, may be delivered out of sequence. Event notifications may be re-ordered using their event.time
attribute.
Asynchronous
The event notification delivery is an asynchronous process. When retrieving the entity referenced in the event notification through the API the entity may already have changed. This may or may not be a problem depending on the use case. To verify that the received event notification still applies to the entity retrieved through the API the event.data.version
and event.data.lastModified
properties of the event notification can be compared with the entity.version
and entity.lastModified
of the retrieved entity. Action can be taken accordingly.
Security Considerations
As described earlier, the event notification is just a notification about an event. The notification itself does not contain any sensitive data and consists solely of meta data and opaque identifiers. The notification should be used as a trigger to fetch the actual referenced data though the Silverflow API. This subsequent call requires the client to authenticate itself to the API using regular authentication means.
Authentication
Event notification only support TLS client certificate for authentication. Which means the subscription endpoint must be HTTPS to support mutual TLS authentication. So it's strongly recommended using HTTPS as subscription endpoint. When creating an Event Subscription through the API, Silverflow does not check if the target url exists, accepts callbacks or is owned/operated by the agent. All Silverflow's event notification certificate is signed by a well known certificate authority, DigiCert, and to identify the Silverflow event notification certificate you should add the DigiCert's certificate to the known certificate authority in your server configuration. The public certificate from DigiCert can be download from their site. The event delivery is with the following CN (common name) in the certificate, which you can authenticate with:
SBX Environment CN=event-delivery.sbx.silverflow.comPRD Environment CN=event-delivery.silverflow.com
Source IP address
Event notification delivery does not use static IP addresses. It is therefore not possible to restrict access to client endpoints using IP filtering.