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-Code | HTTP Status Code | Reference Name | Description |
---|---|---|---|
0 | 2xx | SUCCESS | The operation was successful. |
10 | 404 | NOT_FOUND | Resource not found. |
100 | 400 | MALFORMED SCHEMA | The payload could not be loaded. |
200 | 400 | INVALID REQUEST | The request was invalid. See the description for details. |
300 | 400 | REQUIRED PROPERTY MISSING OR MISSING A VALUE | A required property (object or scalar) is missing. The property must be provided and contain a value for the type. |
350 | 400 | INVALID DATA TYPE | The data type is invalid. Example: An integer was expected, but an alphanumeric string was provided. |
400 | 400 | INVALID FORMAT | The format of the string or number was invalid. |
500 | 500 | INVALID FIELD LEN | A value was provided that is shorter than the minimum supported length or longer than the maximum supported length. |
503 | 503 | DOWNSTREAM SYSTEM OFFLINE - DO NOT AUTO RETRY | A downstream system is unavailable. It may be offline for an extended or unknown period, so the client should not retry automatically. |
600 | 400 | DOWNSTREAM SYSTEM OFFLINE - RETRY | A downstream system is unavailable. It may be transient, so the client may retry automatically |
610 | 400 | INVALID ENUM VALUE | A value was provided that is not in the set of allowable values. |
620 | 400 | INVALID AMOUNT | An amount was provided that is not valid. |
630 | 400 | INVALID DATE RANGE | A date was provided that is not in the allowable date range. |
640 | 400 | INVALID_PROPERTY | A property was provided that was not valid given the context of the request. |
700 | 400 | INVALID STRING CHARACTER | An invalid character was provided for a string field. |
720 | 400 | INVALID DATE FORMAT | Invalid date-format. Must be (ISO_8601): YYYY-MM-DD |
725 | 400 | INVALID UTC DATE TIME FORMAT | Invalid date-format. Must be (ISO_8601): YYYY-MM-DDTHH:MM:SS.SSSZ. Precision can be from MM to SSS. |
730 | 730 | INVALID 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. |
740 | 400 | INVALID 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. |
750 | 400 | INVALID HTTP URL FORMAT | Invalid HTTP URL format. Must follow Internet standard. |
1000 | 200, 201, 202,400 | INVALID EMAIL FORMAT | Invalid Email format. Must follow Internet standard. |
1060 | 2xx | VALUE_DOES_NOT_EXIST | Value does not exist in the system. This is usually because an invalid object identifier was provided. |
n/a | 5xx | DUPLICATE RESOURCE | The resource already exists based on unique identifiers. |
n/a | 5xx | GENERAL UNEXPECTED ERROR | A 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.
Field | Description | Example |
---|---|---|
accountIdentifier | Account Identifier | e1b7c5b4-14ab-4f64-bf89- 9403a4ba8c4f |
eventIdentifier | Identifier for the event | a0c7680f-8e0e-44ad-a7c3- f73cb95c8a08 |
eventType | Type of event | transaction |
eventDateTime | Date and time of the event | 2025-03-11 06:46:17.1010000 |
transactionIdentifier | Transaction identifier | cf27e0e7-eaf3-4421-93b3- 012fc9ab46aa |
parentTransactionIdentifier | Parent transaction identifier | 23aeb5fe-102a-47b5-bd95- 856be896cc0e |
transactionType | Type of transaction | purchase, adjustment, partnerTransferIn, atmWithdrawal, cashReload |
transactionStatus | Status of the transaction | completed, declined |
bin | Bin of the payment instrument (PAN) | 346596 |
last4Pan | Last 4 digits of the payment instrument (PAN) | 8978 |
transactionAmount | Amount of transaction | 15.81 |
currency | Currency of the transaction | USD |
isCredit | Is true if credit, false otherwise | true/false |
retrievalReferenceNumber | Retrieval Reference Number of a network transaction | 459272062104469 |
purseIdentifier | Purse Identifier | 0e8574a0-12ef-4506-918c-c1d7fc93693a |
purseType | Type of the purse | primary, savings |
availableBalance | Account available balance | 50.20 |
availableBalanceAsOfDateTime | Account available balance as of date time | 2025-03-11 06:46:17.1010000 |
ledgerBalance | Account ledger balance | 50.20 |
ledgerBalanceAsOfDateTime | Account ledger balance as of date time | 2025-03-11 06:46:17.1010000 |
postedDateTime | Date time the network transaction was posted | 2025-03-11 06:46:17.1010000 |
feeAmount | Fee amount | 1.00 |
feeCurrency | Currency of the fee amount | USD |
feeType | Type of fee | bankOTCFee |
feeDescription | Description of fee | Bank OTC Fee |
authorizationDateTime | Date time of the network AUTH transaction | 2025-03-10 06:46:17.1010000 |
cashBackAmount | Cash back amount, if any | 2.50 |
localTransactionAmount | Transaction amount in local currency | 25.12 |
localTransactionCurrency | Local transaction currency | CDN |
merchantId | Merchant Identifier | MC12412 |
addressLine1 | Address of merchant | 1 Blueberry street |
postalCode | Zip code of merchant | 91001 |
merchantName | Merchant Name | Starbucks Inc |
merchantCity | Merchant city | Pasadena |
merchantStateProv | Merchant state | CA |
merchantIndustryCode | Merchant industry code | 5999, 6011 |
merchantIndustryCategory | Merchant industry category | Miscellaneous Stores |
merchantIndustryDescription | Merchant industry description | Miscellaneous and speciality retail outlets |
authorizationStatusIndicator | Authorization Status Indicator | |
holdExpirationDate | Expiration date of the Auth hold | |
declineReason | If Auth was declined, then the reason | Other |
eci | Ecommerce Indicator | |
isPartialAuth | True if auth is partial auth, false otherwise | true/false |
approvalCode | Approval code | |
transferIdentifier | Transfer identifier | |
adjustmentType | Type of adjustment | provisionalDispute |
description | Description | |
transferType | Type of transfer | achPull, swipeReload, adjustment |
dpanIdentifier | Device 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, etc | 08d9e746-6cda-40b6-84ce-d3be86a48797 |
fpanIdentifier | Funding 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 |
par | PAR (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 |
last4Dpan | Last 4 digits of DPan | 2040 |
wallet | Name of wallet provider | Google, Apple, Samsung, etc |
tokenStatus | Status of token | Active |
achCategoryCode | Ach Category code | pr |
bankName | Bank name | GDot Bank |
accountNumber | Account Number used for ACH | 115608195748333 |
routingNumber | Routing number | 123456789 |
firstName | First Name | |
lastName | Last Name | |
accountType | Account type | Checking |
transactionTypeDescription | Transaction type description | ATM Withdrawal, Cash Deposit |
authType | Type of Auth | |
requestAuthorizationAmount | Authorization amount | |
localDateTime | Local Date time | |
postingDateTime | Posting Date time | |
approvalCode | Approval code | |
retailMerchantName | Retail Merchant name | Walmart Supercenter |
retailStoreNumber | Retail store number | 2252 |
retailCity | Retail City | Centreville |
retailState | Retail State | MD |
adjustmentIdentifier | Adjustment Identifier | e1b7c5b4-14ab-4f64-bf89- 9403a4ba8c4f |
isMultiClearing | Is the Auth a multi-clearing |
Updated about 11 hours ago