Transactions API Endpoints

Obtain Transactions List for an Account

When query parameters are provided, the transactions API lists transactions for a specific account.

Structure of API Call

GET /programs/{programCode}/accounts/{accountIdentifier}/transactions

📘

Transactions History will only show pending and posted (completed or reversed) transactions. Pending will be returned at the top of the result set for current period requests only (i.e., End Date = Today’s Date or End Date not provided).

Visa Mandate

As part of a Visa mandate, merchants must start authorizing merchandise return transactions instead of just force posting them as they have traditionally done. However, they advise that these authorizations should not impact the customer's available balance until the actual posting transaction has come in. Otherwise, there may be a risk of negative balances occuring if the customer uses the funds and the post never comes. Even though this transaction is not impacting the customer's available balance, we still are required to show it in their online history, so that they are aware that the return is in progress.

To indicate which transactions are informational a new optional property, authStatusIndicator, will be included in the authorizedTransactionData object under the Transactions object for both WebHooks and Get Transactions.

If authStatusIndicator is “I” then it is informational only. Other values can be ignored and interpreted to mean that they are reflected in the Available Balance.

Note: Do not rely on the presence of this property for all authorizations. If the property is missing, then it is not Informational only.

Sample Response - Informational Transaction

   "authorizedTransactionData":{
   "authStatusIndicator":"I",
   "holdExpirationDate":"2019-03-25",
   "requestAuthorizationAmount":14.45"eci":"eCommerce",
   "approvalCode":"12345678"
},

Transactions Initiated via an Adjustment API

An adjustmentIdentifier and an adjustment description will be returned via the GET Transactions API for any transactions that are initiated from the Adjustment API.

Example:

• A transaction is initiated via an Adjustment API call.
• The transaction is processed.
• The transaction webhook will include the adjustmentIdentifier under postedInternalTransactionData.
• A GET Transactions API call covering the period of the Adjustment API request will also include the adjustmentIdentifier under postedInternalTransactionData.
• The description returned will be based on the description provided via the Adjustment API.

Sample Response

   "postedInternalTransactionData":{
   "adjustmentIdentifier":"20433e90-0935-4ca1-8beb-ae7de12ef759",
   "description":"Value passed to adjustmentDescription"
}

For additional information on Transaction Webhooks, click here.

For additional information on the Adjustment API, click here.

Request Parameters

Sample Responses

Sample Response - Pending Authorization:-
"transactions":[
   {
      "transactionIdentifier":" 96827a40-2dc8-4b49-bd56-241674be99b6",
      "transactionType":"purchase",
      "transactionTypeDescription":"Purchase",
      "transactionStatus":"pending",
      "accountIdentifier":" 55d416dc-0891-46e8-8a4d-558074c9204f",
      "purseIdentifier":" 9b405f96-ae52-4723-baca-26b810386c96",
      "bin":"413331 ",
      "last4Pan":"4717",
      "currency":"USD",
      "postedDateTime":"2020-01-16T19:26:03Z",
      "transactionAmount":14.45,
      "isCredit":false,
      "networkTransactionData":{
         "authorizationDateTime":"2020-01-16T19:26:03Z",
         "cashBackAmount":0.0,
         "cardAcceptor":{
            "merchantName":"Acme",
            "merchantIndustryCode":"6011",
            "merchantIndustryCategory":"Service Providers",
            "merchantIndustryDescription":"Financial institutions — automated cash disbursements",
            "city":"Pasadena",
            "stateProvReg":"CA"
         },
         "authorizedTransactionData":{
            "holdExpirationDate":"2020-01-30"
         }
      }
   }
],
"responseDetails":[
   {
      "code":0,
      "subCode":0,
      "description":"Success",
      "url":"http://tbd"
   }
]
}

