The Green Dot Network (GDN) consists of the following:
Consumption API - Enables partners to authorize and accept cash deposits and payments made by their customers at Green Dot Network retailers. For complete information, refer to the Consumption API section.
Partner Web API - This is a REST API used to stage eCash barcode-based Cash-In transactions by enabling partners to :
Generate eCash barcodes linked to the target account or transaction
obtain lists of retailers
For complete information, refer to the Partner Web API section.
Retail Transaction Simulator - This is a Cash-In Simulation service that simulates a Consumption API call at various retailers for the following transactional simulation features:
Walmart Swipe Reload
CVS Swipe Reload & eCash Load
Walgreens Swipe Reload & eCash Load
Rite Aid Swipe Reload & eCash Load
Kroger Swipe Reload & eCash Load
For complete information, refer to the Retail Transaction Simulator section.
POB Partner API - The POB (Point of Banking) Partner API provides an alternative method to the Consumption API to receive cash deposit transactions to debit card accounts. This API authenticates Green Dot and the Partner, obtains customer information, processes transactions, and returns responses back to the retailer. For complete information, refer to the POB Partner API section.
Store API - This is a REST API that partners use to obtain a list of stores where the specific Cash-In services are available. The results can then be displayed to the users on the Partner’s mobile app or website. The API uses different endpoints to produce a list of stores by:
Zip code
Longitude and latitude
For complete information, refer to the Stores API section.
The Green Dot Network (GDN) APIs allow your company to accept cash at Green Dot’s Retailer Network for a wide range of user cases including:
Cash Deposit to debit cards
Cash top-up to virtual accounts
Bill Payments
Rent payments
Collections payments
Crypto accounts
Many more
Note: If your company uses a processor for your accounts that is already integrated into the GDN, you do not need to integrate to the Consumption API to handle payment authorization and posting.
Our integrated GDN processor partners include:
FIS North
VISA DPS
Galileo
Jack Henry
FIS Direct
FSV
Paysign
Synapse
MCrePower
i2C
The Perfect Processor
Cascade Fintech
First Data
The customer can use two methods to make cash deposits or payments through GDN retailers:
Debit Card Swipe Reload (at the retail point of sale)
eCash Mobile Barcode (cash-in for anything other than debit-card accounts)
Following is a description of each method.
All Green Dot Retailer locations can perform cash deposits to debit cards. To accommodate this, partners have two options for API integration. Following are descriptions of these options and their key differences.
Integration Option 1: Direct Authorization with Green Dot
APIs Used
Consumption API
Key Features
XML API
Directly authorizes and posts funds in response to Green Dot requests triggered by the customer at the point of sale.
The partner approves or declines the deposit in response to the Auth request from Green Dot.
Note: If you approve the Cash Deposit Auth request, you must honor a subsequent Auth Commit call to post funds.
Green Dot may send an Auth Void call if the retailer experiences technical problems with the transaction.
The transaction type is identified.
The Individual retail store information is included in the AuthCommit call.
Partner Requirements
Set up the endpoints to accept the following Green Dot requests:
Auth
Auth Commit
Auth Void
Configure the processing system to:
Determine when to authorize cash deposits when the Auth is received, based on the debit card PAN and amount only.
Post funds when an Auth Commit call is received.
Void a previous Auth call if received.
Provide credentials to access the endpoints you set up, and whitelist Green Dot IP addresses to enable our requests to reach your endpoints successfully.
Pass the individual retail store information in the AuthCommit call.
Settlement Method
Using SFTP protocol, you can directly settle with Green Dot using the Settlement file posted the day after settlement.
Integration Option 2: Lookup to Enable Usage of Debit Network Integration
APIs Used
Point-of-Banking API
Key Features
REST API
To process and approve a cash deposit, the API:
Receives the information lookup call from Green Dot.
Receives the standard funds posting authorization call from the program’s preferred debit or ATM network.
Green Dot only sends an information lookup API call, GET Customer information, then uses that information to send a combined funds authorization and posting call via its connection to the MasterCard Send gateway.
MasterCard Send matches your BIN to the best funds posting channel, which could be Visa OCT, MasterCard MoneySend, NYCE, STAR, and Pulse ATM networks. Note: These networks might already be set up.
Partner Requirements
Configure the processing system to retrieve the information Green Dot needs to use the debit network rails to post funds.
Make available a connection and established process for receiving account credits via the debit networks and configure it to specifically authorize cash deposits.
Settlement Method
Use the existing settle process that the debit networks use to push account credits.
If you seek to accept cash for any purpose other than a cash deposit to a debit card, you need to use an eCash mobile barcode. Many of Green Dot’s leading retailers (including Walmart, 7-Eleven, CVS, Rite Aid, and Walgreens) accept eCash. We are always adding retailers, so please check with your account manager for the latest list of retailers supporting eCash.
Generally, the eCash mobile barcode is generated as a one-time usage transaction and must be generated fresh for each usage. If you require a repeat-usage barcode or need bulk barcodes generated for printed statements, etc., please contact your Green Dot account manager for assistance.
Completing an eCash facilitated cash-in transaction is a two-step process:
The Customer generates an eCash barcode or displays one already provided on their mobile phone to show the retail cashier.
After the customer tenders cash at the retailer, Green Dot authorizes the cash-in transaction with the partner and the funds are posted.
To integrate the eCash Mobile Barcode, there are two options:
Real-time payments
All payments accepted and posted the next day
The following table summarizes the functionality, options, and requirements for integrating to the eCash mobile barcode.
Green Dot issues each partner a secret key used to calculate the digital signature. Calculating each key involves the following steps:
Sorting the headers (except the Signature header) and removing extra spaces around the fields.
Concatenating the headers using a delimiter &.
ASCII encoding the SecretKey.
UTF8 encoding the concatenated header string.
Hashing the string using SHA-256 (use the key as SecretKey). Secret Key is shared between Green Dot and the partner.
Green Dot uses the following C# code to generate the signature.
//sort
var dict = requestHeaderDictionary.OrderBy(t => t.Key).ToList();
//concatenate
var pairs = dict.Where(p => (p.Key != “x-gdn-signature”) && (!string.IsNullOrWhiteSpace(p.Value))).Select(x => string.Format("{0}{1}{2}", x.Key, ":", x.Value));
var concatnatedString = string.Join("&", pairs).ToLower();
var encoding = new ASCIIEncoding();
byte[] secretKeyBytes = encoding.GetBytes(secret);
byte[] signature = Encoding.UTF8.GetBytes(concatnatedString);
using (var hmac = new HMACSHA256(secretKeyBytes))
{
byte[] signatureBytes = hmac.ComputeHash(signature);
return string.Concat(signatureBytes.Select(b => b.ToString("X2")).ToArray());
}
NOTE: Before performing the concatenation/hashing, make sure all characters are converted to lower case and the strings are trimmed (left/right) for the extra white spaces. Do not include headers that have null/empty values.
Following are the steps to generate the digital signature. You may check the results of each step.
//sort
var dict = requestHeaderDictionary.OrderBy(t => t.Key).ToList();
//concatenate
var pairs = dict.Where(p => (p.Key != WebApiRequestHeaders.X_GDN_Signature) && (!string.IsNullOrWhiteSpace(p.Value))).
Select(x => string.Format("{0}{1}{2}", x.Key, ":", x.Value));
var concatenatedString = string.Join("&", pairs).ToLower();
The is x-gdn-channeltype:1&x-gdn-devicetype:2&x-gdn-encryptiontype:1&x- gdn-ipaddress:192.168.1.1&x-gdn-messageid:61aa6e58-b442-4839-8432- 948af2fad3c5&x-gdn-programnumber:bahu-bc2019&x-gdn-timestamp:2020-05- 22t03:07:53z
var encoding = new ASCIIEncoding();
byte[] secretKeyBytes = encoding.GetBytes(secret);
The secret is i4pu7k3y secretKeyBytes.Length is 8
byte[] signature = Encoding.UTF8.GetBytes(concatenatedString);
signature.Length is 211
using (var hmac = new HMACSHA256(secretKeyBytes))
{
byte[] signatureBytes = hmac.ComputeHash(signature);
return string.Concat(signatureBytes.Select(b =>b.ToString("X2")).ToArray());
}
signatureBytes.Length is 32
The x-gdn-signature is
0116eb70450b743f26ccc701f598341f3e6d5b04d50979897571125928d65e8d
<base_response xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://greendotcorp.com/WebServices/Corporate/GDFNReloadServices/">
<gd_response_code>351000019</gd_response_code>
<gd_response_date>2020-05-27T07:32:57.0244211Z</gd_response_date>
<gd_response_message>Invalid X_GDN_Signature</gd_response_message>
<gd_transaction_reference>3b938107-cef0-4515-8e0f- efca6e45d656</gd_transaction_reference>
<partner_transaction_reference i:nil="true" />
</base_response>
Sample Header Input
{
"x-gdn-timestamp": "2020-05-22T03:07:53Z",
"x-gdn-encryptiontype": "1",
"x-gdn-messageid": "61aa6e58-b442-4839-8432-948af2fad3c5",
"x-gdn-channeltype": "1",
"x-gdn-devicetype": "2",
"x-gdn-ipaddress": "192.168.1.1",
"x-gdn-programnumber": "Bahu-BC2019"
}Sample Body Input
{
"gd_retailer_key”: "2433",
"amount”: "22.22"
}Sample Concatendated Values
“x-gdn-channeltype:1&x-gdn-devicetype:2&x-gdn-encryptiontype:1&x-gdn-ipaddress:192.168.1.1&x-gdn-messageid:61aa6e58-b442-4839-8432-948af2fad3c5&x-gdn-programnumber:bahu-bc2019&x-gdn-timestamp:2020-05-22t03:07:53z”
Resulting Signature
Using the sample secret key i4pu7k3y, the resulting hash/signature would be as follows:
0116eb70450b743f26ccc701f598341f3e6d5b04d50979897571125928d65e8d