Overview

The BaaS platform provides a means for users to receive event notifications at an endpoint hosted by the Partner. Because there are several different transaction events, it is important for the Partner to understand these different events to better understand how to develop against the API.

A Webhook (also referred to as Publish Notifications or PNs) is a messaging mechanism that enables the Partner to receive event notifications as they occur. The BaaS platform sends these event notifications to a webhook endpoint (URL). This endpoint is provided and hosted by the Partner in their environment. The Partner’s environment must be able to receive and process event notifications. Partner endpoints are configured per event type (i.e., transaction, accountUpdated, statementReady, etc.).

Note: Partners can have a different endpoint for each event type or the same endpoint for more than one event type.
The BaaS platform can push webhooks to the Partner’s system in response to a variety of events. An event is an activity that happens outside of the Partner’s system, such as a card transaction at a point-of-sale (POS) terminal or an account status update. Webhooks contain useful information pertinent to the events. For example, a webhook may alert the Partner that a payment instrument was used. The webhook would include details regarding the outcome of the attempted transaction.

For multi-clearing transactions, webhooks will also include posting data. For example, webhooks will be sent as one message with two events (one transaction in each event).

Webhook HTTP Headers

To easily identify Green Dot's traffic, the following three HTTP headers are included in Webhook request messages:

• Accept: application/json, text/plain, text/html
• Accept-Encoding: gzip, deflate
• User-Agent: greendot-baas/3.0.0

Using Webhooks

When a webhook-enabled event occurs, the BaaS platform issues an HTTPS POST containing information about the event to the Partner’s pre-configured endpoint (Webhook URL). The Partner must have an environment able to listen for and process event webhooks to take advantage of this functionality. All webhooks issued to the Partner will include an API Key in the header so the Partner can authenticate Green Dot. The PIE (testing environment) and Product API Keys will still need to be provided to Green Dot via a secure channel.

Note: PCI information (i.e., expiration date, pin, cvv) and SSN will not be included in the webhook body. Only the last 4 digits of the PAN and the bin will be included.

Authentication

GD supports the below authentication types:

• OAuth
• FormOAuth
• PartnerOAuth
• FormUrlEncodedOAuth
• Certificate
• None

Sample Request

curl --location 'https://bank-events.XXXXX.com/api/v1/token' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--data-urlencode 'client_id=CLIENTID' \

--data-urlencode 'client_secret=SECRET' \

--data-urlencode 'grant_type=client_credentials' \

--data-urlencode 'scope=post:webhook'

Sample Response

{

    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6ImdyZWVuZG90IiwiY2xpZW50TmFtZSI6IkdyZWVuZG90IiwiZXhwaXJlc0F0IjoxNzExMDc5NDQyLCJpYXQiOjE3MTEwNzU4NDJ9.aB6-kUtkC6VSYmytggYBQebhnMRgE2FdSgxRZ77w2ms",

    "expires_in": 3600,

    "token_type": "Bearer",

    "scope": "post:webhook"

}

Notifications

The BaaS platform pushes notifications for the following events:

• Transaction Events – Activities such as transaction authorizations and posted transactions.
• Statement Ready Events – When an E-Statement is ready for an account.
• Account Updated Events – Changes to the status of accounts.
• Interest Paid Events – When interest is paid to a purse.
• ACH Transfer Events – When a valid ACH transfer is requested, or the transfer status is updated.
• Failed Transfer Events - When retried transactions fail due to Non-Sufficient Funds (NSF).
• NOC Alert Events – When Green Dot receives ACH Notifications of Change (NOCs) requests for a program.
• User Updated Events – When a user profile is updated (name, address, email or phone).
  Note: Only notifications for the delta changes will be pushed.
