Overview

Clients can subscribe to the webhook notifications to create a HTTP callbacks via a POST request. Once subscribed, the client will receive notifications whenever there is an update to the status of an Interac e-transfer.

Setup on Berkeley side

Register a callback URL with the Berkeley Platform, which will receive email transfer update requests as they are sent from the processor. Contact Berkeley to add/update the callback URL, to retrieve the signing key in order to validate incoming webhook messages and to enable the forwarding of Event Notifications to the callback URL.

Setup on Client side

When an email transfer status message is received from the processor, the Berkeley Platform will forward the message to the callback URL registered.

You should extract the signature from the BPS-Signature header and compare the value to the expected value to ensure the message originated from the Berkeley Platform.

A response is then sent back to the Berkeley Platform acknowledging the receipt of the webhook message.

Message Signatures

Every webhook message received from the Berkeley Platform will contain the following header:

X-BPS-Signature: XXXX

This header is the signature generated by the Berkeley Platform. You will need to use the process described below in order to generate the signature and compare against the value sent in the header.

Signature Generation

The signature can be generated using the following process:

Extract the body of the request
Compute a HMAC using SHA-256 with the body of the request as the message and the signing key received from Berkeley.
The value in the header can then be compared to the generated signature to confirm the message originated from the Berkeley Platform.

NOTE: When comparing the values use a constant time" string comparison” algorithm to protect from certain timing attacks. Timing Attacks are a particular type of attacks that use flaws in code that impact the execution time to discover hints about secrets.

Event Notification Format

The webhook will be sent as a HTTP Post request and the body for each request will follow the the format described below:

{

"id": XXX, // String - Unique ID associated with transaction

"type": XXXX, //String - Transaction Type [push] 

"status": XXXX, //String - Transaction status [awaiting_settlement, declined, canceled, approved] 

“processor_status”: XXXX, //String - Processor Status

"network": XXXX, //String - Transaction Network [etransfer]

"currency": XXXX, //String - Transaction currency [CAD]

"amount": XXXX, // Integer - Transaction amount in cents. Ex, 499 -> $4.99

"action_message": "No action code found", // String - Action code to be configured in future version

"action_code": "action_code_not_found" // String - Action code to be configured in future version

}

Expected Berkeley Transaction Statuses

The following are the statuses for “status” which are the Berkeley statuses:

awaiting_settlement: This status is a flattened status so it could represent any of the following 3 statuses - The transaction has been created and waiting to send it to the bank or the transaction has been sent to the bank and waiting for the bank response or awaiting to be accepted by the recipient.
declined: The transaction is failed for wrong information, rejected from the bank, non-sufficient funds, etc.
cancelled: The transaction is marked as a cancel from the user.
approved: The transaction has been completed and the funds have been released.

Expected Processor Transaction Statuses

The following are the statuses for “processor_status”:

pending: The transaction has been created and waiting to send it to the bank.
in progress: The transaction has been sent to the bank and waiting for the bank response.
sent: e-Transfer email sent to recipient.
failed: The transaction is failed for wrong information, rejected from the bank, non-sufficient funds, etc.
cancelled: The transaction is marked as a cancel from the user.
successful: The transaction has been completed and the funds have been released.