Webhooks Overview

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

Sub-CodeHTTP Status CodeReference NameDescription
02xxSUCCESSThe operation was successful.
10404NOT_FOUNDResource not found.
100400MALFORMED SCHEMAThe payload could not be loaded.
200400INVALID REQUESTThe request was invalid. See the description for details.
300400REQUIRED PROPERTY MISSING OR MISSING A VALUEA required property (object or scalar) is missing. The property must be provided and contain a value for the type.
350400INVALID DATA TYPEThe data type is invalid. Example: An integer was expected, but an alphanumeric string was provided.
400400INVALID FORMATThe format of the string or number was invalid.
500500INVALID FIELD LENA value was provided that is shorter than the minimum supported length or longer than the maximum supported length.
503503DOWNSTREAM SYSTEM OFFLINE - DO NOT AUTO RETRYA downstream system is unavailable. It may be offline for an extended or unknown period, so the client should not retry automatically.
600400DOWNSTREAM SYSTEM OFFLINE - RETRYA downstream system is unavailable. It may be transient, so the client may retry automatically
610400INVALID ENUM VALUEA value was provided that is not in the set of allowable values.
620400INVALID AMOUNTAn amount was provided that is not valid.
630400INVALID DATE RANGEA date was provided that is not in the allowable date range.
640400INVALID_PROPERTYA property was provided that was not valid given the context of the request.
700400INVALID STRING CHARACTERAn invalid character was provided for a string field.
720400INVALID DATE FORMATInvalid date-format. Must be (ISO_8601): YYYY-MM-DD
725400INVALID UTC DATE TIME FORMATInvalid date-format. Must be (ISO_8601): YYYY-MM-DDTHH:MM:SS.SSSZ. Precision can be from MM to SSS.
730730INVALID DATE TIME FORMAT (non-UTC, timezone unknown)Invalid date-format. Must be (ISO_8601): YYYY-MM-DDTHH:MM:SS.SSS. Precision can be from MM to SSS.
740400INVALID DATE TIME FORMAT (non-UTC, timezone offset known)Invalid date-format. Must be (ISO_8601): YYYY-MM-DDTHH:MM:SS.SSS>±hh:mm. Timezone offset precision can be from HH to MM.
750400INVALID HTTP URL FORMATInvalid HTTP URL format. Must follow Internet standard.
1000200, 201, 202,400INVALID EMAIL FORMATInvalid Email format. Must follow Internet standard.
10602xxVALUE_DOES_NOT_EXISTValue does not exist in the system. This is usually because an invalid object identifier was provided.
n/a5xxDUPLICATE RESOURCEThe resource already exists based on unique identifiers.
n/a5xxGENERAL UNEXPECTED ERRORA catch all for any unexpected system errors.

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.

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.

FieldDescriptionExample
accountIdentifierAccount Identifiere1b7c5b4-14ab-4f64-bf89- 9403a4ba8c4f
eventIdentifierIdentifier for the eventa0c7680f-8e0e-44ad-a7c3- f73cb95c8a08
eventTypeType of eventtransaction
eventDateTimeDate and time of the event2025-03-11 06:46:17.1010000
transactionIdentifierTransaction identifiercf27e0e7-eaf3-4421-93b3- 012fc9ab46aa
parentTransactionIdentifierParent transaction identifier23aeb5fe-102a-47b5-bd95- 856be896cc0e
transactionTypeType of transactionpurchase, adjustment, partnerTransferIn, atmWithdrawal, cashReload
transactionStatusStatus of the transactioncompleted, declined
binBin of the payment instrument (PAN)346596
last4PanLast 4 digits of the payment instrument (PAN)8978
transactionAmountAmount of transaction15.81
currencyCurrency of the transactionUSD
isCreditIs true if credit, false otherwisetrue/false
retrievalReferenceNumberRetrieval Reference Number of a network transaction459272062104469
purseIdentifierPurse Identifier0e8574a0-12ef-4506-918c-c1d7fc93693a
purseTypeType of the purseprimary, savings
availableBalanceAccount available balance50.20
availableBalanceAsOfDateTimeAccount available balance as of date time2025-03-11 06:46:17.1010000
ledgerBalanceAccount ledger balance50.20
ledgerBalanceAsOfDateTimeAccount ledger balance as of date time2025-03-11 06:46:17.1010000
postedDateTimeDate time the network transaction was posted2025-03-11 06:46:17.1010000
feeAmountFee amount1.00
feeCurrencyCurrency of the fee amountUSD
feeTypeType of feebankOTCFee
feeDescriptionDescription of feeBank OTC Fee
authorizationDateTimeDate time of the network AUTH transaction2025-03-10 06:46:17.1010000
cashBackAmountCash back amount, if any2.50
localTransactionAmountTransaction amount in local currency25.12
localTransactionCurrencyLocal transaction currencyCDN
merchantIdMerchant IdentifierMC12412
addressLine1Address of merchant1 Blueberry street
postalCodeZip code of merchant91001
merchantNameMerchant NameStarbucks Inc
merchantCityMerchant cityPasadena
merchantStateProvMerchant stateCA
merchantIndustryCodeMerchant industry code5999, 6011
merchantIndustryCategoryMerchant industry categoryMiscellaneous Stores
merchantIndustryDescriptionMerchant industry descriptionMiscellaneous and speciality retail outlets
authorizationStatusIndicatorAuthorization Status Indicator
holdExpirationDateExpiration date of the Auth hold
declineReasonIf Auth was declined, then the reasonOther
eciEcommerce Indicator
isPartialAuthTrue if auth is partial auth, false otherwisetrue/false
approvalCodeApproval code
transferIdentifierTransfer identifier
adjustmentTypeType of adjustmentprovisionalDispute
descriptionDescription
transferTypeType of transferachPull, swipeReload, adjustment
dpanIdentifierDevice Primary Account Number also known as the "Digital" Primary Account Number is the network token generated by Payment network or Issuing bank to identify Card/Account provisioned in a wallet, for ex. Apple pay, Samsung pay, Google, pay, etc08d9e746-6cda-40b6-84ce-d3be86a48797
fpanIdentifierFunding Primary Account Number) means the number of the actual Account appearing on the physical Card (or similar device) issued by [issuing bank].b337df5f-e056-4ca2-868f-3055b93333a8
parPAR (Payment Account Reference) is a unique, persistent identifier that links all tokens back to the same underlying funding card (PAN - Primary Account Number). In a tokenized environment (e.g., Apple Pay, Google Pay, Samsung Wallet), a single card can have multiple tokens, (i.e.), one per device, per wallet, or merchant and PAR accurately identifies tokens that belong to the same card.V0010013818032485958373336929
last4DpanLast 4 digits of DPan2040
walletName of wallet providerGoogle, Apple, Samsung, etc
tokenStatusStatus of tokenActive
achCategoryCodeAch Category codepr
bankNameBank nameGDot Bank
accountNumberAccount Number used for ACH115608195748333
routingNumberRouting number123456789
firstNameFirst Name
lastNameLast Name
accountTypeAccount typeChecking
transactionTypeDescriptionTransaction type descriptionATM Withdrawal, Cash Deposit
authTypeType of Auth
requestAuthorizationAmountAuthorization amount
localDateTimeLocal Date time
postingDateTimePosting Date time
approvalCodeApproval code
retailMerchantNameRetail Merchant nameWalmart Supercenter
retailStoreNumberRetail store number2252
retailCityRetail CityCentreville
retailStateRetail StateMD
adjustmentIdentifierAdjustment Identifiere1b7c5b4-14ab-4f64-bf89- 9403a4ba8c4f
isMultiClearingIs the Auth a multi-clearing