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 configured 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 configured 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) will not be included in the webhook body. Only the last 4 digits of the PAN and the bin will be included

x-api-key: apikeyvalueforPartnerX

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.

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.

Async Retry is available for:

• Transactions Webhooks
• Statement Ready Webhooks
• Account Updated Webhooks
• ACH Transfer Webhooks
• MRDC Check Deposit Webhooks
• eWallet Webhooks
• Card Updated Webhooks
• Bill Payment
• ATM Pin Update
• NOC Alert
• User Updated Webhooks
• P2P Transfers Webhooks
• Mail Tracking

Note: This retry process is not automatically enabled for partners. It must be explicitly requested through your account liaison team.

Webhook Response Requirements

The partner should return HTTP status codes as follows:

• 4xx and 5xx for errors
• 2xx for successfully received messages
• 503 if the BaaS system needs to retry publishing

Required Response Components

• Required Status Code
• Required Body Format
• Required Response Headers

Required Response Headers

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

Note: The response header should also be called x-GD-RequestId and have the same header value that was provided in the request.

• x-GD-RequestId

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.

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.

Webhooks for API Endpoints

General Transaction Notification

API Call Reference

POST https://yourendpoint.yourcompany.com/events/transactions

Sample Request - Transaction Notification

Note: This is a generalized transactions schema. Certain fields and object groups will be included or excluded, depending on the transactionType. See Transaction Types & Statuses for details.