Sample Response – Purchase Completed:-
"transactions":[
   {
      "transactionIdentifier":" f9796733-b547-4260-b4c1-30b897e67d24",
      "transactionType":"purchase",
      "transactionTypeDescription":"Purchase",
      "transactionStatus":"completed",
      "accountIdentifier":" 53dac044-0f47-4b31-beae-c0875151a8a4",
      "purseIdentifier":"f82d6aef-cc5d-4f0b-a18e-921fd8011a32",
      "bin":"413331 ",
      "last4Pan":"4000",
      "currency":"USD",
      "postedDateTime":"2020-01-17T15:17:51Z",
      "transactionAmount":92.49,
      "isCredit":false,
      "networkTransactionData":{
         "authorizationDateTime":"2020-01-16T15:17:51Z",
         "cashBackAmount":0.0,
         "cardAcceptor":{
            "merchantName":"Acme",
            "merchantIndustryCode":"0001",
            "city":"E Main Pasadena",
            "stateProvReg":"CA"
         }
      }
   }
],
"responseDetails":[
   {
      "code":0,
      "subCode":0,
      "description":"Success",
     "url":"http://tbd"
   }
]
}

Sample Response – achIn Completed:-
{
   "transactions":[
      {
         "transactionIdentifier":" 4a0b198f-ad81-4c07-b8ee-6dea5db2a38d",
         "transactionType":"achIn",
         "transactionTypeDescription":"Deposit",
         "transactionStatus":"completed",
         "accountIdentifier":" a6da9d55-5fc5-420b-b4db-0e5fb4610328",
         "purseIdentifier":" 89271e6a-eef2-45cf-a49c-40cc15688ae0",
         "bin":"111111",
         "last4Pan":"1282",
         "currency":"USD",
         "postedDateTime":"2019-12-05T05:23:23Z",
         "transactionAmount":10.0,
         "isCredit":true,
         "postedInternalTransactionData":{
            "achCategoryCode":"uk",
            "description":" Acme Payroll",
            "transferType":"None"
         }
      }
   ],
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Sample Response - Adjustment Made by the Bank:-
Note: Adjustments made directly to an account by the bank have the transactionType, adjustment.

    "transactions":[
   {
      "transactionIdentifier":"7cff644f-aefc-2e50-4f64-ff7cfcae502e",
      "transactionType":"adjustment",
      "transactionTypeDescription":"Adjustment",
      "transactionStatus":"completed",
      "accountIdentifier":"64072e95-7b6a-401f-b5e5-af6378227047",
      "purseIdentifier":"8dde1bcf-2175-40e3-a726-4906edbcfd72",
      "bin":"400798",
      "last4Pan":"8168",
      "currency":"USD",
      "postedDateTime":"2020-01-27T20:20:43Z",
      "transactionAmount":50.0,
      "isCredit":true,
      "postedInternalTransactionData":{
         "transferIdentifier":"064b4d97-b4df-4c1d-8149-e72129c4dfc6",
         "adjustmentType":"provisionalDispute",
         "description":"Dispute Provisional Credit",
         "transferType":"adjustment"
      }
   }
],
"responseDetails":[
   {
      "code":0,
      "subCode":0,
      "description":"Success",
     "url":"http://tbd"
   }
]
}  

Sample Response - Adjustment Made by a Partner:-
Note: The POST /adjustments endpoint requires an adjustmentType to be provided in the request. Therefore, the adjustmentType will be returned for a GET /transactions request as a partnerAdjustmentType under the postedInternalTransactionData node. Adjustments made by a Partner, using the Adjustment API, may have different transactionType values, but will have an adjustmentIdentifier.
{
   "transactions":[
      {
         "transactionIdentifier":" 4b0c978c-8cef-4db2-ae2d-0f8dff996e5d",
         "transactionType":"promo",
         "transactionTypeDescription":"Promotional Credit Reversal",
         "transactionStatus":"reversed",
         "accountIdentifier":"3d6f00f4-9731-4493-b34e-9a76d54008b6",
         "purseIdentifier":"8a8a4844-49d1-45aa-9829-64bc9d40a1e8",
         "bin":"000000",
         "last4Pan":"1111",
         "currency":"USD",
         "postedDateTime":"2020-03-09T01:23:01Z",
         "transactionAmount":2.72,
         "isCredit":false,
         "postedInternalTransactionData":{
            "adjustmentIdentifier":"4f465478-8b6b-4d15-bc0c-b42dd66df2f1",
            "description":"Promotional Credit Reversal",
            "transferType":"None",
            "partnerAdjustmentType":"promoReversal"
         }
      }
   }
],
"responseDetails":[
   {
      "code":0,
      "subCode":0,
      "description":"Success",
      "url":"http://tbd"
   }
]
}

