API Reference

Card Issuing Webhook Notifications

Introduction

The Berkeley Card Issuing application allows our clients to receive real-time payment information through the use of webhooks. Various events will generate real time notifications which will be forwarded as configured (one example use case is to be informed on the most recent status of a Collection). The client can then use the information to trigger another process of their choosing within their own systems.

Process

Setup

In order to subscribe to webhooks you will need to do the following

  • Register a callback URL with the Berkeley Platform, which will receive authorization requests as they are sent from the Payment Card Processor.
    • Contact operations to add this callback url.
    • Operations will also give you the signing key used to validate incoming webhook messages from the Berkeley Platform.

Transaction messages

  • When a transaction message is received from the Card Processor, the Berkeley Platform will forward the message to the callback URL you registered.
  • You should extract the signature from the X-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

1X-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

  1. Extract the body of the request
  2. Compute a HMAC using SHA-256 with the body of the request as the message and the signing key provided by Berkeley as the key.
  3. The value in the header needs to be decoded using base64. The decoded signature from the request header can then be compared to the generated signature from step 2. 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

Event Notification Formats

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

{
  "program_id": XXX, // Integer - ID of program event was fired under
  "event": XXX, // The type of event that happened.
  "event_time": XXX, // DateTime - Time the event was generated within the Berkeley Platform
  "data": {
    ...
  } // Object - Data describing the event
}