POST https://yourendpoint.yourcompany.com/events/transactions
Content-Type: application/json
X-GD-RequestId: 977d83e8-84d5-4c3d-98f3-fc0e739ba1ee
x-api-key: apikeyvalueforPartnerX
cache-control: no-cache
User-Agent: PostmanRuntime/7.3.0
Accept: */*
Host: https://yourendpoint.yourcompany.com
accept-encoding: gzip, deflate
content-length: 838
Connection: close
{
   "accounts":[
      {
         "accountIdentifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4c",
         "events":[
            {
               "eventIdentifier":"67659d0f-76db-44b3-a40f-d2df27d2727e",
               "eventType":"transaction",
               "eventDateTime":"2018-09-17T20:50:16.657Z",
               "transactions":[
                  {
                     "parentTransactionIdentifier":"908bd6ce-de70-4f7a-9875-88201aa086a1",
                     "transactionIdentifier":"184f9c51-4e8b-4245-a045-f545e1dd1c5a",
                     "transactionType":"purchase",
                     "transactionStatus":"pending",
                     "accountIdentifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4c",
                     "bin":"4111",
                     "last4Pan":"1234",
                     "currency":"USD",
                     "purses":[
                        {
                           "purseIdentifier":"562a27ec-6cae-4459-a522-be94b4570f78",
                           "purseType":"primary",
                           "availableBalance":0,
                           "ledgerBalance":0,
                           "availableBalanceAsOfDateTime":"2018-09-17T20:50:16.657Z",
                           "ledgerBalanceAsOfDateTime":"2018-09-17T20:50:16.657Z"
                        }
                     ],
                     "postedDateTime":"2018-09-17T20:50:16.657Z",
                     "transactionAmount":10.53,
                     "fees":[
                        {
                           "feeType":"atmWithdrawalFee",
                           "description":"ATM Withdrawal Fee",
                           "amount":2.5,
                           "currency":"USD"
                        }
                     ],
                     "isCredit":true,
                     "networkTransactionData":{
                        "authorizationDateTime":"2018-09-17T20:50:16.658Z",
                        "cashBackAmount":20,
                        "localTransactionData":{
                           "amount":25.34,
                           "currency":"CDN"
                        },
                        "cardAcceptor":{
                           "merchantName":"Acme Gas",
                           "city":"Pasadena",
                           "stateProvReg":"CA"
                        },
                        "authorizedTransactionData":{
                           "holdExpirationDate":"2018-03-03",
                           "declineReason":"insufficientFunds""eci":"eCommerce",
                           "approvalCode":"12345678"
                        }
                     },
                     "postedInternalTransactionData":{
                        "transferIdentifier":"20433e90-0935-4ca1-8beb-ae7de12ef759",
                        "adjustmentType":"provisionalDispute",
                        "description":"Acme Invest",
                        "transferType":"achOut"
                     }
                  }
               ]
            }
         ]
      }
   ]
}

Request Parameters - Transaction Notification

Sample Response Bodies

The following example illustrates how parentTransactionIdentifier is included in responses when partners perform the following:

• Query the status of a transaction.
• Programmatically check transactions periodically against the Transaction API to ensure they are in sync.

Sample Response 1

{
   "totalRecordCount":1,
   "transactions":[
      {
         "paymentIdentifier":"af0b729a-9957-4c7d-96f0-9a7057e44e79",
         "transactionIdentifier":"61ea4be3-7b20-0b7c-e34b-ea61207b7c0b",
         "parentTransactionIdentifier":"67e0695f-1143-02d7-5f69-e0674311d702",
         "transactionType":"purchase",
         "transactionTypeDescription":"Purchase",
         "transactionStatus":"completed",
         "accountIdentifier":"b7c54dfc-225a-40e4-ac89-c65beb699d07",
         "purseIdentifier":"82529298-efbb-45fc-8fd1-24d3fb4fcb93",
         "bin":"424067 ",
         "last4Pan":"5648",
         "currency":"USD",
         "postedDateTime":"2021-08-12T01:08:58Z",
         "transactionAmount":17.5600,
         "isCredit":false,
         "networkTransactionData":{
            "authorizationDateTime":"2021-08-12T01:08:58Z",
            "cashBackAmount":0.0,
            "cardAcceptor":{
               "merchantName":"GreenDot Corporation Vish",
               "merchantIndustryCode":"6011",
               "merchantIndustryCategory":"Service Providers",
               "merchantIndustryDescription":"Financial institutions - automated cash disbursements",
               "city":"E Main Pasadena",
               "stateProvReg":"CA"
            }
         }
      }
   ],
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Sample Response 2

{
   "count":1,
   "pn_results":[
      {
         "ResponseMessage":"Ingested 1 event(s)",
         "RequestMessageToPartner":{
            "accounts":[
               {
                  "events":[
                     {
                        "eventIdentifier":"0189030a-6027-44c5-8f92-3716ccf02298",
                        "eventType":"transaction",
                        "transactions":[
                           {
                              "transactionTypeDescription":"Purchase",
                              "last4Pan":"5648",
                              "postedDateTime":"2021-08-12T01:08:58.000Z",
                              "purses":[
                                 {
                                    "availableBalance":8,
                                    "ledgerBalanceAsOfDateTime":"2021-08-12T01:08:58.000Z",
                                    "ledgerBalance":488.98,
                                    "purseIdentifier":"82529298-efbb-45fc-8fd1-24d3fb4fcb93",
                                    "availableBalanceAsOfDateTime":"2021-08-12T01:08:58.000Z",
                                    "purseType":"primary"
                                 }
                              ],
                              "transactionAmount":17.56,
                              "transactionIdentifier":"6e287cbd-ec4f-0708-bd7c-286e4fec0807",
                              "currency":"USD",
                              "parentTransactionIdentifier":"67e0455f-1143-02d7-5f66-e0672211d702",
                              "isCredit":false,
                              "bin":"424067",
                              "transactionStatus":"pending",
                              "paymentIdentifier":"af0b729a-9957-4c7d-96f0-9a7057e44e79",
                              "accountIdentifier":"b7c54dfc-225a-40e4-ac89-c65beb699d07",
                              "transactionType":"purchase",
                              "networkTransactionData":{
                                 "cashBackAmount":0.01,
                                 "cardAcceptor":{
                                    "merchantIndustryCode":"6011",
                                    "merchantIndustryDescription":"Financial institutions-automated cash disbursements",
                                    "stateProvReg":"CA",
                                    "merchantName":"PTS MTF TEST",
                                    "city":"Pasadena",
                                    "merchantIndustryCategory":"Service Providers"
                                 },
                                 "authorizationDateTime":"2021-08-12T01:08:58.000Z",
                                 "authorizedTransactionData":{
                                    "eci":"none",
                                    "isPartialAuth":false,
                                    "holdExpirationDate":"2021-08-25",
                                    "authStatusIndicator":"I",
                                    "requestAuthorizationAmount":17.56,
                                    "approvalCode":"373087"
                                 }
                              },
                              "userIdentifier":"e10e3cba-bfea-403c-8be9-dc0cd8fd6ca2",
                              "fees":[
                                 {
                                    "currency":"USD",
                                    "amount":0.01,
                                    "feeType":"bankOtcFee",
                                    "description":"Bank OTC Fee"
                                 },
                                 {
                                    "currency":"USD",
                                    "amount":0.03,
                                    "feeType":"bankOtcFee",
                                    "description":"Bank OTC Fee"
                                 },
                                 {
                                    "currency":"USD",
                                    "amount":0.05,
                                    "feeType":"bankOtcFee",
                                    "description":"Bank OTC Fee"
                                 },
                                 {
                                    "currency":"USD",
                                    "amount":0.08,
                                    "feeType":"bankOtcFee",
                                    "description":"Bank OTC Fee"
                                 },
                                 {
                                    "currency":"USD",
                                    "amount":0.13,
                                    "feeType":"bankOtcFee",
                                    "description":"Bank OTC Fee"
                                 }
                              ]
                           }
                        ],
                        "eventDateTime":"2021-08-11T19:08:59.683Z"
                     }
                  ],
                  "accountIdentifier":"b7c54dfc-225a-40e4-ac89-c65beb699d07"
               }
            ]
         },
         "RequestMessage":{
            "transactions":[
               {
                  "transactionTypeDescription":"Purchase",
                  "accountCurrency":"USD",
                  "last4Pan":"5648",
                  "postedDateTime":"2021-08-12T01:08:58.000Z",
                  "purses":[
                     {
                        "availableBalance":8,
                        "ledgerBalanceAsOfDateTime":"2021-08-12T01:08:58.000Z",
                        "ledgerBalance":488.98,
                        "purseIdentifier":"82529298-efbb-45fc-8fd1-24d3fb4fcb93",
                        "availableBalanceAsOfDateTime":"2021-08-12T01:08:58.000Z",
                        "purseType":"primary"
                     }
                  ],
                  "transactionAmount":17.56,
                  "description":"PTS MTF TEST\\Pasadena",
                  "userIdentifier":"e10e3cba-bfea-403c-8be9-dc0cd8fd6ca2",
                  "parentTransactionIdentifier":"67e0695f-1143-02d7-5f44-e0444311d702",
                  "isCredit":false,
                  "bin":"424067",
                  "transactionStatus":"pending",
                  "statusChangedTimestamp":"2021-08-12T01:08:58.000Z",
                  "accountIdentifier":"b7c54dfc-225a-40e4-ac89-c65beb699d07",
                  "programCode":"stash",
                  "transactionType":"purchase",
                  "networkTransactionData":{
                     "cashBackAmount":0.01,
                     "cardAcceptor":{
                        "merchantIndustryCode":"6011",
                        "merchantIndustryDescription":"Financial institutions -automated cash disbursements",
                        "stateProvReg":"CA",
                        "merchantName":"PTS MTF TEST",
                        "city":"Pasadena",
                        "merchantIndustryCategory":"Service Providers"
                     },
                     "authorizationDateTime":"2021-08-12T01:08:58.000Z",
                     "authorizedTransactionData":{
                        "eci":"none",
                        "isPartialAuth":false,
                        "holdExpirationDate":"2021-08-25",
                        "authStatusIndicator":"I",
                        "requestAuthorizationAmount":17.56,
                        "approvalCode":"373087"
                     }
                  },
                  "transactionIdentifier":"6e287cbd-ec4f-0708-bd7c-286e4fec0807",
                  "userProfileId":"fd3f8b5c-8048-46f4-88c5-ec9a4adad024",
                  "fees":[
                     {
                        "currencyCode":"USD",
                        "amount":0.01,
                        "feeType":"bankOtcFee",
                        "description":"Bank OTC Fee"
                     },
                     {
                        "currencyCode":"USD",
                        "amount":0.03,
                        "feeType":"bankOtcFee",
                        "description":"Bank OTC Fee"
                     },
                     {
                        "currencyCode":"USD",
                        "amount":0.05,
                        "feeType":"bankOtcFee",
                        "description":"Bank OTC Fee"
                     },
                     {
                        "currencyCode":"USD",
                        "amount":0.08,
                        "feeType":"bankOtcFee",
                        "description":"Bank OTC Fee"
                     },
                     {
                        "currencyCode":"USD",
                        "amount":0.13,
                        "feeType":"bankOtcFee",
                        "description":"Bank OTC Fee"
                     }
                  ],
                  "paymentIdentifier":"af0b729a-9957-4c7d-96f0-9a7057e44e79"
               }
            ],
            "account":{
               "state":"normal",
               "identifier":"b7c54dfc-225a-40e4-ac89-c65beb699d07",
               "ConsumerProfileKey":1125060,
               "balance":{
                  "currentBalanceAsOfDate":"2021-08-12T01:08:58.000Z",
                  "availableBalance":8,
                  "availableBalanceAsOfDate":"2021-08-12T01:08:58.000Z",
                  "currentBalance":488.98
               },
               "ConsumerProfileIdentifier":"e10e3cba-bfea-403c-8be9-dc0cd8fd6ca2"
            }
         },
         "message":"Publish notification post sent successfully.",
         "PostBackUrl":"https://tsa-webhook.staging.checking.com/events/transactions/tsa",
         "ResponseHttpStatusCode":200,
         "X-GD-RequestId":"11215c52-0e09-45cc-aca2-e319797e32ca",
         "EventType":"transaction"
      }
   ]
}

ACH NOC Alert Webhook

API Call Reference

POST https://yourendpoint.yourcompany.com/events/achNOCAlert

Sample NOC Alert Webhook

{
  "accounts":[
    {
      "accountIdentifier":"4b830092-e5d4-86b8-ad26-8a42c94eee4c",
      "events":[
        {
          "eventIdentifier":"0b830092-e5d4-45b8-ad26-8a42c94fff4c",
          "eventType":"achNOCAlert",
          "eventDateTime":"2020-03-24T22:04:37.441Z",
          "achNOCInfo":{
            "achTransferType":"ACHOut",
            "transferIdentifier":"434c1349-1edb-453b-91c3-69169b4ef3a9",
            "nocCode":"C01",
            --The following properties are all optional and conditional based on the NOC code. See the NOC Code/Request Body Mapping for details.
			"originalCustomerName":"string",
            "correctedFirst15CustomerName":"string",
			"originalRoutingNumber":"123456789",
            "correctedRoutingNumber":"123456789",
            "originalLast4AccountNumber":"9012",
            "correctedLast4AccountNumber":"9013",
            "encryptedAccountData":{
              "version":"string",
              "ephemeralPublicKey":"string",
              "publicKeyHash":"string",
              "data":"string"
            }
          }
        }
      ]
    }
  ]
}

Unencrypted Account Data

Unencrypted Account Data:-
{
  "originalAccountNumber":"123456789012",
  "correctedAccountNumber":"123456789012"
}

NOC Code/Request Body Mapping

NOC Codes

Create eWallet Webhook

API Call Reference

POST https://yourendpoint.yourcompany.com/events/ewallet

Create Bill Payment Webhook

API Call Reference

POST https://yourendpoint.yourcompany.com/events/billPayment

Bill Pay Sample Webhooks

Sample Object:-

BillPayTransfer

{
	[JsonProperty("paymentIdentifier")]
	public string PaymentIdentifier {get; set;}
	[JsonProperty("transferIdentifier")]
	public string TransferIdentifier {get; set;}
	[JsonProperty("transferStatus")]
	public string TransferStatus {get; set;}
	[JsonProperty("payeeIdentifier")]
	public string PayeeIdentifier {get; set;}
	[JsonProperty("payeeName")]
	public string PayeeName {get; set;}
	[JsonProperty("paymentStatus")]
	public string PaymentStatus {get; set;}
	[JsonProperty("amount")]
	public decimal Amount {get; set;}
	[JsonProperty("paymentDate")]
	public string PaymentDate {get; set;}
	[JsonProperty("deliveryDate")]
	public string DeliveryDate {get; set;}
	[JsonProperty("paymentMemo")]
	public string PaymentMemo {get; set;}
	[JsonProperty("note")]
	public string Note {get; set;}
	[JsonProperty("confirmationNumber")]
	public string ConfirmationNumber {get; set;}
}

Sample Webhook - Bill Payment Debit:-

"events":[{
    "eventIdentifier":"694a2279-e800-47c9-867b-d541e06094af",
    "eventType":"billPayTransfer",
    "eventDateTime":"2019-05-29T21:45:36.493Z",
    "billPayTransfer":{
      "paymentIdentifier":"86af4b9f-b9ae-4521-a9c0-218697d96775",
      "transferIdentifier":"16046290-99f8-41ff-8876-0ffad4495794",
      "transferStatus":"completed",
      "payeeIdentifier":"6625fb26-832e-47ae-a1e0-402128a8e218",
      "paymentStatus":"scheduled",
      "amount":5.0,
      "paymentDate":"2020-06-24T18:22:01.285Z",
      "deliveryDate":"2020-07-01T18:22:01.285Z",
      "paymentMemo":"testPayment",
      "note":"test",
      "confirmationNumber":"P53DP-KDFXG",
      "payeeName":"Duquesne Light Company",
      "frequencyType":"“onetime” // onetime",
      "weekly",
      every2Weeks,
      every4Weeks,
      "twiceAMonth",
      "monthly",
      every2Months,
      every4Months,
      every3Months,
      every6Months,
      "annually"
    }
  }
]

Sample Webhook - Bill Payment Transfer Failure:-

{
	"accounts”: [{
		"accountIdentifier":"4f8feff5-9a19-4277-9a6b-663d946d3c91",
		"events": [{
			"eventIdentifier":"01dfc34a-6044-4984-9569-16a344cf2119",
			"eventType":"billPayTransfer",
			"eventDateTime":"2020-07-23T15":"00":51.065Z",
			"billPayTransfer": {
				"paymentIdentifier":"00000000-0000-0000-0000-000000000000",
				"transferIdentifier":"3b6af751-6399-4e87-b9e2-4e7ab0fc508a",
				"transferStatus":"failed",
				"amount":0.0,
				"frequencyType":0
			},
			"accountIdentifier":"4f8feff5-9a19-4277-9a6b-663d946d3c91"\"
		}]
	}]
}

Paper Check Webhook

Paper check Webhooks are sent to notify Partners of paper check clearing statuses.

Note: This Webhook is available only to programs that are configured for Bill Pay. Please contact your Green Dot Liaison to request Bill Pay configuration.

API Call Reference

POST https://yourendpoint.yourcompany.com/events/paperCheck

Sample Webhook Notification

{
  "accounts":[
    {
      "accountIdentifier":"4b830092-e5d4-86b8-ad26-8a42c94eee4c",
      "events":[
        {
          "eventIdentifier":"",
          "eventType":"paperCheck",
          "eventDateTime":"2020-08-06T06:09:25.534Z",
          "transfer":{
            "accountIdentifier":"4b830092-e5d4-86b8-ad26-8a42c94eee4c",
            "firstName":"John",
            "middleName":"Sam",
            "lastName":"Doe",
            "transactionDescription":"transactionTest",
            "eventDateTime":"2015-02-02T18:22:01.285Z",
            "checkNumber":"123456",
            "returnedReason":"returned",
            "associatedTransactionID":"16046290-99f8-41ff-8876-0ffad4495794""transactionAmount":“10.0”
          }
        }
      ]
    }
  ]
}

Mail Tracking Webhook

API Call Reference

POST https://yourendpoint.yourcompany.com/events/mailTracking

After a Physical Card has been Shipped to the Customer

• A payment identifier is included in the Mail Tracking webhook.
• The Mail Tracking webhook will publish event notifications during the following delivery stages:
  • TMM card status of “shipped” will be set upon receipt of a confirmation file from the vendor.
  • TMM card status will be unchanged upon receipt of an in-process file from the vendor.
  • TMM card status of “delivered” will be set upon receipt of an in-home file from the vendor.
  • TMM card status of “returned’ will be set upon receipt of a returned file from the vendor
• The PN will contain the following delivery status information:
  • Last 4 digits of the payment instrument (card)
  • deliveryMethod
  • deliveryMethodCode
    • Note: Allows the processing of mail tracking updates based on delivery method.
  • deliveryStatus
  • deliveryStatusCode containing one of the following:
    • shipped
    • delivered
    • returned
  • trackingNumber (internal only – not intended for release to accountholders)
  • shippedDate
  • estimatedArrivalDate
  • productMaterialType

Delivery Methods and Delivery Method Codes

Sample MailTracking Webhook & Webhook Notification

Sample MailTracking Webhook:-

{[-]
"AccountIdentifier:19185555-aa32-476e-96ac-025d7de9c7af
CallerFilePath:C:\\BuildAgent\\work\\ddd132195e437bb8\\PN\\Services\\PublishNotification\\PublishNotification.Logic\\Publishers\\PublisherBase.cs
 CallerLineNumber:422
 CallerMemberName:ProcessResponseMessage
 ElapsedTimeToPost:668 ms
 EventType:mailTracking
 PostBackUrl:https"::"partnerpc
 RequestMessage":
 {
  "deliveryStatus":
  {
	 "programCode:partnerpc",
	 "accountIdentifier:19185555-aa32-476e-96ed025d7de9e7bf",
	 "last4Pan:7141",
	 "deliveryMethod:Regular",
	 "deliveryMethodCode:reg",
	 "deliveryStatus:Card At Local Post Office",
	 "deliveryStatusCode:delivered",
	 "trackingNumber:0031029826605107792160634369611",
	 "shippedDate:2021-05-03T07:00:00Z",
	 "estimatedArrivalDate:2021-05-07T07:00:00Z",
	 "productMaterialType:moneyvcard",
	 "bin:499998",
	 "cardHolderName:* JOHN***DE JO***DOE",
	 "paymentIdentifier:c3f2b774-7c3x4b15-95db-e0c0f785c122""RequestMessageToPartner":
	 {
	   "accounts":
	   [{
	      "accountIdentifier:19185555-aa32-476e-96ac-025d7de9c7af",
	      "events":
	      [{
	       "eventIdentifier:bc21c571-a6b0-4837-90c2-9f61d51cf269",
	       "eventType:mailTracking",
	       "eventDateTime:2021-05-07T17:06:36.168Z",
	       "deliveryStatus":
	       {
	        "last4Pan:7141",
	        "deliveryMethod:Regular",
	        "deliveryMethodCode:reg",
	        "deliveryStatus:Card At Local Post Office",
	        "trackingNumber:0039999825505106543360637469611",
	        "shippedDate:2021-05-03T07:00:00Z",
	        "estimatedArrivalDate:2021-05-07T07:00:00Z",
	        "productMaterialType:moneyvcard",
	        "deliveryStatusCode:delivered",
	        "bin:499998 ",
	        "cardHolderName:* PE***NS GI***RE",
	        "paymentIdentifier:c3f2b934-7c3a-4b15-95db-e0c0f785c122"
	       }
	      }]
	   ]}
	   ResponseHttpStatusCode:200 
	   ResponseMessage:{
		"success":"true",
		"error":"",
		"tid":"1-6095739c-506beecd3759b01f166e730d"
	 }	 
	SkipPublish:false
	TimeoutOccurred:false
	X-GD-RequestId:5a1dda4f-f8a1-47b1-b3c4-340f876338ae
	level:INFO
	logger:PublishNotificationService
	machineName:PDIN-PN-C3B52
	message:Publish notification post sent successfully.
	threadId:69
	time:2021-05-07 10:06":36.8376
}
Show as raw text
host = pdin-pn-c3b52source = L":\GDC\Logs\PublishNotification\Log2021-05-07.json
sourcetype = bos_publish_notification

Sample Webhook Notification:-

{
  "accounts":
  [{
    "accountIdentifier:4b830092-e5d4-86b8-ad26-8a42c94eee4c",
    "events":
    [{
      "eventIdentifier:0b830092-e5d4-45b8-ad26-8a42c94fff4c",
      "eventType:mailTracking",
      "eventDateTime:2019-09-24T21:46:31.483Z",
      "deliveryStatus":
      {
        "last4Pan:2134",
        "deliverMethod:Regular",
        "deliveryMethodCode:reg",
        "deliveryStatus:Card Returned",
        "deliveryStatusCode:returned",
        "trackingNumber:1038475483854843",
        "shippedDate:2019-09-24T21:46:31.483Z",
        "estimatedArrivalDate:2019-09-24T21:46:31.483Z",
        "productMaterialType:pvc"
      }
    }]
  }]
}

Promotional Webhook

API Call Reference

POST https://yourendpoint.yourcompany.com/events/promotionalTransactions

Webhook – Promotional:-

{
  "accounts":[
    {
      "events":[
        {
          "eventType":"transaction",
          "eventDateTime":"2019-08-27T18:52:21.303Z",
          "transactions":[
            {
              "postedDateTime":"2019-08-27T16:52:20.000Z",
              "isCredit":true,
              "currency":"USD",
              "transactionTypeDescription":"Promotional Credit",
              "parentTransactionIdentifier":"8fd50a5c-cf94-c8d6-5c0a-d58f94cfd6c8",
              "accountIdentifier":"36c90bd4-5cd9-44d2-a591-073c4bc15c29",
              "transactionIdentifier":"8fd50a5c-cf94-c8d6-5c0a-d58f94cfd6c8",
              "transactionType":"promo",
              "purses":[
                {
                  "purseType":"primary",
                  "purseIdentifier":"1809d35f-ad81-4c59-9716-f4a1db8ab66b",
                  "availableBalanceAsOfDateTime":"2019-08-27T16:52:20.000Z",
                  "ledgerBalanceAsOfDateTime":"2019-08-27T16:52:20.000Z",
                  "availableBalance":87.59,
                  "ledgerBalance":971.35
                }
              ],
              "postedInternalTransactionData":{
                "description":"Promotional Credit"
              },
              "transactionAmount":15.35,
              "transactionStatus":"completed"
            }
          ],
          "eventIdentifier":"5b093a1b-45ab-4211-b61a-fdc4ddde69b4"
        }
      ],
      "accountIdentifier":"36c90bd4-5cd9-44d2-a591-073c4bc15c29"
    }
  ]

Webhook - Unknown Adjustment:-

 {
    "accounts":[
      {
        "events":[
          {
            "transactions":[
              {
                "transactionIdentifier":"ca455764-cb89-1680-6457-45ca89cb8016",
                "transactionStatus":"completed",
                "postedDateTime":"2019-08-26T19:59:31.000Z",
                "accountIdentifier":"067425cd-f4d5-48cd-a55b-f7725d423ba3",
                "purses":[
                  {
                    "purseIdentifier":"a453f5c2-aeb9-40b3-a607-c293747dc08b",
                    "availableBalanceAsOfDateTime":"2019-08-26T19:59:31.000Z",
                    "purseType":"primary",
                    "ledgerBalance":264.38,
                    "availableBalance":25.48,
                    "ledgerBalanceAsOfDateTime":"2019-08-26T19:59:31.000Z"
                  }
                ],
                "currency":"USD",
                "parentTransactionIdentifier":"ca455764-cb89-1680-6457-45ca89cb8016",
                "isCredit":true,
                "transactionTypeDescription":"Adjustment",
                "postedInternalTransactionData":{
                  "transferType":"adjustment",
                  "adjustmentType":"unknown",
                  "description":"Merchant Chargeback"
                },
                "transactionType":"adjustment",
                "transactionAmount":36.15
              }
            ],
            "eventIdentifier":"c91fff86-3d5c-4342-838d-651a5d5035f2",
            "eventType":"transaction",
            "eventDateTime":"2019-08-26T21:59:31.907Z"
          }
        ],
        "accountIdentifier":"067425cd-f4d5-48cd-a55b-f7725d423ba3"
      }
    ]
  }

Check Deposit Webhook

API Call Reference

POST https://yourendpoint.yourcompany.com/events/checkDeposit

Sample Webhooks

Webhook - Failed MRDC Transfer:-

{
  "accounts":[
    {
      "events":[
        {
          "eventDateTime":"2019-08-21T21:32:22.303Z",
          "eventIdentifier":"0b284cf9-b33e-4ebd-81b1-844aaee9eb10",
          "transfer":{
            "checkDeposit":{
              "lastChangedDateTime":"2019-08-21T21:32:22Z",
              "checkSubmitDate":"2019-08-21T18:22:01.285Z",
              "checkDepositStatus":"failed",
              "transactionAmount":50.0,
              "checkDepositSubStatus":"failed"
            },
            "transferIdentifier":"06fa213b-bebe-42c3-ba9b-d06a296e66a8"
          },
          "eventType":"checkDeposit"
        }
      ],
      "accountIdentifier":"7eea52f1-5439-4462-93d8-5e291d67dcf6"
    }
  ]
}

MRDC Check Under Review Process - Sample Webhook - Submit Check that is placed under review:-

{
  "accounts":[
    {
      "accountIdentifier":"bbb85a67-8122-4322-829f-f019204c4aaa",
      "events":[
        {
          "eventIdentifier":"444552ba-d029-49a1-895d-55d89cfc8111",
          "eventType":"checkDeposit",
          "eventDateTime":"2019-09-03T20:26:13.007Z",
          "transfer":{
            "transferIdentifier":"555a3fab-5593-4ca7-b008-57feb399f111",
            "checkDeposit":{
              "checkDepositStatus":"review",
              "checkDepositSubStatus":"pendingUserAcceptance",
              "transactionAmount":2800.0,
              "checkSubmitDate":"2019-09-03T18:22:01.285Z"
            }
          }
        }
      ]
    }
  ]
}

Sample Webhook - Update Check when the customer cancels the review:-

{
  "accounts":[
    {
      "accountIdentifier":"bbb85a67-8122-4322-829f-f019204c4aaa",
      "events":[
        {
          "eventIdentifier":"4444e68d-0b0c-49b9-9076-e3ae06fd9111",
          "eventType":"checkDeposit",
          "eventDateTime":"2019-09-03T20:26:28.088Z",
          "transfer":{
            "transferIdentifier":"555a3fab-5593-4ca7-b008-57feb399f111",
            "checkDeposit":{
              "checkDepositStatus":"canceled",
              "checkDepositSubStatus":"canceledByCustomer",
              "transactionAmount":2800.0,
              "checkSubmitDate":"2019-09-03",
              "lastChangedDateTime":"2019-09-03T20:26:28Z"
            }
          }
        }
      ]
    }
  ]
}

Sample Webhook - Update Check when user accepts the review:-

{
  "accounts":[
    {
      "accountIdentifier":"4449e061-b3bb-4582-94a5-43b64de56111",
      "events":[
        {
          "eventIdentifier":"444e036e-6234-42f1-8947-68a62c242111",
          "eventType":"checkDeposit",
          "eventDateTime":"2019-09-03T20:40:01.823Z",
          "transfer":{
            "transferIdentifier":"5550c3a5-ee54-4cbf-878d-b24c6fb0c111",
            "checkDeposit":{
              "checkDepositStatus":"review",
              "checkDepositSubStatus":"pendingAgentReview",
              "transactionAmount":2800.0,
              "checkSubmitDate":"2019-09-03",
              "lastChangedDateTime":"2019-09-03T20:40:01Z"
            }
          }
        }
      ]
    }
  ]
}

Sample Webhook - Update Check when agent accepts the review:-

{
  "accounts":[
    {
      "accountIdentifier":"4449e061-b3bb-4582-94a5-43b64de56111",
      "events":[
        {
          "eventIdentifier":"4441f7e4-b1e9-4af6-83f9-442227dd7111",
          "eventType":"checkDeposit",
          "eventDateTime":"2019-09-03T20:41:36.370Z",
          "transfer":{
            "transferIdentifier":"5550c3a5-ee54-4cbf-878d-b24c6fb0c111",
            "checkDeposit":{
              "checkDepositStatus":"approved",
              "checkDepositSubStatus":"fundsScheduled",
              "fundsAvailableDate":"2019-09-03T18:22:01.285Z",
              "transactionAmount":2800.0,
              "checkSubmitDate":"2019-09-03T18:22:01.285Z",
              "lastChangedDateTime":"2019-09-03T20:41:36Z"
            }
          }
        }
      ]
    }
  ]
}

Sample Webhook - Update Check when agent declines the check:-

{
  "accounts":[
    {
      "accountIdentifier":"1a09d887-6c53-44e3-8180-8e4a7f51ccc7",
      "events":[
        {
          "eventIdentifier":"0ea2cd36-e2fc-440b-a3ca-ade557490a6a",
          "eventType":"checkDeposit",
          "eventDateTime":"2021-03-16T23:00:04.303Z",
          "transfer":{
            "transferIdentifier":"e79a0ff2-8db9-4a81-a7ca-1ca8c87f865c",
            "checkDeposit":{
              "checkDepositStatus":"declined",
              "checkDepositSubStatus":"declinedByAgent",
              "transactionAmount":1111.7,
              "checkSubmitDate":"2021-03-16",
              "lastChangedDateTime":"2021-03-16T23:00:04Z",
              "checkDeclinedDate":"2021-03-16",
              "discardReason":"Third party check"
            }
          }
        }
      ]
    }
  ]
}

Sample Webhook – Returned Checks:-

{
  "accounts":[
    {
      "accountIdentifier":"4f205a81-0d9c-47fa-b47d-71e3f0d2b108",
      "events":[
        {
          "eventIdentifier":"fbb869a4-3799-4389-b3e2-56e8278441d8",
          "eventType":"checkDeposit",
          "eventDateTime":"2020-08-10T18:53:34.886Z",
          "transfer":{
            "transferIdentifier":"20c0cb2a-af75-497f-97e7-afbfc534888d",
            "checkDeposit":{
              "checkDepositStatus":"returned",
              "checkDepositSubStatus":"fundsReversed",
              "transactionAmount":10.0,
              "checkSubmitDate":"2020-08-10T18:22:01.285Z",
              "lastChangedDateTime":"2020-08-10T18:53:34Z",
              "checkReturnedDate":"2020-08-10T18:22:01.285Z",
              "rejectReason":"R01"
            }
          }
        }
      ]
    }
  ]
}

Failed Transfer Webhook

API Call Reference

POST https://yourendpoint.yourcompany.com/events/failedTransfer

Sample Webhook

Sample Failed Transfer Webhook - NSF Failed Retry Transactions:-

When retried transactions fail due to Non-Sufficient Funds ("NSF)",
a failed transfer webhook will be returned containing a reference to the original disbursement.

{
  "accounts":[
    {
      "accountIdentifier":"8ca5c97a-b2fc-4108-a4fa-7f01b556e332",
      "events":[
        {
          "eventIdentifier":"fad0182e-b070-4813-8928-330303695d5d",
          "eventType":"failedTransfer",
          "eventDateTime":"2020-09-17T19:12:17.137Z",
          "transfer":{
            "transferType":"disbursementOut",
            "transferIdentifier":"7383a828-d277-4e0a-927c-e3901a783b12",
            "accountIdentifier":"8ca5c97a-b2fc-4108-a4fa-7f01b556e332",
            "transactionAmount":10.0,
            "transferStatus":"failed",
            "transferStatusReason":"insufficientFunds"
          }
        }
      ]
    }
  ]
}

Event Type: Auto Money Movement (AMM)

An AMM Webhook will be published for:

• ACH In events
• Date Driven events
• Failed AMM events
• Rule expiring reminders (3 days before rule end date)
• Expiration notifications (rule end date or goal amount met)

Sample Webhook Notifications

Sample Webhook Notification – ACH In (P2P):-

{
  "priorityMessage":{
    "programCode":"acme",
    "attributes":[
      {
        "value":"achIn",
        "name":"ruleName"
      },
      {
        "value":"ftXsq",
        "name":"firstName"
      },
      {
        "value":"INRtH",
        "name":"lastName"
      },
      {
        "value":"24.00",
        "name":"amount"
      },
      {
        "value":"2019-08-22T18:22:01.285Z",
        "name":"date"
      },
      {
        "name":"vaultName"
      }
    ],
    "accountIdentifier":"08974d51-e290-4530-b714-2cdf98da9f08",
    "productCode":"40002",
    "contacts":[
      {
        "channelType":"1",
        "contactValue":"8199920733"
      }
    ],
    "notificationType":"57"
  },
  "eventType":"PrioritySend",
  "postBackUrl":"https":"responseMessage":{
    "responseHeader":{
      "statusMessage":"Success",
      "statusCode":"200",
      "responseId":"223c5c1a-8af3-4524-9d7e-f2a3734e9ef1"
    }
  }

Sample Webhook Notification – Date Driven (P2P):-

{
    "priorityMessage":{
      "productCode":"40002",
      "programCode":"acme",
      "contacts":[
        {
          "contactValue":"7573619525",
          "channelType":"1"
        }
      ],
      "accountIdentifier":"177f3011-9c1e-477f-8faa-a3fec6f7dd6b",
      "notificationType":"58",
      "attributes":[
        {
          "value":"dateDriven",
          "name":"ruleName"
        },
        {
          "value":"JYQhG",
          "name":"firstName"
        },
        {
          "value":"bsLoA",
          "name":"lastName"
        },
        {
          "value":"90.00",
          "name":"amount"
        },
        {
          "value":"2019-08-22T18:22:01.285Z",
          "name":"date"
        },
        {
          "name":"vaultName"
        }
      ]
    },
    "postBackUrl":"https://tbd",
    "responseMessage":{
      "responseHeader":{
        "statusCode":"200",
        "responseId":"efc8c44f-974d-465c-bd86-6b94731c762b",
        "statusMessage":"Success"
      }
    },
    "eventType":"prioritySend"
  }
]

Sample Webhook Notification – Failed (Closed account):-

{
  "priorityMessage":{
    "productCode":"40002",
    "programCode":"acme",
    "attributes":[
      {
        "value":"achIn",
        "name":"ruleName"
      },
      {
        "value":"AvYNP",
        "name":"firstName"
      },
      {
        "value":"HaWIQ",
        "name":"lastName"
      },
      {
        "value":"91.00",
        "name":"amount"
      },
      {
        "value":"accountStatus is Closed.",
        "name":"Reason"
      },
      {
        "value":"2019-08-22T18:22:01.285Z ",
        "name":"date"
      },
      {
        "name":"vaultName"
      }
    ],
    "accountIdentifier":"c79aa6fb-20ac-48a3-950c-148b63dd3fd9",
    "contacts":[
      {
        "channelType":"1",
        "contactValue":"4007239942"
      }
    ],
    "notificationType":"59"
  },
  "responseMessage":{
    "responseHeader":{
      "statusMessage":"Success",
      "statusCode":"200",
      "responseId":"4db854fd-b7ff-4c6a-935a-8231ca8a9265"
    }
  },
  "eventType":"prioritySend",
  "postBackUrl":"https://tbd"
 }]
}