Sample Response - Fee for a Network Transaction:-
{
   "transactions":[
      {
         "transactionIdentifier":"e5709fb9-4a72-4067-b1d6-136506efdcfc",
         "transactionType":"fee",
         "transactionTypeDescription":"Fee",
         "transactionStatus":"completed",
         "accountIdentifier":"f6d95dc8-26c3-449c-8658-2026bc351259",
         "purseIdentifier":"f315b5c0-1112-4e6f-81fc-1462ccb03134",
         "bin":"101200",
         "last4Pan":"4000",
         "currency":"USD",
         "postedDateTime":"2020-01-26T21:33:34Z",
         "transactionAmount":34.64,
         "fee":{
            "description":"Out of Network ATM Withdrawal Fee",
            "amount":34.64,
            "currency":"USD"
         },
         "isCredit":false,
         "postedInternalTransactionData":{
            "description":"Out of Network ATM Withdrawal Fee",
            "transferType":"None"
         }
      }
   ],
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Sample Response - Fee for Internally Generated Transactions:-
{
   "transactions":[
      {
         "transactionIdentifier":"8d6727db-89c0-7029-db27-678dc0892970",
         "transactionType":"fee",
         "transactionTypeDescription":"Fee",
         "transactionStatus":"completed",
         "accountIdentifier":"1d6eb60c-bcfc-4d4a-8efc-55b55d08636c",
         "purseIdentifier":"a0b9bbae-074c-4fa2-a6a2-53810a2d7344",
         "bin":"400798 ",
         "last4Pan":"9018",
         "currency":"USD",
         "postedDateTime":"2020-01-28T16:43:56Z",
         "transactionAmount":0.5,
         "fee":{
            "description":"Instant Transfer Fee",
            "amount":0.5,
            "currency":"USD"
         },
         "isCredit":false,
         "postedInternalTransactionData":{
            "adjustmentIdentifier":"34c9934a-35c7-3dde-b2c1-4c10d08ef3a3",
            "description":"Instant Transfer Fee",
            "transferType":"None"
         }
      }
   ],
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"Success",
         "url":"http://tbd"
      }
   ]
}

Sample Response – Business Accounts:-
"transactions":[
   {
      "paymentIdentifier":"8caf6251-237d-411d-aab5-a9d90aafc773",
      "transactionIdentifier":"6b48c463-52bb-40c5-9a32-d4dfe1538633",
      "transactionType":"achOut",
      "transactionTypeDescription":"Transfer",
      "transactionStatus":"completed",
      "accountIdentifier":"fde3cf88-8e1a-47c5-9a36-f91814e107ff",
      "purseIdentifier":"e49570db-1b02-4a2a-b72e-e441bc383caf",
      "bin":"424500 ",
      "last4Pan":"1111",
      "currency":"USD",
      "postedDateTime":"2020-07-20T17:51:46Z",
      "transactionAmount":5.0000,
      "isCredit":false,
      "postedInternalTransactionData":{
         "transferIdentifier":"54a696d9-294b-41e5-b07f-bae787847bbc",
         "description":"BusinessACHPartne123, GDot Bank (-8878)",
         "bankData":{
            "routingNumber":"090678876",
            "accountNumber":"8878",
            "bankName":"GDot Bank",
            "accountType":"Checking",
            "businessName":"BusinessACHPartne123"
         },
         "transferType":"achOut"
      }
   }
],
"responseDetails":[
   {
      "code":0,
      "subCode":0,
      "description":"Success",
     "url":"http://tbd"
   }
]
}

Response Parameters

Retail Sale and Bank Data

The retailSaleData or bankData will be included in responses received as a result of one of the following transactions:

• cashReload
• eCash
• achOut
• achPull

How it Works

• cashReload and eCash Transactions:
  • When GET /transactions is called and processed, retailSaleData and transferType will be included in the response.

Sample Response (retailSaleData)

"postedInternalTransactionData":{
   "description":"Corner Store 2000, Haltom City TX",
   "transferType":"cashReload",
   "retailSaleData":{
      "city":"Haltom City",
      "state":"TX",
      "merchantName":"Corner Store",
      "storeNumber":"2000"
   }
}