• Card Updated Events – When a card is ordered for the first time or as a replacement.
• Check Updated Events – When events such as check declined by agent, check approved by agent, check posted, and check returned occur.
• eWallet Events – When eWallet events occur, such as token activations, token completions and token status updates.
• Bill Payment Events – When events occur, such as a bill payment debit, a failed debit, or a credit due.
• Paper Check Events – When the clearing status of paper checks is updated.
• Paper Check Order Events - When paper check orders are initiated, ordered, declined, or notReceived.
• Mail Tracking Events – During delivery stages of a physical card once it has been mailed.
• Promotional Events - When promotional transactions are processed.
• MRDC Check Deposit Events - When a MRDC check deposit fails.
• P2P Transfer Events – When a person to person transfer is processed.
• ATM Pin Update Events – When a successful ATM pin change is made.
• Auto Money Movement (AMM) Events – When ACH In, date driven, and failed AMM events occur along with rule expiring reminders and expiration notifications.
• Adjustment Final Status Events – When an adjustment has failed all retries.
• Direct Deposit Switch – Events that occur for Green Dot’s Direct DD Switch feature thar helps partners simplify the DD enrollment process.

Note: The partner needs to respond to notifications with an http status code 200 or 201 and a response body that must be a valid json object. The response body can be used by the Partner to provide Green Dot with a correlation Id to help troubleshoot issues.

Retry Failed Webhooks

🚧

This webhook feature must be explicitly requested and configured on a per-partner basis.

If a Partner is configured to use this feature and a webhook fails due to a HTTP Status 5xx or a timeout, then it will be automatically resent on a scheduled basis (initially on an hourly basis, up to 24 hours) until it is successful, or until all attempts have been exhausted.

If a Partner responds to a webhook with a HTTP Status 401 or 403 when the retry processor is executed and the cause of the failed webhook is fixed, then the webhook will be retried and published.

When an HTTP Status 0 is returned or a hard failure is received from a Partner (i.e., All exceptions where no response object is returned, including failure to resolve DNS, failure to connect the endpoint, and SSL errors), the Transaction Webhook will be retried.

This feature can only be configured on release boundaries, as in it can't just be turned on or off and must be tied to a release.

Async Retry is available for all webhooks.

Webhook Response Codes

The following are how GDOT responds to certain HTTP codes:

• 4xx and 5xx for errors
• 2xx for successfully received messages
• 5xx, and 401/403 status codes will be retried by the BaaS system

Sample Response with Required Components

Response HTTP Status Code: 200

{   
  "responseDetails": [
    {       
      "code": 0,       
      "description": "80172fdd-012f-4635-bb4f-dd71a637cc92",
      "subCode": 0     
    }   
  ] 
}

Required Response Headers

Green Dot requires partners to echo back the following header that we send as part of the webhook request.

• x-GD-RequestId

📘

The request and response headers should both include the x-GD-RequestId header.

Response Codes

Webhook Reconciliation Files

The Transaction Webhook Reconciliation file is a daily update sent to Partners to allow reconciliation of webhooks received from Green Dot. Partners configured to use this feature will have access to Green Dot’s Secure File Transfer Protocol (SFTP) server where they will receive a reconciliation file each morning containing the transaction webhooks that were sent to them on the previous day. Reconciliation files can be encrypted depending on the Partner’s configuration.

Note: Contact your Green Dot Representative to request configuration with Transaction Webhook Reconciliation.

Secure File Transfer Protocol Accounts

Green Dot uses SFTP to exchange files with Partners. So, Partners must have a SFTP account on Green Dot’s server to access their daily Transaction Webhook Reconciliation files.

📘

Please note the file is in csv format, but it is encrypted to a pgp file before being dropped on the SFTP. The partner will need appropriate keys to decrypt it.

Transaction Webhook Reconciliation File Specification

The reconciliation file has a human-readable header line that may be ignored. All other lines fit the fixed width specification. The following table contains the fields included in the reconciliation file along with their fixed width specification.

Note: The examples may not be found in the same reconciliation file. Each value is only being used as an example.