• achOut and achPull Transactions:
  • When GET /transactions is called and processed, bankData and transferType will be included in the response.
  • achPull is distinguished from disbursement using the transferType
  • bankData is unencrypted due to only the last four digits of the accountNumber being displayed

Sample Response (bankData)

"postedInternalTransactionData":{
   "transferIdentifier":"da23e369-b535-4d17-9529-0e65db6736d6",
   "description":"CusTACHPartne020 BaaS, GDot Bank (-4444)",
   "bankData":{
      "routingNumber":"123456789",
      "accountNumber":"4444",
      "bankName":"GDot Bank",
      "firstName":"Jack",
      "lastName":"Jones",
      "accountType":"checking"
   },
   "transferType":"achPull"
}

List Transactions for Specific Savings Purse

This endpoint allows Partners to retrieve a list of transactions for a specific savings purse using the optional purseIdentifier parameter. If a request is submitted including a purseIdentifier, then only transactions for that specific purse will be returned. If a request is submitted without a purseIdentifier, then the primary purse’s transactions will be returned.

Structure of API Call

GET /programs/{programCode}/accounts/{accountIdentifier}/transactions?startDate&endDate&purseIdentifier

Obtain Interest Earned

This endpoint obtains the interest earned on an account.

Structure of API Call

GET /programs/{programCode}/accounts/{accountIdentifier}/purses/{purseIdentifier}/interestEarned

Obtain Direct Deposits Information

This endpoint is used to obtain direct deposit details for a specific account.

Structure of API Call

GET /programs/{programCode}/accounts/{accountIdentifier}/directdeposits

Create Trial Deposit

This endpoint is used to generate a trial deposit transaction for a specific account.

Structure of API Call

POST /programs/{programCode}/accounts/{accountIdentifier}/trialDeposit

Verify Trial Deposit

This endpoint is used to verify the trial deposit transaction for a specific account.

Structure of API Call

POST /programs/{programCode}/accounts/{accountIdentifier}/trialDeposit/verify

Obtain External Bank Accounts

This endpoint is used to access external bank accounts for a specific institution.

Structure of API Call

GET /programs/{programCode}/accounts/{accountIdentifier}/externalBankAccounts

Update External Bank Account Status

This endpoint is used to update the status of a specific external bank account.

Structure of API Call

PUT /programs/{programCode}/accounts/{accountIdentifier}/externalBankAccounts/{externalBankAccountReferenceID}

Transaction Pagination

This API produces a list of transactions and paginates them according to the requested parameters.

Structure of API Call

GET ​/programs​/{programCode}​/accounts​/{accountIdentifier}​/transactions​/pagination

Obtain List of Cashback Rewards Transactions

This API obtains a list of transactions for cashback rewards.

Structure of API Call

GET ​/programs​/{programCode}​/accounts​/{accountIdentifier}​/transactions​/cashBackRewards

Obtain Related Transactions by ID

This API obtains related transactions for a specific account.

Structure of API Call

GET ​/programs​/{programCode}​/accounts​/{accountIdentifier}​/transactions​/relatedTransactions

Appendices

Transaction Types & Statuses

Transactions are originally recorded based on the processor’s time zone then represented by the APIs in UTC. Several of our key processors use Central Time.

• Pending: authorizedTransactionData will be included
• Declined: only returned via the webhook - authorizedTransactionData will be included along with declineReason
• Removed: only returned via the webhook - authorizedTransactionData will be included
• Expired: only returned via the webhook - authorizedTransactionData will be included
• Reversed: transaction has been posted to the customer’s account but is a reversal of a previously completed transaction
• Completed: transaction has been posted to the customer’s account
• Cleared: In multi-clearing publish notifications (PNs), this transaction status Indicates when the outstanding authorization amount has been fully posted.

Transactions – Required Fields & Allowable Values

📘

Refer to Bill Payment Codes for Adjustment Types.

References

• Transaction Types & Statuses
• Fee Types
• Decline Reasons
• Adjustment Types

Valid Characters for Names, Cities, and Addresses

Note: Below is a complete list of characters permitted for customer names.
General Rules
Unicode is disallowed for name fields, address fields, and city fields.

Allowable values for name fields are ascii 32 to 126, with the following exceptions:

• 33-38
• 40-43
• 47
• 58-64
• 91-96
• 123-126

Allowable values for city and address are ascii 32-126 and 192-255, with the following exceptions:

• 33-34
• 36-37
• 42-43
• 58-64
• 91-96
• 123-126
• 215
• 217-220
• 247

Fee Types

🚧

Some of these fee types may not be supported for a program.

• bankOtcFee - Bank OTC Fee (Debit)
• atmBalanceInquiryFee - ATM Balance Inquiry Fee (Debit)
• atmWithdrawalFee - ATM Withdrawal Fee (Debit)
• foreignTransactionFee - Foreign Transaction Fee (Debit)
• payPerUseFee - Pay Per Use Fee (Debit)
• bankOtcFee - Bank OTC Fee Reversal (Credit)
• atmBalanceInquiryFee - ATM Balance Inquiry Fee Reversal (Credit)
• atmWithdrawalFee - ATM Withdrawal Fee Reversal (Credit)
• foreignTransactionFee - Foreign Transaction Fee Reversal (Credit)

Transaction Decline Reasons

• ATC - Application Transaction Counter. The counter results in uniqueness to the cryptograms (ARQC) and provides tracking values for the host verification services, allowing replayed transactions and cloned cards to be identified.
• atcDecline - The transaction counter for the transaction has either been used before or is out of range. If this error persists, contact Customer Service to reset the ATC counter for the card used in the transaction.
• cardStatus - The card used is currently in a status that does not allow transactions. Contact customer service to review the account.
• closedAccount - Closed is a terminal status, so it cannot be reopened at the processor.
• closedCard - May be due to a card being reported lost or stolen or a closed account.
• customerHold - Purchase transactions that are declined because the card can be unpaused by the customer will trigger a webhook to the partner containing this decline reason. The partner will then be able to notify the accountholder that their purchase may be processed if the card used in the transaction is unpaused. Note: Customers should not unpause their cards if the declined transaction is not recognized.
• insufficientFunds - The available funds for the account are less than the purchase amount being authorized.
• invalidAddress - Declined due to AVS mismatch.
  Note: This is not a standard configuration and will not be provided to any partners by default. However, if you are interested, please discuss this feature with your Green Dot representative.
• invalidCVV - The CVV provided does not match the CVV of the card being used.
• invalidExpirationDate - The expiration date provided does not match the expiration date of the active card.
• invalidTransactionData - This is due to a merchant data issue. Often, but not always, the transaction will succeed on a retry.
• other - Fraud related (Do Not Honor, Suspicious or Unusual Activity)
• partialApproval - The purchase was approved for an amount that is less than the requested amount. For example, if the balance on the account is $40.00 and the amount being authorized is $50.00 then a merchant may be configured to approve up to the available balance of $40.00. This is often the case for restaurant purchases.
• transactionNotAllowed - Transaction type is not allowed on the card (i.e., ATM on a temporary card, internet gambling, signature based AFD, etc.). Transactions are not allowed at this specific merchant or purchase not allowed for this country.
• velocityLimitedExceeded - The purchase would cause the account to exceed a velocity limit, such as trying to go over your daily ATM limit in # or $, monthly spend limit, etc.
• wrongPin - The ATM Pin entered did not match the ATM Pin that was last set for the card.
  Note: ATM Pins must be reset whenever a new card with a new card number is issued.

Transaction Alert Recommendations (Webhooks)

Some of the scenarios supported by alerts to the partner include:

• The partner wants to provide real-time balance alerts to the end user. For example, if the balance falls before a certain level, the partner may want to alert the user.
• The partner wants to provide alerts to the users for transactions that are completed or reversed from an external process. For example, ACH Out Reversal, ACH in Completed or Reversed, and Adjustments.
• The partner wants to provide alerts to the users for transactions that are pending. For example, the end user may be alerted of purchases or refunds at the time they are authorized, because they affect Available Balance.
• The partner wants to provide alerts to the users for transactions that are declined.
  Note: The end user is typically not alerted for this status but is an option to consider in discussion with Green Dot during UX reviews.
• The partner wants to provide alerts to the users for transactions that are removed.
  Note: The end user is typically not alerted for this status, but it does update the Available Balance of an account.
• The partner wants to provide alerts to the users for transactions that are expired.
  Note: The end user is typically not alerted for this status, but it does update the Available Balance of an account.

TX ATM Withdrawal with Fee